Carbon


AEGetParamPtr

Header: AEDataModel.h Carbon status: Supported

Gets a copy of the data for a specified Apple event parameter from an Apple event; typically used when your application needs to work with the extracted data directly.

OSErr AEGetParamPtr (
    const AppleEvent *theAppleEvent, 
    AEKeyword theAEKeyword, 
    DescType desiredType, 
    DescType *typeCode, 
    void *dataPtr, 
    Size maximumSize, 
    Size *actualSize
);
theAppleEvent

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

theAEKeyword

The keyword that specifies the desired Apple event parameter. Some keyword constants are described in “Keyword Parameter Constants”.

desiredType

The desired descriptor type for the copied data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants”.

If the descriptor record specified by the theAEKeyword parameter is not of the desired type, AEGetParamPtr attempts to coerce the data to this type. However, if the desired type is typeWildCard, no coercion is performed.

On return, you can determine the actual descriptor type by examining the typeCode parameter.

typeCode

A pointer to a descriptor type. On return, specifies the descriptor type of the data pointed to by dataPtr. The returned type is either the same as the type specified by the desiredType parameter or, if the desired type was type wildcard, the true type of the descriptor. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants”.

dataPtr

A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size in bytes must be at least as large as the value you pass in the maximumSize parameter. On return, contains the parameter data.

maximumSize

The maximum length, in bytes, of the expected Apple event parameter data. The AEGetParamPtr function will not return more data than you specify in this parameter.

actualSize

A pointer to a size variable. On return, the length, in bytes, of the data for the specified Apple event parameter. If this value is larger than the value you passed in the maximumSize parameter, the buffer pointed to by dataPtr was not large enough to contain all of the data for the parameter, though AEGetParamPtr does not write beyond the end of the buffer. If the buffer was too small, you can resize it and call AEGetParamPtr again.

function result

A result code.

DISCUSSION

To get Apple event parameter data for your application to use directly, call AEGetParamPtr. To get a descriptor record for an Apple event parameter to pass on to another Apple Event Manager routine, call AEGetParamDesc.

Before calling AEGetParamPtr, you can call the AESizeOfParam function to determine a size for the dataPtr buffer. However, unless you specify typeWildCard for the desiredType parameter, AEGetParamPtr may coerce the data, which may cause the size of the data to change.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.


© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)