![]() |
AEInstallEventHandler |
||||
Header: | AppleEvents.h | Carbon status: | Supported | |
Adds an entry for an event handler to an Apple event dispatch table.
OSErr AEInstallEventHandler ( AEEventClass theAEEventClass, AEEventID theAEEventID, AEEventHandlerUPP handler, SInt32 handlerRefcon, Boolean isSysHandler );
The event class for the Apple event or events to dispatch to this event handler. The Discussion section describes interactions between this parameter and the theAEEventID parameter.
The event ID for the Apple event or events to dispatch to this event handler. The Discussion section describes interactions between this parameter and the theAEEventClass parameter.
A universal procedure pointer to the Apple event handler function to install.
A reference constant. The Apple Event Manager passes this value to the handler each time it calls it. If your handler doesnt expect a reference constant, pass 0 for this parameter.
Specifies the Apple event dispatch table to add the handler to. Pass TRUE to add the handler to the system dispatch table or FALSE to add the handler to your applications dispatch table. See Platform Considerations for related information.
A result code.
The parameters theAEEventClass and theAEEventID specify the event class and event ID of the Apple events handled by the handler for this dispatch table entry. If there is already an entry in the specified dispatch table for the same event class and event ID, it is replaced. For these parameters, you must provide one of the following combinations:
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 an Apple event dispatch table contains one entry for an event class and a specific event ID, and also contains another entry that is identical except that it specifies a wildcard value for either the event class or the event ID, the Apple Event Manager dispatches the more specific entry. For example, if an Apple event dispatch table includes one entry that specifies the event class as kAECoreSuite and the event ID as kAEDelete, and another entry that specifies the event class as kAECoreSuite and the event ID as typeWildCard, the Apple Event Manager dispatches the Apple event handler associated with the entry that specifies the event ID as kAEDelete.
In addition to the Apple event handler dispatch tables, applications can add entries to special handler dispatch tables, as described in Managing Special Handler Dispatch Tables.
A Carbon application should not install a handler in a system dispatch table with the goal that the handler will get called when other applications receive eventsthis wont necessarily work. See Apple Event Dispatching (to be supplied later) for more information.
Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.
© 2000 Apple Computer, Inc. (Last Updated 5/8/2000)