![]() |
AECoerceDescProcPtr |
||||
Header: | AEDataModel.h | Carbon status: | Supported | |
Defines a pointer to a function that coerces data stored in a descriptor record. Your descriptor coercion callback function coerces the data from the passed descriptor record to the specified type, returning the coerced data in a second descriptor record.
typedef OSErr(* AECoerceDescProcPtr) ( const AEDesc *fromDesc, DescType toType, SInt32 handlerRefcon, AEDesc *toDesc );
You would declare your function like this if you were to name it MyAECoerceDescCallback:
OSErr MyAECoerceDescCallback ( const AEDesc *fromDesc, DescType toType, SInt32 handlerRefcon, AEDesc *toDesc );
A pointer to the descriptor record that contains the data to coerce.
The desired descriptor type for the resulting descriptor record. For a list of AppleScripts predefined descriptor types, see
A reference constant that is stored in the coercion dispatch table entry for the handler. The Apple Event Manager passes this value to the handler each time it calls it. The reference constant may have a value of 0.
A pointer to a descriptor record where your coercion routine must store the descriptor record that contains the coerced data.
A result code. Your handler should return noErr if it successfully handled the coercion, errAECoercionFailed if it cant handle the coercion and it wants the Apple Event Manager to continue dispatching to other coercion handlers, or a nonzero result code otherwise.
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.
To provide a pointer to your descriptor coercion callback function, you create a universal procedure pointer (UPP) of type AECoerceDescUPP, using the function NewAECoerceDescUPP. You can do so with code like the following:
AECoerceDescUPP MyCoerceDescUPP;
MyCoerceDescUPP = NewAECoerceDescUPP (&MyCoerceDescCallback);
You can then pass the UPP MyCoerceDescUPP as a parameter to any function that installs or removes a coercion handler, such as AEInstallCoercionHandler. If your application installs the same coercion handler to coerce more than one type of data, you can use the same UPP to install the handler multiple times.
If you wish to call your descriptor coercion callback function directly, you can use the InvokeAECoerceDescUPP function.
After you are finished with a descriptor coercion callback function, and have removed it with the AERemoveCoercionHandler function, you can dispose of the UPP with the DisposeAECoerceDescUPP function. However, dont dispose of the UPP if any remaining coercion handler uses it or if you plan to install the coercion handler again.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)