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 Coercion Handler Dispatch Tables

AEInstallCoercionHandler

You can use the AEInstallCoercionHandler function to install a coercion handler routine in either the application or system coercion handler dispatch table.

FUNCTION AEInstallCoercionHandler (fromType: DescType; 
                                   toType: DescType; 
                                   handler: ProcPtr; 
                                   handlerRefcon: LongInt; 
                                   fromTypeIsDesc: Boolean; 
                                   isSysHandler: Boolean): OSErr;

fromType

The descriptor type of the data coerced by the handler.

toType

The descriptor type of the resulting data. If there was already an entry in the specified coercion handler table for the same source descriptor type and result descriptor type, the existing entry is replaced.

handler

A pointer to the coercion handler. Note that a handler in the system coercion 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, you should use AERemoveCoercionHandler to remove the handler when your application quits.

handlerRefcon

A reference constant passed by the Apple Event Manager to the handler each time the handler is called. If your handler doesn't expect a reference constant, use 0 as the value of this parameter.

fromTypeIsDesc

Specifies the form of the data to be coerced. If the value of this parameter is TRUE, the coercion handler expects the data to be passed as a descriptor record. If the value is FALSE, the coercion handler expects a pointer to the data. Because it is more efficient for the Apple Event Manager to provide a pointer to data than to a descriptor record, all coercion routines should accept a pointer to data if possible.

isSysHandler

Specifies the coercion table to which the handler is added. If the value of this parameter is TRUE, the handler is added to the system coercion table and made available to all applications. If the value is FALSE, the handler is added to the application coercion table. Note that a handler in the system coercion table must reside in the system heap; thus, if the value of the isSysHandler parameter is TRUE, the handler parameter must point to a location in the system heap.

DESCRIPTION

Before using AEInstallCoercionHandler to install a handler for a particular descriptor type into the system coercion handler dispatch table, use the AEGetCoercionHandler function to determine whether the table already contains a coercion handler for that descriptor type. If an entry exists, AEGetCoercionHandler returns a reference constant and a pointer to that handler. Chain these to your coercion handler by providing, in the handlerRefcon parameter of AEInstallCoercionHandler, pointers to the previous handler and its reference constant. If your coercion handler returns the error errAECoercionFail, use these pointers to call the previous handler. If you remove your system coercion handler, be sure to reinstall the chained handlers.

SPECIAL CONSIDERATIONS

Before an application calls a system coercion handler, system software has set up the A5 register for the calling application. For this reason, if you provide a system coercion 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.

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough room in heap zone