Important: The information in this document is obsolete and should not be used for new development.
AEInstallCoercionHandler
You can use theAEInstallCoercionHandler
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 isTRUE
, thehandler
parameter should point to a location in the system heap. Otherwise, if you put your system handler code in your application heap, you should useAERemoveCoercionHandler
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 isTRUE
, the coercion handler expects the data to be passed as a descriptor record. If the value isFALSE
, 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 isTRUE
, the handler is added to the system coercion table and made available to all applications. If the value isFALSE
, 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 theisSysHandler
parameter isTRUE
, 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 theAEGetCoercionHandler
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 thehandlerRefcon
parameter ofAEInstallCoercionHandler
, pointers to the previous handler and its reference constant. If your coercion handler returns the errorerrAECoercionFail
, 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