Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Reference to Responding to Apple Events

Routines for Responding to Apple Events / Creating and Managing the Special Handler Dispatch Tables

AERemoveSpecialHandler

You can use the AERemoveSpecialHandler function to remove a handler from a special handler table.

FUNCTION AERemoveSpecialHandler (functionClass: AEKeyword; 
                                 handler: ProcPtr; 
                                 isSysHandler: Boolean): OSErr;

functionClass

The keyword for the special handler to be removed. In addition to the constants for object callback functions listed on page 4-100, two other values are allowed for the functionClass parameter: keyPreDispatch and keySelectProc. The keyPreDispatch constant identifies a handler with the same parameters as an Apple event handler that is called immediately before the Apple Event Manager dispatches an Apple event. The keySelectProc constant indicates that you want to disable the Object Support Library--that is, all the routines described in the chapter "Resolving and Creating Object Specifier Records" in this book (see the description that follows for more information).

handler

A pointer to the special handler to be removed. Although the functionClass parameter would be sufficient to identify the handler to be removed, providing the handler parameter is a safeguard that you remove the correct handler.

isSysHandler

Specifies the special handler dispatch table from which to remove the handler. If the value of this parameter is TRUE, the handler is taken from the system special handler dispatch table. If the value is FALSE, the handler is removed from the application special handler dispatch table.

DESCRIPTION

In addition to using the AERemoveSpecialHandler function to remove specific special handlers, you can use the function to disable, within your application only, all Apple Event Manager routines that support Apple event objects--that is, all the routines available to your application as a result of linking the Object Support Library (OSL) and calling the AEObjectInit function.

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 do this. When an application calls AEObjectInit to initialize the OSL, the OSL installs the addresses of its routines as extensions to the pack. If those routines move, the addresses become invalid.

To disable the OSL, you should pass the keyword keySelectProc in the functionClass parameter, NIL in the handler parameter, and FALSE in the isSysHandler parameter. Once you have called the AERemoveSpecialHandler function with these parameters, subsequent calls by your application to any of the Apple Event Manager routines 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.

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough room in heap zone
errAENotASpecialFunction	-1714	Wrong keyword for a special function