All Databases Inside Mac - AppleEvents

AEInstallCoercionHandler

Install a coercion handler

#include <AppleEvents.h> Apple Event Manager

OSErr AEInstallCoercionHandler ( fromType, toType, handler,

handlerRefcon, fromTypeIsDesc, isSysHandler );

DescType fromType ; descriptor type of coerced data

DescType toType ; descriptor type of resulting data

ProcPtr handler ; pointer to coercion handler routine

long handlerRefcon ; reference constant

Boolean fromTypeIsDesc ; TRUE = data passed as descriptor record

FALSE = pointer to the data passed

Boolean isSysHandler ; TRUE = added to system coercion table

FALSE = added to application coercion table

returns Error Code; 0 = no error

The AEInstallCoercionHandler function installs a coercion handler

routine in either the application or system coercion table.

The fromType parameter is the descriptor type of the data coerced by the

handler, and the toType parameter is 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, it is replaced.

Therefore, before installing a handler for a particular descriptor type into

the system coercion table, use the AEGetCoercionHandler function to

determine if the table already contains a 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

pointers to the previous handler and its reference constant in the

handlerRefcon parameter of AEInstallCoercionHandler. When your

handler is finished, use these pointers to call the previous handler. If you

remove your system handler, be sure to reinstall the chained handlers.

The handler parameter is a pointer to the coercion handler routine. Note that

a handler in the system coercion 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

AERemoveCoercionHandler function. See the Notes section below for a

description of the syntax of a coercion handler.

The handlerRefcon parameter is a reference constant that is passed by the

Apple Event Manager to the handler each time the handler is called. If

your handler doesn't expect a reference con-stant, use 0 as the value of this

parameter.

The fromTypeIsDesc parameter specifies the form of the data to be coerced. If

its value is TRUE, the coercion handler expects the data to be passed as a

descriptor record. If its value is FALSE, the coercion handler expects a

pointer to the data to be coerced. 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.

The isSysHandler parameter specifies the coercion table to which to add the

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

and made available to all applications. If its 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; this means that if the value of

the isSysHandler parameter is TRUE, the handler parameter must point to a

location in the system heap.

Note: 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.

Result codes

noErr (0) No error

memFullErr (-108) Not enough room in heap zone

Notes: You can provide a coercion handler that expects to receive the data in a

descriptor record or a buffer referred to by a pointer. When you install

your coercion handler, you specify how your handler wishes to receive the

data. It's more efficient for the Apple Event Manager to provide your

coercion handler with a pointer to the data so, whenever possible, you

should write your coercion handler so that it can accept a pointer to the

data.

A coercion handler that accepts a pointer to data must be a function with

the following syntax:

OSErr MyCoercePtr (DescType typeCode, Ptr dataPtr, Size dataSize,

DescType toType, long handlerRefcon,

AEDesc * result);

The typeCode parameter is the descriptor type of the original data. The

dataPtr parameter is a  pointer to the data to  coerce; the  dataSize  parameter

is the length, in bytes, of the data. The toType is the desired descriptor type

of the resulting data. The handlerRefcon parameter is a reference constant

that is stored in the coercion table entry for the handler and passed to the

handler by the Apple Event Manager whenever the handler is called. The

result parameter is the resulting descriptor record returned by your

coercion handler.

Your coercion handler should coerce the data to the desired descriptor type

and return the resulting data in the descriptor record specified by the

result parameter. Your handler should return the noErr result code if

your handler successfully performs the coercion, and a nonzero result code

otherwise.

A coercion handler that accepts a descriptor record must be a function with

the following syntax:

OSErr MyCoerceDesc (AEDesc * theAEDesc, DescType toType,

long handlerRefcon, AEDesc * result);

The parameter theAEDesc is the descriptor record that contains the data to

be coerced. The toType parameter is the descriptor type of the resulting

data. The handlerRefcon parameter is a reference constant that is stored in

the coercion table entry for the handler and passed to the handler by the

Apple Event Manager whenever the handler is called. The result

parameter is the resulting descriptor record.

Your coercion handler should coerce the data in the descriptor record to the

desired descriptor type and return the resulting data in the

descriptor record specified by the result parameter. Your handler should

return an appropriate result code.

See Writing and Installing Coercion Handlers for additional

information on coercion handlers.

Referenced by (4):