Legacy Document

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

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 coerced	Desired descriptor type	Description
typeChar	typeInteger 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	typeChar	Any 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.
typeChar	typeType typeEnumerated typeKeyword typeProperty	Any four-character string can be coerced to one of these descriptor types.
typeEnumerated typeKeyword typeProperty typeType	typeChar	Any of these descriptor types can be coerced to the equivalent text string.
typeIntlText	typeChar	The result contains text only, without the script code or language code from the original descriptor record.
typeTrue	typeBoolean	The result is the Boolean value TRUE.
typeFalse	typeBoolean	The result is the Boolean value FALSE.
typeEnumerated	typeBoolean	The enumerated value 'true' becomes the Boolean value TRUE. The enumerated value 'fals' becomes the Boolean value FALSE.
typeBoolean	typeEnumerated	The Boolean value FALSE becomes the enumerated value 'fals'. The Boolean value TRUE becomes the enumerated value 'true'.
typeShortInteger typeSMInt	typeBoolean	A value of 1 becomes the Boolean value TRUE. A value of 0 becomes the Boolean value FALSE.
typeBoolean	typeShortInteger typeSMInt	A value of FALSE becomes 0. A value of TRUE becomes 1.
typeAlias	typeFSS	An alias record is coerced into a file system specification record.
typeAppleEvent	typeAppParameters	An Apple event is coerced into a list of application parameters for the LaunchParamBlockRec parameter block.
any descriptor type	typeAEList	A descriptor record is coerced into a descriptor list containing a single item.
typeAEList	type of list item	A 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'.