Carbon


AERemoveSpecialHandler

Header: AppleEvents.h Carbon status: Supported

Removes a handler from a special handler dispatch table.

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

The keyword for the special handler to remove. Pass one of the constants described in “Special Handler Callback Constants”.

handler

A universal procedure pointer to the special handler to remove. Although the functionClass parameter is sufficient to identify the handler to remove, you can identify the handler explicitly as a safeguard. If you pass NULL for this parameter, the Apple Event Manager relies solely on the function class to identify the handler.

isSysHandler

Specifies the special handler dispatch table to remove the handler from. Pass TRUE to remove the handler from the system special handler dispatch table or FALSE to remove the handler from 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

See also AEInstallSpecialHandler and AEGetSpecialHandler.

VERSION NOTES

A Carbon application should not install a special 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.

In some previous versions of the Mac OS, applications might have reason to disable, within the application only, all Apple Event Manager functions that support Apple event objects—that is, all the functions available to an application as a result of linking the Object Support Library (OSL) and calling theAEObjectInit function.

To disable the OSL, you should pass the keyword keySelectProc in the functionClass parameter, NULL in the handler parameter, and FALSE in the isSysHandler parameter. An application that expects its copy of the OSL to move after it is installed—for example, an application that keeps it in a stand-alone code resource—would need to disable the OSL. When an application calls AEObjectInit to initialize the OSL, the OSL installs the addresses of its functions as extensions to the pack. If those functions move, the addresses become invalid.

Once you have called the AERemoveSpecialHandler function to disable the OSL, subsequent calls by your application to any of the Apple Event Manager functions that support Apple event objects will return errors. To initialize the OSL after disabling it with the AERemoveSpecialHandler function, your application must call AEObjectInit again.

If you expect to initialize the OSL and disable it several times, you should call AERemoveObjectAccessor to remove your application’s object accessor functions from your application’s object accessor dispatch table before you call AERemoveSpecialHandler.

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)