Carbon


AEProcessAppleEvent

Header: AEInteraction.h Carbon status: Supported

Calls the handler, if one exists, for a specified Apple event.

OSErr AEProcessAppleEvent (
    const EventRecord *theEventRecord
);
theEventRecord

A pointer to the event record for the Apple event to process.

function result

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.

DISCUSSION

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 application’s special handler dispatch table for an entry that was installed by the AEInstallSpecialHandler function with the constant keyPreDispatch. If the application’s special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, AEProcessAppleEvent looks in the application’s 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 application’s dispatch table with the AEInstallEventHandler function.

If the application’s 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.

VERSION NOTES

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 events—this won’t necessarily work. See “Apple Event Dispatching” (to be supplied later) for more information.

AVAILABILITY

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)