Carbon


AEInstallSpecialHandler

Header: AppleEvents.h Carbon status: Supported

Installs a callback function in a special handler dispatch table.

OSErr AEInstallSpecialHandler (
    AEKeyword functionClass, 
    AEEventHandlerUPP handler, 
    Boolean isSysHandler
);
Parameter descriptions
functionClass

A value that specifies the type of handler to install. You can use any of the constants defined in “Special Handler Callback Constants”.

If there is already an entry in the specified special handler dispatch table for the value you specify in this parameter, it is replaced.

handler

A universal procedure pointer to the special handler to install.

isSysHandler

Specifies the special handler dispatch table to add the handler to. Pass TRUE to add the handler to the system special handler dispatch table or FALSE to add the handler to your application’s special handler dispatch table. Use of the system special handler dispatch table is not recommended for Carbon applications.

function result

A result code.

DISCUSSION

An Apple event special handler dispatch table contains entries with a function class keyword, the address of the handler function that handles the Apple events indicated by the keyword, and a reference constant. Depending on which handlers you choose to install, a special handler dispatch table can have entries for any of the following:

See also AEGetSpecialHandler and AERemoveSpecialHandler.

VERSION NOTES

For Carbon applications running in Mac OS 8 or Mac OS 9, a handler in the system special handler dispatch table should reside in the system heap, where it may be available to other applications. If you put your system handler code in your application heap, be sure to use AERemoveSpecialHandler to remove the handler when your application quits. Otherwise, your handler will still have an entry in the system dispatch table with a pointer a handler that no longer exists. Another application may dispatch an Apple event that attempts to call your handler, leading to a system crash.

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

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


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