![]() |
AEProcessAppleEvent |
||||
Header: | AEInteraction.h | Carbon status: | Supported | |
Calls the handler, if one exists, for a specified Apple event.
OSErr AEProcessAppleEvent ( const EventRecord *theEventRecord );
A pointer to the event record for the Apple event to process.
A result code. This is the error result from the Apple event handler (or errAEHandlerNotFound). In most cases your application should ignore this error because it will be seen by the Apple event sender as the keyErrorNumber parameter in the reply.
After receiving a high-level event (and optionally determining whether it is a type of high-level event other than an Apple event that your application might support), your application typically calls the AEProcessAppleEvent function to determine the type of Apple event received and call the corresponding handler.
The AEProcessAppleEvent function looks first in the applications special handler dispatch table for an entry that was installed by the AEInstallSpecialHandler function with the constant keyPreDispatch. If the applications special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, AEProcessAppleEvent looks in the applications Apple event dispatch table for an entry that matches the event class and event ID of the specified Apple event. You install handlers in the applications dispatch table with the AEInstallEventHandler function.
If the applications Apple event dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, the AEProcessAppleEvent function looks in the system special handler dispatch table for an entry that was installed with the constant keyPreDispatch. If the system special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, AEProcessAppleEvent looks in the system Apple event dispatch table for an entry that matches the event class and event ID of the specified Apple event.
If the system Apple event dispatch table does not include such a handler, the Apple Event Manager returns the result code errAEEventNotHandled to the server (or target) application and, if the client application is waiting for a reply, to the client application.
If AEProcessAppleEvent finds an entry in one of the dispatch tables that matches the event class and event ID of the specified Apple event, it calls the corresponding handler.
If an Apple event dispatch table contains one entry for an event class and a specific event ID, and also contains another entry that specifies a wildcard value for either the event class or the event ID, the Apple Event Manager uses the more specific entry. For example, if one entry specifies an event class of kAECoreSuite and an event ID of kAEDelete and another entry specifies an event class of kAECoreSuite and an event ID of typeWildCard, the Apple Event Manager will dispatch an Apple event with an event ID of kAEDelete to the handler from the entry that specifies the event ID as kAEDelete.
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 Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)