Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Handling Apple Events

Writing Apple Event Handlers

For each Apple event your application supports, you must provide a function called an Apple event handler. The AEProcessAppleEvent function calls one of your Apple event handlers when it processes an Apple event. Your Apple event handlers should perform any action requested by the Apple event, add parameters to the reply Apple event if appropriate, and return a result code.

The Apple Event Manager uses dispatch tables to route Apple events to the appropriate Apple event handler. You must supply an Apple event handler for each entry in your application's Apple event dispatch table. Each handler must be a function that uses this syntax:

FUNCTION MyEventHandler (theAppleEvent: AppleEvent; 
                         reply: AppleEvent; 
                         handlerRefcon: LongInt): OSErr; 

The parameter theAppleEvent is the Apple event to handle. Your handler uses Apple Event Manager functions to extract any parameters and attributes from the Apple event and then performs the necessary processing. If any of the parameters include object specifier records, your handler should call AEResolve to resolve them--that is, to locate the Apple event objects they describe. For more information, see the chapter "Resolving and Creating Object Specifier Records" in this book.

The reply parameter is the default reply provided by the Apple Event Manager. ("Replying to an Apple Event," which begins on page 4-36, describes how to add parameters to the default reply.) The handlerRefcon parameter is the reference constant stored in the Apple event dispatch table entry for the Apple event. Your handler can check the reference constant, if necessary, for information about the Apple event.

You can use the reference constant for anything you wish. For example, if you want to use the same handler for several Apple events, you can install entries for each event in your application's Apple event dispatch table that specify the same handler but different reference constants. Your handler can then use the reference constant to distinguish the different Apple events it handles.

To provide an Apple event handler in C, be sure to include the Pascal declaration before the handler declaration. This is the syntax for an Apple event handler in C:

pascal OSErr MyEventHandler (const AppleEvent *theAppleEvent, 
                             const AppleEvent *reply, 
                             long handlerRefcon);

After extracting all known parameters from the Apple event, every handler should determine whether the Apple event contains any further required parameters. Your handler can determine whether it retrieved all the required parameters by checking whether the keyMissedKeywordAttr attribute exists. If the attribute exists, then your handler has not retrieved all the required parameters and should immediately return an error. If the attribute does not exist, then the Apple event does not contain any more required parameters, although it may contain additional optional parameters.

The Apple Event Manager determines which parameters are optional according to the keywords listed in the keyOptionalKeywordAttr attribute. The source application is responsible for adding these keywords to the keyOptionalKeywordAttr attribute, but is not required to do so, even if that parameter is listed in the Apple Event Registry: Standard Suites as an optional parameter. If the source application does not add the necessary keyword to the keyOptionalKeywordAttr attribute, the target application treats the parameter as required for that Apple event. If the target application supports the parameter, it should handle the Apple event as the source application expects. If the target application does not support the parameter and checks whether it has received all the required parameters, it finds that there's another parameter that the client application considered required, and should return the result code errAEParamMissed without attempting to handle the event.

Listing 4-11 shows a function that checks for a keyMissedKeywordAttr attribute. A handler calls this function after getting all the required parameters it knows about from an Apple event.

Listing 4-11 A function that checks for a keyMissedKeywordAttr attribute

FUNCTION MyGotRequiredParams (theAppleEvent: AppleEvent): OSErr;
VAR
   myErr:            OSErr;
   returnedType:     DescType;
   actualSize:       Size;
BEGIN
   myErr := AEGetAttributePtr(theAppleEvent, 
                               keyMissedKeywordAttr, 
                               typeWildCard, returnedType, 
                               NIL, 0, actualSize);
   IF myErr = errAEDescNotFound THEN 
      {you got all the required parameters}
      MyGotRequiredParams := noErr
   ELSE IF myErr = noErr THEN        
      {you missed a required parameter}
      MyGotRequiredParams := errAEParamMissed;
END;

The code in Listing 4-11 uses the AEGetAttributePtr function to get the keyMissedKeywordAttr attribute. This attribute contains the first required parameter, if any, that your handler didn't retrieve. If AEGetAttributePtr returns the errAEDescNotFound result code, the Apple event doesn't contain a keyMissedKeywordAttr attribute. If the Apple event doesn't contain this attribute, then your handler has extracted all of the parameters that the client application considered required.

If the AEGetAttributePtr function returns noErr as the result code, then the attribute does exist, meaning that your handler has not extracted all of the required parameters. In this case, your handler should return an error and not process the Apple event.

The first remaining required parameter is specified by the data of the keyMissedKeywordAttr attribute. If you want this data returned, specify a buffer to hold the data. Otherwise, specify NIL as the buffer and 0 as the size of the buffer. If you specify a buffer to hold the data, you can check the value of the actualSize parameter to see if the data is larger than the buffer you allocated.

For more information about specifying Apple event parameters as optional or required, see "Specifying Optional Parameters for an Apple Event" beginning on page 5-7.