Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Reference to Responding to Apple Events

Routines for Responding to Apple Events / Creating and Managing the Apple Event Dispatch Tables

AEInstallEventHandler

You can use the AEInstallEventHandler function to add an entry to either your application's Apple event dispatch table or the system Apple event dispatch table.

FUNCTION AEInstallEventHandler (theAEEventClass: AEEventClass;
                                theAEEventID: AEEventID; 
                                handler: EventHandlerProcPtr; 
                                handlerRefcon: LongInt;
                                isSysHandler: Boolean): OSErr;

theAEEventClass

The event class for the Apple event or events to be dispatched for this entry. The AEEventClass data type is defined as a four-character code:

            TYPE AEEventClass = PACKED ARRAY[1..4] OF Char;

theAEEventID

The event ID for the Apple event or events to be dispatched for this entry. The AEEventID data type is defined as a four-character code:

            TYPE AEEventID = PACKED ARRAY[1..4] OF Char;

handler

A pointer to an Apple event handler for this dispatch table entry. Note that a handler in the system dispatch table must reside in the system heap; this means that if the value of the isSysHandler parameter is TRUE, the handler parameter should point to a location in the system heap. Otherwise, if you put your system handler code in your application heap, you must use AERemoveEventHandler to remove the handler before your application terminates.

handlerRefcon

A reference constant that is passed by the Apple Event Manager to the handler each time the handler is called. If your handler doesn't use a reference constant, use 0 as the value of this parameter.

isSysHandler

Specifies the dispatch table to which you want to add the handler. If the value of isSysHandler is TRUE, the Apple Event Manager adds the handler to the system Apple event dispatch table. Entries in the system dispatch table are available to all applications. If the value of isSysHandler is FALSE, the Apple Event Manager adds the handler to your application's Apple event dispatch table. The application's dispatch table is searched first; the system dispatch table is searched only if the necessary handler is not found in your application's dispatch table.

DESCRIPTION

The AEInstallEventHandler function creates an entry in the Apple event dispatch table. You must supply parameters that specify the event class, the event ID, the address of the handler that handles Apple events of the specified event class and event ID, and whether the handler is to be added to the system Apple event dispatch table or your application's Apple event dispatch table. You can also specify a reference constant that the Apple Event Manager passes to your handler whenever your handler processes an Apple event.

The parameters theAEEventClass and theAEEventID specify the event class and event ID of the Apple events to be handled by the handler for this dispatch table entry. For these parameters, you must provide one of the following combinations:

• the event class and event ID of a single Apple event to be dispatched to the handler
• the typeWildCard constant for theAEEventClass and an event ID for theAEEventID, which indicate that Apple events from all event classes whose event IDs match theAEEventID should be dispatched to the handler
• an event class for theAEEventClass and the typeWildCard constant for theAEEventID, which indicate that all events from the specified event class should be dispatched to the handler
• the typeWildCard constant for both the theAEEventClass and theAEEventID parameters, which indicates that all Apple events should be dispatched to the handler

IMPORTANT

If you use the typeWildCard constant for either the theAEEventClass or the theAEEventID parameter (or for both parameters), the corresponding handler must return the error errAEEventNotHandled if it does not handle a particular event.

If there was already an entry in the specified dispatch table for the same event class and event ID, it is replaced. Therefore, before installing a handler for a particular Apple event in the system dispatch table, use the AEGetEventHandler function (described next) to determine whether the table already contains a handler for that event. If an entry exists, AEGetEventHandler returns a reference constant and a pointer to that event handler. Chain the existing handler to your handler by providing pointers to the previous handler and its reference constant in the handlerRefcon parameter of AEInstallEventHandler. When your handler is done, use these pointers to call the previous handler. If you remove your system Apple event handler, be sure to reinstall the chained handler.

SPECIAL CONSIDERATIONS

Before an application calls a system Apple event handler, system software has set up the A5 register for the calling application. For this reason, if you provide a system Apple event handler, it should never use A5 global variables or anything that depends on a particular context; otherwise, the application that calls the system handler may crash.

RESULT CODES

noErr	0	No error
paramErr	-50	Parameter error (handler pointer is NIL or odd)
memFullErr	-108	Not enough room in heap zone

SEE ALSO

For more information about installing Apple event handlers, see "Installing Entries in the Apple Event Dispatch Tables," which begins on page 4-7.