Important: The information in this document is obsolete and should not be used for new development.
Getting Data Out of an Apple Event
The Apple Event Manager stores the parameters and attributes of an Apple event in a format that is internal to the Apple Event Manager. You use Apple Event Manager functions to retrieve the data from an Apple event and return it to your application in a format your application can use.Most of the functions that retrieve data from Apple event parameters and attributes are available in two forms: one that returns the desired data in a specified buffer and one that returns a descriptor record containing the same data. For example, the
AEGetParamPtr
function uses a specified buffer to return the data contained in an Apple event parameter, and theAEGetParamDesc
function returns the descriptor record for a specified parameter.You can also use Apple Event Manager functions to get data out of descriptor records, descriptor lists, and AE records. You use similar functions to put data into descriptor records, descriptor lists, and AE records.
When your handler receives an Apple event, you typically use the
AEGetParamPtr
,AEGetAttributePtr
,AEGetParamDesc
, orAEGetAttributeDesc
function to get the data out of the Apple event.Some Apple Event Manager functions let your application request that the data be returned using any descriptor type, even if it is different from the original descriptor type. If the original data is of a different descriptor type, the Apple Event Manager attempts to coerce the data to the requested descriptor type.
For example, the
AEGetParamPtr
function lets you specify the desired descriptor type of the resulting data as follows:
VAR theAppleEvent: AppleEvent; returnedType: DescType; multResult: LongInt; actualSize: Size; myErr: OSErr; myErr := AEGetParamPtr(theAppleEvent, keyMultResult, typeLongInteger, returnedType, @multResult, SizeOf(multResult), actualSize);In this example, the desired type is specified in the third parameter by thetypeLongInteger
descriptor type. This requests that the Apple Event Manager coerce the data to a long integer if it is not already of this type. To prevent coercion and ensure that the descriptor type of the result is of the same type as the original, specifytypeWildCard
for the third parameter.The Apple Event Manager returns, in the
returnedType
parameter, the descriptor type of the resulting data. This is useful information when you specifytypeWildCard
as the desired descriptor type; you can determine the descriptor type of the resulting data by examining this parameter.The Apple Event Manager can coerce many different types of data. For example, the Apple Event Manager can convert alias records to file system specification records, integers to Boolean data types, and characters to numeric data types, in addition to other data type conversions. For a complete list of the data types for which the Apple Event Manager provides coercion handling, see Table 4-1 on page 4-45.
To perform data coercions that the Apple Event Manager doesn't perform, you can provide your own coercion handlers. See "Writing and Installing Coercion Handlers," which begins on page 4-41, for information on providing your own coercion handlers.
Apple event parameters are keyword-specified descriptor records. You can use
AEGetParamDesc
to get the descriptor record of a parameter, or you can useAEGetParamPtr
to get the data out of the descriptor record of a parameter. If an Apple event parameter consists of an object specifier record, you can useAEResolve
and your own object accessor functions to resolve the object specifier record--that is, to locate the Apple event object it describes. For more information aboutAEResolve
and object accessor functions, see "Writing Object Accessor Functions," which begins on page 6-28. Attributes are also keyword-specified descriptor records, and you can use similar routines to get the descriptor record of an attribute or to get the data out of an attribute.The following sections show how to use the
AEGetParamPtr
,AEGetAttributePtr
,AEGetParamDesc
, orAEGetAttributeDesc
function to get the data out of an Apple event.Getting Data Out of an Apple Event Parameter
You can use theAEGetParamPtr
orAEGetParamDesc
function to get the data out of an Apple event parameter. Use theAEGetParamPtr
function (or theAEGetKeyPtr
function, which works the same way) to return the data contained in a parameter. Use theAEGetParamDesc
function when you need to get the descriptor record of a parameter or to extract the descriptor list from a parameter.For example, suppose you need to get the data out of a Section Read event. The Edition Manager sends your application a Section Read event to tell your application to read updated information from an edition into the specified subscriber. The direct parameter of the Apple event contains a handle to the section record of the subscriber. You can use the
AEGetParamPtr
function to get the data out of the Apple event.You specify the Apple event that contains the desired parameter, the keyword of the desired parameter, the descriptor type the function should use to return the data, a buffer to store the data, and the size of this buffer as parameters to the
AEGetParamPtr
function. TheAEGetParamPtr
function returns the descriptor type of the resulting data and the actual size of the data, and it places the requested data in the specified buffer.
VAR sectionH: SectionHandle; theAppleEvent: AppleEvent; returnedType: DescType; actualSize: Size; myErr: OSErr; myErr := AEGetParamPtr(theAppleEvent, keyDirectObject, typeSectionH, returnedType, @sectionH, SizeOf(sectionH), actualSize);In this example, thekeyDirectObject
keyword specifies that theAEGetParamPtr
function should extract information from the direct parameter;AEGetParamPtr
returns the data in the buffer specified by thesectionH
variable.You can request that the Apple Event Manager return the data using the descriptor type of the original data or you can request that the Apple Event Manager coerce the data into a descriptor type that is different from the original. To prevent coercion, specify the desired descriptor type as
typeWildCard
.The
typeSectionH
descriptor type specifies that the returned data should be coerced to a handle to a section record. You can use the information returned in thesectionH
variable to identify the subscriber and read in the information from the edition.In this example, the
AEGetParamPtr
function returns, in thereturnedType
variable, the descriptor type of the resulting data. The descriptor type of the resulting data matches the requested descriptor type unless the Apple Event Manager wasn't able to coerce the data to the specified descriptor type or you specified the desired descriptor type astypeWildCard
. If the coercion fails, the Apple Event Manager returns theerrAECoercionFail
result code.The
AEGetParamPtr
function returns, in theactualSize
variable, the actual size of the data (that is, the size of coerced data, if any coercion was performed). If the value returned in this variable is greater than the amount your application allocated for the buffer to hold the returned data, your application can increase the size of its buffer to this amount, and get the data again. You can also choose to use theAEGetParamDesc
function when your application doesn't know the size of the data.In general, use the
AEGetParamPtr
function to extract data that is of fixed length or known maximum length, and theAEGetParamDesc
function to extract data that is of variable length. TheAEGetParamDesc
function returns the descriptor record for an Apple event parameter. This function is useful, for example, for extracting a descriptor list from a parameter.You specify, as parameters to
AEGetParamDesc
, the Apple event that contains the desired parameter, the keyword of the desired parameter, the descriptor type the function should use to return the descriptor record, and a buffer to store the returned descriptor record. TheAEGetParamDesc
function returns the descriptor record using the specified descriptor type.For example, the direct parameter of the Open Documents event contains a descriptor list that specifies the documents to open. You can use the
AEGetParamDesc
function to get the descriptor list out of the direct parameter.
VAR docList: AEDescList; theAppleEvent: AppleEvent; myErr: OSErr; myErr := AEGetParamDesc(theAppleEvent, keyDirectObject, typeAEList, docList);In this example, the Apple event specified by the variabletheAppleEvent
contains the desired parameter. ThekeyDirectObject
keyword specifies that theAEGetParamDesc
function should get the descriptor record of the direct parameter. ThetypeAEList
descriptor type specifies that the descriptor record should be returned as a descriptor list. In this example, theAEGetParamDesc
function returns a descriptor list in thedocList
variable.The descriptor list contains a list of descriptor records. To get the descriptor records and their data out of a descriptor list, use the
AECountItems
function to find the number of descriptor records in the list and then make repetitive calls to theAEGetNthPtr
function to get the data out of each descriptor record. See "Getting Data Out of a Descriptor List" on page 4-31 for more information.Note that the
AEGetParamDesc
function copies the descriptor record from the parameter. When you're done with a descriptor record that you obtained fromAEGetParamDesc
, you must dispose of it by calling theAEDisposeDesc
function.If an Apple event parameter consists of an object specifier record, you can use
AEResolve
to resolve the object specifier record (that is, locate the Apple event object it describes), as explained in "Finding Apple Event Objects" on page 3-38.Getting Data Out of an Attribute
You can use theAEGetAttributePtr
orAEGetAttributeDesc
function to get the data out of the attributes of an Apple event.You specify, as parameters to
AEGetAttributePtr
, the Apple event that contains the desired attribute, the keyword of the desired attribute, the descriptor type the function should use to return the data, a buffer to store the data, and the size of this buffer. TheAEGetAttributePtr
function returns the descriptor type of the returned data and the actual size of the data and places the requested data in the specified buffer.For example, this code gets the data out of the
keyEventSourceAttr
attribute of an Apple event.
VAR theAppleEvent: AppleEvent; returnedType: DescType; sourceOfAE: Integer; actualSize: Size; myErr: OSErr; myErr := AEGetAttributePtr(theAppleEvent, keyEventSourceAttr, typeShortInteger, returnedType, @sourceOfAE, SizeOf(sourceOfAE), actualSize);ThekeyEventSourceAttr
keyword specifies the attribute from which to get the data. ThetypeShortInteger
descriptor type specifies that the data should be returned as a short integer; thereturnedType
variable contains the actual descriptor type that is returned. You also must specify a buffer to hold the returned data and specify the size of this buffer. If the data is not already a short integer, the Apple Event Manager coerces it as necessary before returning it. TheAEGetAttributePtr
function returns, in theactualSize
variable, the actual size of the returned data after coercion has taken place. You can check this value to make sure you got all the data.As with the
AEGetParamPtr
function, you can request thatAEGetAttributePtr
return the data using the descriptor type of the original data, or you can request that the Apple Event Manager coerce the data into a descriptor type that is different from the original.In this example, the
AEGetAttributePtr
function returns the requested data as a short integer in thesourceOfAE
variable, and you can get information about the source of the Apple event by examining this value. You can test the returned value against the values defined by the data typeAEEventSource
.
TYPE AEEventSource = (kAEUnknownSource, kAEDirectCall, kAESameProcess, kAELocalProcess, kAERemoteProcess);The constants defined by the data typeAEEventSource
have the following meanings:The next example shows how to use the
AEGetAttributePtr
function to get data out of thekeyMissedKeywordAttr
attribute. After your handler extracts all known parameters from an Apple event, it should check whether thekeyMissedKeywordAttr
attribute exists. If it does, then your handler did not get all of the required parameters.Note that if
AEGetAttributePtr
returns theerrAEDescNotFound
result code, then thekeyMissedKeywordAttr
attribute does not exist--that is, your application has extracted all of the required parameters. IfAEGetAttributePtr
returnsnoErr
, then thekeyMissedKeywordAttr
attribute does exist--that is, your handler did not get all of the required parameters.
myErr := AEGetAttributePtr(theAppleEvent, keyMissedKeywordAttr, typeWildCard, returnedType, NIL, 0, actualSize);The data in thekeyMissedKeywordAttr
attribute contains the keyword of the first required parameter, if any, that your handler didn't retrieve. If you want this data returned, specify a buffer to hold it and specify the buffer size. Otherwise, as in this example, specifyNIL
as the buffer and 0 as the size of the buffer.This example shows how to use the
AEGetAttributePtr
function to get the address of the sender of an Apple event from thekeyAddressAttr
attribute of the Apple event:
VAR theAppleEvent: AppleEvent; returnedType: DescType; addressOfAE: TargetID; actualSize: Size; myErr: OSErr; myErr := AEGetAttributePtr(theAppleEvent, keyAddressAttr, typeTargetID, returnedType, @addressOfAE, SizeOf(addressOfAE), actualSize);ThekeyAddressAttr
keyword specifies the attribute to get the data from. ThetypeTargetID
descriptor type specifies that the data should be returned as a target ID record; thereturnedType
variable contains the actual descriptor type that is returned. You can examine the address returned in theaddressOfAE
variable to determine the sender of the Apple event.The target ID record returned in the
addressOfAE
variable contains the sender's port name, port location, and session reference number. To get the process serial number for a process on the local machine, pass the port name returned in the target ID record to theGetProcessSerialNumberFromPortName
function. You can then pass the process serial number to theGetProcessInformation
function to find the creator signature for a given process. (For more information about these functions, see the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials.)For more information about target addresses, see "Specifying a Target Address" on page 5-10.
Getting Data Out of a Descriptor List
You can use theAECountItems
function to count the number of items in a descriptor list, and you can useAEGetNthDesc
orAEGetNthPtr
to get a descriptor record or its data out of a descriptor list.The Open Documents event contains a direct parameter that specifies the list of documents to open. The list of documents is contained in a descriptor list. After extracting the descriptor list from the parameter, you can determine the number of items in the list and then extract each descriptor record from the descriptor list. See Figure 3-9 on page 3-16 for a depiction of the Open Documents event.
For example, when your handler receives an Open Documents event, you can use the
AEGetParamDesc
function to return the direct parameter as a descriptor list. You can then useAECountItems
to return the number of descriptor records in the list.
VAR theAppleEvent: AppleEvent; docList: AEDescList; itemsInList: LongInt; myErr: OSErr; myErr := AEGetParamDesc(theAppleEvent, keyDirectObject, typeAEList, docList); myErr := AECountItems(docList, itemsInList);TheAEGetParamDesc
function returns, in thedocList
variable, a copy of the descriptor list from the direct parameter of the Open Documents event. You specify this list to theAECountItems
function.You specify the descriptor list whose items you want to count in the first parameter to
AECountItems
. The Apple Event Manager returns, in the second parameter, the number of items in the list. When extracting the descriptor records from a list, you often use the number of items as a loop index. Here's an example:
FOR index := 1 TO itemsInList DO BEGIN {for each descriptor record in the list, get its data} END;The format of the descriptor records in a descriptor list is private to the Apple Event Manager. You must use theAEGetNthPtr
orAEGetNthDesc
function to extract descriptor records from a descriptor list.You specify the descriptor list that contains the desired descriptor records and an index as parameters to the
AEGetNthPtr
function. The index represents a specific descriptor record in the descriptor list. TheAEGetNthPtr
function returns the data for the descriptor record represented by the specified index.You also specify the descriptor type the function should use to return the data, a buffer to store the data, and the size of this buffer. If the specified descriptor record exists, the
AEGetNthPtr
function returns the keyword of the parameter, the descriptor type of the returned data, and the actual size of the data, and it places the requested data in the specified buffer.Here's an example that uses the
AEGetNthPtr
function to extract an item from the descriptor list in the direct parameter of the Open Documents event:
myErr := AEGetNthPtr(docList, index, typeFSS, keywd, returnedType, @myFSS, Sizeof(myFSS), actualSize);ThedocList
variable specifies the descriptor list from the direct parameter of the Open Documents event. Theindex
variable specifies the index of the descriptor record to extract. You can use thetypeFSS
descriptor type, as in this example, to specify that the data be returned as a file system specification record. The Apple Event Manager automatically coerces the original data type of the descriptor record from an alias record to a file system specification record. TheAEGetNthPtr
function returns the keyword of the parameter and the descriptor type of the resulting data in thekeywd
andreturnedType
variables, respectively.You also specify a buffer to hold the desired data and the size (in bytes) of the buffer. In this example, the
myFSS
variable specifies the buffer. The function returns the actual size of the data in theactualSize
variable. If this size is larger than the size of the buffer you provided, you know that you didn't get all of the data for the descriptor record.Listing 4-10 shows a more complete example of extracting the items from a descriptor list in the Open Documents event.
Listing 4-10 Extracting items from a descriptor list
VAR index: LongInt; itemsInList: LongInt; docList: AEDescList; keywd: AEKeyword; returnedType: DescType; myFSS: FSSpec; actualSize: Size; myErr: OSErr; FOR index := 1 TO itemsInList DO BEGIN myErr := AEGetNthPtr(docList, index, typeFSS, keywd, returnedType, @myFSS, Sizeof(myFSS), actualSize); IF myErr <> noErr THEN DoError(myErr); myErr := MyOpenFile(@myFSS); IF myErr <> noErr THEN DoError(myErr); END; myErr := AEDisposeDesc(docList);