Carbon


AEEventHandlerProcPtr

Header: AEDataModel.h Carbon status: Supported

Defines a pointer to a function that handles one or more Apple events. Your Apple event handler function performs any action requested by the Apple event, adds parameters to the reply Apple event if appropriate, and returns a result code.

typedef OSErr(* AEEventHandlerProcPtr) (
    const AppleEvent *theAppleEvent, 
    AppleEvent *reply, 
    UInt32 handlerRefcon
);

You would declare your function like this if you were to name it MyAEEventHandlerCallback:

OSErr MyAEEventHandlerCallback (
    const AppleEvent *theAppleEvent, 
    AppleEvent *reply, 
    UInt32 handlerRefcon
);
Parameter descriptions
theAppleEvent

A pointer to the Apple event to handle.

reply

A pointer to 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. The reference constant may have a value of NULL.

function result

A result code. Your handler should always return noErr if it successfully handled the Apple event. If an error occurs, your handler should return either errAEEventNotHandled or some other nonzero result code. For more information, see the Discussion section.

DISCUSSION

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. You must provide an Apple event handler for each Apple event your application supports. The AEProcessAppleEvent function calls one of your Apple event handlers when it processes an Apple event.

If an error occurs because your application cannot understand the event, return errAEEventNotHandled, so that the Apple Event Manager may be able to find another handler 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 kAEGetData event that requests the name of the current printer, and your application cannot handle such an event. In this situation, you should return errAEEventNotHandled so that another handler available to the Apple Event Manager can have a chance to handle the event. This strategy allows users to take advantage of system capabilities from within your application via system handlers.

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.

For additional information on dealing with error conditions, see OSLGetErrDescProcPtr.

To provide a pointer to your event handler callback function, you create a universal procedure pointer (UPP) of type AEEventHandlerUPP, using the function NewAEEventHandlerUPP. You can do so with code like the following:

AEEventHandlerUPP MyEventHandlerUPP;

MyEventHandlerUPP = NewAEEventHandlerUPP (&MyEventHandlerCallback);

You can then pass the UPP MyEventHandlerUPP as a parameter to any function that installs or removes a handler, such as AEInstallEventHandler. If your application installs the same event handler to handle more than one kind of event (more than one pair of event class and event ID), you can use the same UPP to install the handler multiple times.

If you wish to call your event handler callback function directly, you can use the InvokeAEEventHandlerUPP function.

After you are finished with an event handler callback function, and have removed it with the AERemoveEventHandler function, you can dispose of the UPP with the DisposeAEEventHandlerUPP function. However, don’t dispose of the UPP if any remaining handler uses it or if you plan to install the handler again.

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


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)