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 (possibly including error information), and returns a result code.
- macOS 10.0+
- Mac Catalyst 13.0+
- Core Services
A pointer to the Apple event to handle. See
A pointer to the default reply Apple event provided by the Apple Event Manager. See
Apple. If no reply is expected,
replyhas descriptor type
The reference constant stored in the Apple event dispatch table when you install the handler function for the Apple event. You can store any 32-bit value in the dispatch table and use it any way you want when the handler is called. The reference constant may have a value of
A result code. See Result Codes. Your handler should always return
no if it successfully handled the Apple event. If an error occurs, your handler should return either
err or some other nonzero result code. For more information, see the Discussion section.
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
err, 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
k event that requests the name of the current printer, and your application cannot handle such an event. In this situation, you should return
err 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
err. 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
To provide a pointer to your event handler callback function, you create a universal procedure pointer (UPP) of type
AEEvent, using the function
New. You can do so with code like the following:
You can then pass the UPP
My as a parameter to any function that installs or removes a handler, such as
AEInstall. 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
After you are finished with an event handler callback function, and have removed it with the
AERemove function, you can dispose of the UPP with the
Dispose function. However, don’t dispose of the UPP if any remaining handler uses it or if you plan to install the handler again.