Carbon


AEInstallCoercionHandler

Header: AEDataModel.h Carbon status: Supported

Installs a coercion handler in either the application or system coercion handler dispatch table.

OSErr AEInstallCoercionHandler (
    DescType fromType, 
    DescType toType, 
    AECoercionHandlerUPP handler, 
    SInt32 handlerRefcon, 
    Boolean fromTypeIsDesc, 
    Boolean isSysHandler
);
fromType

The descriptor type of the data coerced by the handler. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants”.

toType

The descriptor type of the resulting data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants”.

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 universal procedure pointer to the coercion handler function to install.

handlerRefcon

A reference constant. The Apple Event Manager passes this value to the handler each time it calls it. If your handler doesn’t expect a reference constant, pass 0 for this parameter.

fromTypeIsDesc

Specifies the form of the data to coerce. Pass TRUE if the coercion handler expects the data as a descriptor record or FALSE if the coercion handler expects a pointer to the data. The Apple Event Manager can provide a pointer to data more efficiently than it can provide a descriptor record, so all coercion functions should accept a pointer to data if possible.

isSysHandler

Specifies the coercion table to add the handler to. Pass TRUE to add the handler to the system coercion table or FALSE to add the handler to your application’s coercion table. Use of the system coercion table is not recommended for Carbon applications.

function result

A result code.

DISCUSSION

Before using AEInstallCoercionHandler to install a handler for a particular descriptor type, you can use the AEGetCoercionHandler function to determine whether the table already contains a coercion handler for that type.

VERSION NOTES

A Carbon application should not install a coercion handler in a system coercion handler dispatch table with the goal that the handler will get called when other applications perform coercions—this won’t necessarily work. See “Apple Event Dispatching” (to be supplied later) for more information.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.


© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)