Legacy Document

Inside Macintosh: Interapplication Communication /

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

Application-Defined Routines /

MyEventHandler

An Apple event handler has the following syntax:

FUNCTION MyEventHandler (theAppleEvent: AppleEvent; 
                         reply: AppleEvent; 
                         handlerRefcon: LongInt): OSErr;

theAppleEvent

The Apple event to handle.

reply

The default reply Apple event provided by the Apple Event Manager.

handlerRefcon

The reference constant stored in the Apple event dispatch table for the Apple event.

DESCRIPTION

An Apple event handler should extract any parameters and attributes from the Apple event, perform the requested action, and add parameters to the reply Apple event if appropriate.

Your handler should always set its function result to noErr if it successfully handles the Apple event. If an error occurs, your handler should return either errAEEventNotHandled or some other nonzero result code. If the error occurs because your application cannot understand the event, return errAEEventNotHandled, in case a handler in the system special handler or system Apple event dispatch tables might be able to handle the event. If the error occurs because the event is impossible to handle as specified, return the result code returned by whatever function caused the failure, or whatever other result code is appropriate.

For example, suppose your application receives a Get Data event that requests the name of the current printer, and your application cannot handle such an event. In this situation, you should return errAEEventNotHandled in case another handler available to the Apple Event Manager can handle the event. This strategy allows users to take advantage of system capabilities from within your application via system handlers.

However, if your application cannot handle a Get Data event that requests the fifth paragraph in a document because the document contains only four paragraphs, you should return some other nonzero error, because further attempts to handle the event are pointless.

If your Apple event handler calls the AEResolve function and AEResolve calls an object accessor function in the system object accessor dispatch table, your Apple event handler may not recognize the descriptor type of the token returned by the function. In this case, your handler should return the result code errAEUnknownObjectType. When your handler returns this result code, the Apple Event Manager attempts to locate a system Apple event handler that can recognize the token.

SEE ALSO

For more information about Apple event handlers, see "Writing Apple Event Handlers" on page 4-33.

For a discussion of the dispatching of object accessor functions and the use of the result code errAEUnknownObjectType, see "Installing Entries in the Object Accessor Dispatch Tables," which begins on page 6-21.