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

AEInstallSpecialHandler

You can use the AEInstallSpecialHandler function to install a special handler in either the application or system special handler dispatch table.

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

functionClass

The keyword for the special handler that is installed. The keyPreDispatch constant identifies a handler with the same parameters as an Apple event handler called immediately before the Apple Event Manager dispatches an Apple event. Any of the constants for object callback functions listed above can also be specified in this parameter. If there was already an entry in the specified special handler dispatch table for the same value of functionClass, it is replaced.

handler

A pointer to the special handler. Note that a handler in the system special handler dispatch table must reside in the system heap; thus, if the value of the isSysHandler parameter is TRUE, the handler parameter should point to a location in the system heap. Otherwise, if you put your system handler code in your application heap, use AERemoveSpecialHandler to remove the handler when your application quits.

isSysHandler

The special handler dispatch table to which to add the handler. If the value of this parameter is TRUE, the handler is added to the system handler dispatch table and made available to all applications. If the value is FALSE, the handler is added to the application handler table.

DESCRIPTION

The AEInstallSpecialHandler function creates an entry in either your application's special handler dispatch table or the system special handler dispatch table. You must supply parameters that specify the keyword for the special handler that is installed, the handler routine, and whether the handler is to be added to the system special handler dispatch table or your application's special handler dispatch table.

SPECIAL CONSIDERATIONS

Before an application calls a system special handler, system software has set up the A5 register for the calling application. For this reason, a system special handler should never use A5 global variables or anything that depends on a particular context; otherwise, the application that calls the system handler may crash.

RESULT CODES

noErr	0	No error
paramErr	-50	Parameter error (handler pointer is NIL or odd)
memFullErr	-108	Not enough room in heap zone
errAENotASpecialFunction	-1714	Wrong keyword for a special function