Legacy Document

Inside Macintosh: Interapplication Communication /

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

Routines for Responding to Apple Events / Dispatching Apple Events

AEProcessAppleEvent

You can use the AEProcessAppleEvent function to call the appropriate handler for a specified Apple event.

FUNCTION AEProcessAppleEvent 
                        (theEventRecord: EventRecord): OSErr;

theEventRecord

The event record for the Apple event.

DESCRIPTION

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

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, the function 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 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.

SPECIAL CONSIDERATIONS

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.

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough room in heap zone
bufferIsSmall	-607	Buffer is too small
noOutstandingHLE	-608	No outstanding high-level event
errAECorruptData	-1702	Data in an Apple event could not be read
errAENewerVersion	-1706	Need a newer version of the Apple Event Manager
errAEEventNotHandled	-1708	Event wasn't handled by an Apple event handler

SEE ALSO

For an example of the use of AEProcessAppleEvent, see Listing 4-2 on page 4-6.

For a description of an Apple event handler, see page 4-105.

For more information about event processing, see the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials.