Carbon


AEGetNthPtr

Header: AEDataModel.h Carbon status: Supported

Gets a copy of the data from a descriptor record at a specified position in a descriptor list; typically used when your application needs to work with the extracted data directly.

OSErr AEGetNthPtr (
    const AEDescList *theAEDescList, 
    SInt32 index, 
    DescType desiredType, 
    AEKeyword *theAEKeyword, 
    DescType *typeCode, 
    void *dataPtr, 
    Size maximumSize, 
    Size *actualSize
);
Parameter descriptions
theAEDescList

A pointer to the descriptor list that contains the descriptor.

index

A one-based positive integer indicating the position in the descriptor list of the descriptor record to get the data from. AEGetNthPtr returns an error if you pass zero, a negative number, or a value that is out of range.

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 index parameter is not of the desired type, AEGetNthPtr attempts to coerce the data to this type. If you pass a value of typeWildCard, no coercion is performed, and the descriptor type of the copied data is the same as the descriptor type of the original descriptor record.

theAEKeyword

A pointer to a keyword. On return, the keyword for the specified descriptor record, if you are getting data from a list of keyword-specified descriptor records; otherwise, AEGetNthPtr returns the value typeWildCard. Some keyword constants are described in “Keyword Attribute Constants” and “Keyword Parameter Constants”.

typeCode

A pointer to a descriptor type. On return, specifies the descriptor type of the data pointed to by dataPtr. 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 data from the descriptor record at the position in the descriptor list specified by the index parameter.

maximumSize

The maximum length, in bytes, of the expected data. The AEGetNthPtr 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 descriptor record. If this value is larger than the value of the maximumSize parameter, the buffer pointed to by dataPtr was not large enough to contain all of the data for the descriptor, though AEGetNthPtr does not write beyond the end of the buffer. If the buffer was too small, you can resize it and call AEGetNthPtr again.

function result

A result code.

DISCUSSION

The AEGetNthPtr function uses a buffer to return the data for a specified descriptor record from a specified descriptor list. The function attempts to coerce the descriptor record to the descriptor type specified by the desiredType parameter.

Before calling AEGetNthPtr, you can call the AESizeOfNthItem function to determine a size for the dataPtr buffer. However, unless you specify typeWildCard for the desiredType parameter, AESizeOfNthItem may coerce the data, which may cause the size of the data to change. If you are using AEGetNthPtr to iterate through a list of descriptor records of the same type with a fixed size, such as a list of descriptor records of type typeFSS, you can get the size once, allocate a buffer, and reuse it for each call.

AVAILABILITY

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


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)