Selected Apple Event Manager Functions (original) (raw)
This appendix provides a table of functions that you use to work with the data in Apple event data structures. For complete descriptions of these functions (and the underlying data types), see Apple Event Manager Reference.
Functions for Working With Apple Event Data Structures
Figure A-1 shows the hierarchy for key Apple event data structures. An Apple Event Manager function that operates on one of these data structures can also operate on any type that inherits from it. For example, the same function that works on a descriptor (AEDesc) also works on a descriptor list (AEDescList).
Figure A-1 Hierarchy of Apple event data structures
However, if there is a specific function for working with a data type, you should use that function. For example, because AppleEvent inherits from AEDesc, it is theoretically possible to create an Apple event with the AECreateDesc function (assuming you have access to the raw data for the Apple event). However, you should instead use the AEBuild function or the AECreateAppleEvent function, which are designed specifically for creating Apple events. For information on using these functions, see Two Approaches to Creating an Apple Event.
Table A-1 shows some of the functions the Apple Event Manager provides for working with Apple event data structures. Functions listed for structure types higher in the table also work for types lower in the table, though as noted, you should generally use the most specific function available for a type. For structures that are stored by key value (such as Apple event attributes and parameters), you typically use a function that accesses data by key, rather than by index.
Some functions have both a pointer and a descriptor version (for example, AECoerceDesc and AECoercePtr). The pointer version works with data in a pointed to buffer, while the descriptor version works with data that is in a descriptor.
Table A-1 Functions for working with Apple event data structures
| Data type | Operation | Function |
|---|---|---|
| Descriptor(AEdesc) | create | AECreateDesc, AEBuildDesc |
| dispose of | AEDisposeDesc | |
| get data | AEGetDescData, AEGetDescDataSize,AEGetDescDataRange (valid for AEDesc types only) | |
| set data | AEReplaceDescData | |
| coerce | AECoerceDesc, AECoercePtr | |
| Descriptor list(AEDescList) | create | AECreateList |
| count | AECountItems | |
| get by index (base 1) | AEGetNthDesc, AEGetNthPtr | |
| delete by index (base 1) | AEDeleteItem | |
| put | AEPutDesc, AEPutPtr, AEBuildDesc | |
| Apple event record(AERecord) | get by key | AEGetKeyDesc, AEGetKeyPtr |
| delete by key | AEDeleteKeyDesc | |
| put by key | AEPutKeyDesc, AEPutKeyPtr | |
| Apple event(AppleEvent) | create | AECreateAppleEvent,AEBuildAppleEvent |
| get by parameter | AEGetParamDesc, AEGetParamPtr | |
| get by attribute | AEGetAttributeDesc, AEGetAttributePtr | |
| delete by parameter | AEDeleteParam | |
| put by parameter | AEPutParamDesc, AEPutParamPtr, AEBuildParameters | |
| put by attribute | AEPutAttributeDesc, AEPutAttributePtr, AEBuildParameters |
For the following functions, you can specify the descriptor type of the resulting data; if the actual descriptor type of the attribute or parameter is different from the specified type, the Apple Event Manager attempts to coerce it to the specified type:
AEGetParamPtrAEGetParamDescAEGetAttributePtrAEGetAttributeDescAEGetNthPtrAEGetNthDesc