Writing and Installing Coercion Handlers
When your application extracts data from a parameter, it can request that the Apple Event Manager return the data using a descriptor type that is different from the original descriptor type. For example, when extracting data from the direct parameter of the Open Documents event, you can request that the alias records be returned as file system specification records. The Apple Event Manager can automatically coerce many different types of data from one to another. Table 4-1 on page 4-45 shows descriptor types and the kinds of coercion that the Apple Event Manager can perform.You can also provide your own routines, referred to as coercion handlers, to coerce data into any other descriptor type. To install your own coercion handlers, use the
AEInstallCoercionHandler
function. You specify as parameters to this function
The system coercion dispatch table is a table in the system heap that contains coercion handlers available to all applications and processes running on the same computer. The coercion handlers in your application's coercion dispatch table are available only to your application. When attempting to coerce data, the Apple Event Manager first looks for a coercion handler in your application's coercion dispatch table. If it cannot find a handler for the descriptor type, it looks in the system coercion dispatch table for a handler. If it doesn't find a handler there, it attempts to use the default coercion handling described by Table 4-1 on page 4-45. If it can't find an appropriate default coercion handler, it returns the
- the descriptor type of the data coerced by the handler
- the descriptor type of the resulting data
- the address of the coercion handler for this descriptor type
- a reference constant
- a Boolean value that indicates whether your coercion handler expects the data to be specified as a descriptor record or as a pointer to the actual data
- a Boolean value that indicates whether your coercion handler should be added to your application's coercion dispatch table or the system coercion dispatch table
errAECoercionFail
result code.Any handler that you add to the system coercion dispatch table should reside in the system heap. If there was already an entry in the system coercion dispatch table for the same descriptor type, it is replaced. Therefore, if there is an entry in the system coercion dispatch table for the same descriptor type, you should chain it to your system coercion handler as explained in "Creating and Managing the Coercion Handler Dispatch Tables," which begins on page 4-96.
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. Whenever possible, you should write your coercion handler so that it can accept a pointer to the data, because it's more efficient for the Apple Event Manager to provide your coercion handler with a pointer to the data.
- WARNING
- 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 coercion handler may crash.
A coercion handler that accepts a pointer to data must be a function with the following syntax:
FUNCTION MyCoercePtr (typeCode: DescType; dataPtr: Ptr; dataSize: Size; toType: DescType; handlerRefcon: LongInt; VAR result: AEDesc): OSErr;ThetypeCode
parameter is the descriptor type of the original data. ThedataPtr
parameter is a pointer to the data to coerce; thedataSize
parameter is the length, in bytes, of the data. ThetoType
parameter is the desired descriptor type of the resulting data. ThehandlerRefcon
parameter is a reference constant stored in the coercion table entry for the handler and passed to the handler by the Apple Event Manager whenever the handler is called. Theresult
parameter is the descriptor record returned by your coercion handler.Your coercion handler should coerce the data to the desired descriptor type and return the data in the descriptor record specified by the
result
parameter. If your handler successfully performs the coercion, it should return thenoErr
result code; otherwise, it should return a nonzero result code.A coercion handler that accepts a descriptor record must be a function with the following syntax:
FUNCTION MyCoerceDesc (theAEDesc: AEDesc; toType: DescType; handlerRefcon: LongInt; VAR result: AEDesc): OSErr;The parametertheAEDesc
is the descriptor record that contains the data to be coerced. ThetoType
parameter is the descriptor type of the resulting data. ThehandlerRefcon
parameter is a reference constant stored in the coercion table entry for the handler and passed to the handler by the Apple Event Manager whenever the handler is called. Theresult
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 data in the descriptor record specified by the
result
parameter. Your handler should return an appropriate result code.
Table 4-1 lists the descriptor types for which the Apple Event Manager provides coercion.
- Note
- To ensure that no coercion is performed and that the descriptor type of the result is of the same descriptor type as the original, specify
typeWildCard
for the desired type.
- Note
- Some of the descriptor types listed in this table are synonyms; for example, the constants
typeSMInt
andtypeShortInteger
have the same four-character code,'shor'
.