Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Interapplication Communication /: Chapter 4 - Responding to Apple Events / Handling Apple Events

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 the AEGetParamDesc 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, or AEGetAttributeDesc 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 the typeLongInteger 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, specify typeWildCard 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 specify typeWildCard 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 use AEGetParamPtr 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 use AEResolve 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 about AEResolve 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, or AEGetAttributeDesc function to get the data out of an Apple event.

Getting Data Out of an Apple Event Parameter
You can use the AEGetParamPtr or AEGetParamDesc function to get the data out of an Apple event parameter. Use the AEGetParamPtr function (or the AEGetKeyPtr function, which works the same way) to return the data contained in a parameter. Use the AEGetParamDesc 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. The AEGetParamPtr 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, the keyDirectObject keyword specifies that the AEGetParamPtr function should extract information from the direct parameter; AEGetParamPtr returns the data in the buffer specified by the sectionH 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 the sectionH variable to identify the subscriber and read in the information from the edition.
In this example, the AEGetParamPtr function returns, in the returnedType 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 as typeWildCard. If the coercion fails, the Apple Event Manager returns the errAECoercionFail result code.
The AEGetParamPtr function returns, in the actualSize 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 the AEGetParamDesc 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 the AEGetParamDesc function to extract data that is of variable length. The AEGetParamDesc 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. The AEGetParamDesc 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 variable theAppleEvent contains the desired parameter. The keyDirectObject keyword specifies that the AEGetParamDesc function should get the descriptor record of the direct parameter. The typeAEList descriptor type specifies that the descriptor record should be returned as a descriptor list. In this example, the AEGetParamDesc function returns a descriptor list in the docList 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 the AEGetNthPtr 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 from AEGetParamDesc, you must dispose of it by calling the AEDisposeDesc 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 the AEGetAttributePtr or AEGetAttributeDesc 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. The AEGetAttributePtr 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); 
The keyEventSourceAttr keyword specifies the attribute from which to get the data. The typeShortInteger descriptor type specifies that the data should be returned as a short integer; the returnedType 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. The AEGetAttributePtr function returns, in the actualSize 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 that AEGetAttributePtr 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 the sourceOfAE 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 type AEEventSource.
TYPE AEEventSource = (kAEUnknownSource, kAEDirectCall, 
                      kAESameProcess, kAELocalProcess, 
                      kAERemoteProcess);
The constants defined by the data type AEEventSource have the following meanings:
Constant Meaning
kAEUnknownSource Source of Apple event unknown
kAEDirectCall A direct call that bypassed the PPC Toolbox
kAESameProcess Target application is also the source application
kAELocalProcess Source application is another process on the same computer as the target application
kAERemoteProcess Source application is a process on a remote computer on the network

The next example shows how to use the AEGetAttributePtr function to get data out of the keyMissedKeywordAttr attribute. After your handler extracts all known parameters from an Apple event, it should check whether the keyMissedKeywordAttr attribute exists. If it does, then your handler did not get all of the required parameters.
Note that if AEGetAttributePtr returns the errAEDescNotFound result code, then the keyMissedKeywordAttr attribute does not exist--that is, your application has extracted all of the required parameters. If AEGetAttributePtr returns noErr, then the keyMissedKeywordAttr 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 the keyMissedKeywordAttr 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, specify NIL 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 the keyAddressAttr 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);
The keyAddressAttr keyword specifies the attribute to get the data from. The typeTargetID descriptor type specifies that the data should be returned as a target ID record; the returnedType variable contains the actual descriptor type that is returned. You can examine the address returned in the addressOfAE 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 the GetProcessSerialNumberFromPortName function. You can then pass the process serial number to the GetProcessInformation 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 the AECountItems function to count the number of items in a descriptor list, and you can use AEGetNthDesc or AEGetNthPtr 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 use AECountItems 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);
The AEGetParamDesc function returns, in the docList variable, a copy of the descriptor list from the direct parameter of the Open Documents event. You specify this list to the AECountItems 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 the AEGetNthPtr or AEGetNthDesc 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. The AEGetNthPtr 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);
The docList variable specifies the descriptor list from the direct parameter of the Open Documents event. The index variable specifies the index of the descriptor record to extract. You can use the typeFSS 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. The AEGetNthPtr function returns the keyword of the parameter and the descriptor type of the resulting data in the keywd and returnedType 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 the actualSize 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);  

Constant	Meaning
kAEUnknownSource	Source of Apple event unknown
kAEDirectCall	A direct call that bypassed the PPC Toolbox
kAESameProcess	Target application is also the source application
kAELocalProcess	Source application is another process on the same computer as the target application
kAERemoteProcess	Source application is a process on a remote computer on the network