Previous Book Contents Book Index Next

Inside Macintosh: Interapplication Communication /
Chapter 4 - Responding to Apple Events / Handling Apple Events


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

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

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; 
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 parameter is the desired descriptor type of the resulting data. The handlerRefcon 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. The result 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 the noErr 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 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 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 data in the descriptor record specified by the result parameter. Your handler should return an appropriate result code.

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.
Table 4-1 lists the descriptor types for which the Apple Event Manager provides coercion.
Table 4-1 Coercion handling provided by the Apple Event Manager
Original descriptor type of data to be coercedDesired descriptor typeDescription
typeChartypeInteger

typeLongInteger

typeSMInt

typeSMFloat

typeShortInteger

typeFloat

typeLongFloat

typeShortFloat

typeExtended

typeComp

typeMagnitude

Any string that is a valid representation of a number can be coerced into an equivalent numeric value.
typeInteger

typeLongInteger

typeSMInt

typeSMFloat

typeShortInteger

typeFloat

typeLongFloat

typeShortFloat

typeExtended

typeComp

typeMagnitude

typeCharAny numeric descriptor type can be coerced into the equivalent text string.
typeInteger

typeLongInteger

typeSMInt

typeSMFloat

typeShortInteger

typeFloat

typeLongFloat

typeShortFloat

typeExtended

typeComp

typeMagnitude

typeInteger

typeLongInteger

typeSMInt

typeSMFloat

typeShortInteger

typeFloat

typeLongFloat

typeShortFloat

typeExtended

typeComp

typeMagnitude

Any numeric descriptor type can be coerced into any other numeric descriptor type.
typeChartypeType

typeEnumerated

typeKeyword
typeProperty

Any four-character string can be coerced to one of these descriptor types.
typeEnumerated

typeKeyword

typeProperty

typeType

typeCharAny of these descriptor types can be coerced to the equivalent text string.
   
typeIntlTexttypeCharThe result contains text only, without the script code or language code from the original descriptor record.
typeTruetypeBooleanThe result is the Boolean value TRUE.
typeFalsetypeBooleanThe result is the Boolean value FALSE.
typeEnumeratedtypeBooleanThe enumerated value 'true' becomes the Boolean value TRUE. The enumerated value 'fals' becomes the Boolean value FALSE.
typeBooleantypeEnumeratedThe Boolean value FALSE becomes the enumerated value 'fals'. The Boolean value TRUE becomes the enumerated value 'true'.
typeShortInteger
typeSMInt
typeBooleanA value of 1 becomes the Boolean value TRUE. A value of 0 becomes the Boolean value FALSE.
typeBooleantypeShortInteger typeSMIntA value of FALSE becomes 0. A value of TRUE becomes 1.
typeAliastypeFSSAn alias record is coerced into a file system specification record.
typeAppleEventtypeAppParametersAn Apple event is coerced into a list of application parameters for the LaunchParamBlockRec parameter block.
any descriptor typetypeAEListA descriptor record is coerced into a descriptor list containing a single item.
typeAEListtype of list itemA descriptor list containing a single descriptor record is coerced into a descriptor record.

Note
Some of the descriptor types listed in this table are synonyms; for example, the constants typeSMInt and typeShortInteger have the same four-character code, 'shor'.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996