AEInstallSpecialHandler

Install handler in a special handler table

#include <AppleEvents.h> Apple Event Manager

OSErr AEInstallSpecialHandler ( functionClass, handler,

isSysHandler );

AEKeyword functionClass ; keyword for special handler being installed

ProcPtr handler ; pointer to special handler routine

Boolean isSysHandler ; TRUE = points to location in system heap

FALSE = points to location in application heap

returns Error Code; 0 = no error

The AEInstallSpecialHandler function installs a handler in a special

handler table.

The functionClass parameter is the keyword for the special handler that's

installed. There is currently only one value allowed for this parameter: the

keyPreDispatch constant, which identifies a handler routine that is called

immediately before the Apple Event Manager dispatches an Apple event. If

there was already an entry in the specified special handler table for the same

value of functionClass, it is replaced.

The handler parameter is a pointer to the special handler. Note that a handler

in the system handler table must reside in the system heap; this means that 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, you must remove the handler

when your application quits by using the AERemoveSpecialHandler

function.

The isSysHandler parameter specifies the special handler table to which to

add the handler. If its value is TRUE, the handler is added to the system handler

table and made available to all applications. If its value is FALSE, the handler

is added to the application handler table.

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

Notes: When an application calls a system Apple event handler, the

A5 register is set up for the calling application. For this reason, if you

provide a system Apple event handler, it should never use

A5 global variables or anything that depends on a particular context;

otherwise, the application that calls the system handler may crash.

Referenced by (2):