Important: The information in this document is obsolete and should not be used for new development.
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 eithererrAEEventNotHandled
or some other nonzero result code. If the error occurs because your application cannot understand the event, returnerrAEEventNotHandled
, 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 andAEResolve
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 codeerrAEUnknownObjectType
. 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.