![]() |
AEGetArray |
||||
Header: | AEDataModel.h | Carbon status: | Supported | |
Extracts data from an Apple event array created with the AEPutArray function and stores it as a standard array of fixed size items in the specified buffer.
OSErr AEGetArray ( const AEDescList *theAEDescList, AEArrayType arrayType, AEArrayDataPointer arrayPtr, Size maximumSize, DescType *itemType, Size *itemSize, SInt32 *itemCount );
A pointer to the descriptor list to get the array from. If the array is of type kAEDataArray, kAEPackedArray, or kAEHandleArray, the descriptor list must be factored. A factored descriptor list is one in which the Apple Event Manager automatically isolates the data that is common to all the elements of the list so that the common data only appears in the list once. To create a factored descriptor list, you call the AECreateList function and specify the data that is common to all elements in the descriptor array. See the Discussion section for related information.
The Apple event array type to convert. Pass one of the constants: described in
A pointer to a buffer, allocated and disposed of by your application, for storing the array. The size in bytes must be at least as large as the value you pass in the maximumSize parameter. On return, the buffer contains the array of fixed-size items.
The maximum length, in bytes, of the expected data. The AEGetArray function will not return more data than you specify in this parameter.
A pointer to a descriptor type. On return, for arrays of type kAEDataArray, kAEPackedArray, or kAEHandleArray, the descriptor type of the items in the returned array. The AEGetArray function doesnt supply a value in itemType for arrays of type kAEDescArray and kAEKeyDescArray because they may contain descriptor records of different types. Possible descriptor types are listed in
A pointer to a size variable. On return, for arrays of type kAEDataArray or kAEPackedArray, the size (in bytes) of each item in the returned array. You dont get an item size for arrays of type kAEDescArray, kAEKeyDescArray, or kAEHandleArray because descriptor records and handles (though not the data they point to) have a known size.
A pointer to a size variable. On return, the number of items in the returned array.
A result code.
The AEGetArray function uses a buffer identified by the pointer in the arrayPtr parameter to store the converted data for the Apple event array specified by the theAEDescList parameter. For example, AEGetArray may convert an array of descriptor records of type typeLongInteger into a simple array of integer values or an array of descriptor records of type typeFSS into an array of file specification records.
Even if the descriptor list that contains the array is factored, the converted data for each array item includes the data common to all the descriptor records in the list. The Apple Event Manager automatically reconstructs the common data for each item when you call AEGetArray.
For information about creating and factoring descriptor lists for Apple event arrays, see AECreateList. For information about adding an Apple event array to a descriptor list, see AEPutArray.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)