Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Coercing Data From an Apple Event

Coercion is the process of converting a descriptor and, if necessary, the data it contains, from one type to another. When your handler receives an Apple event, you typically use one or more of the functions AEGetParamPtr, AEGetAttributePtr, AEGetParamDesc, AEGetAttributeDesc, AEGetNthPtr, and AEGetNthDesc to get data from the Apple event. Each of these Apple Event Manager functions allows your application to specify a desired descriptor type for the resulting data. If the original data is of a different type, the Apple Event Manager attempts to coerce the data to the requested descriptor type. To prevent coercion and ensure that the descriptor type of the result is of the same type as the original, you specify typeWildCardfor the desired type.

The following code snippet shows how to specify a desired descriptor type when calling the function AEGetParamPtr.

Listing 4-1  Getting and coercing an Apple event parameter

    DescType        returnedType;

    long            multResult;

    Size            actualSize;

    OSErr           err;

    err = AEGetParamPtr(

            theAppleEvent,// 1

            keyMultResult,// 2

            typeSInt32,// 3

            &returnedType,// 4

            &multResult,// 5

            sizeof(multResult),// 6

            &actualSize);// 7

Here’s a description of the parameters used in this call:

1. A pointer to the Apple event to get the parameter data from.

2. A keyword constant specifying the parameter to get the data from. In this example, the keyword is defined by the application and indicates a parameter containing the result of a multiplication operation.

3. A constant specifying the type to coerce the returned value to (if it isn’t already that type).

4. The address of a variable in which the function stores the actual type of the returned value, which may not match the requested type.

5. The address of a variable in which the function stores the returned data.

6. The maximum size of the returned data. The AEGetParamPtr function won’t return more data than you specify in this parameter.

7. The address of a variable in which the function stores the actual size of the requested data. If the returned value is greater than the amount your application allocated to store the returned data, you can increase the size of your buffer to this amount and call the function again. You can also choose to use the AEGetParamDesc function when your application doesn’t know the size of the data.

If the coercion fails, the AEGetParamPtr function returns the result code errAECoercionFail.

By default, the Apple Event Manager can coerce between many different data types, listed in Table C-2. To perform other coercions, such as those involving data types you have defined, you can provide your own coercion handlers. See “Writing and Installing Coercion Handlers” for more information on working with coercion handlers.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice