Carbon


AEGetNthDesc

Header: AEDataModel.h Carbon status: Supported

Copies a descriptor record from a specified position in a descriptor list into a specified descriptor record; typically used when your application needs to pass the extracted data to another function as a descriptor record.

OSErr AEGetNthDesc (
    const AEDescList *theAEDescList, 
    SInt32 index, 
    DescType desiredType, 
    AEKeyword *theAEKeyword, 
    AEDesc *result
);
theAEDescList

A pointer to the descriptor list to get the descriptor from.

index

A one-based positive integer indicating the position of the descriptor record to get. AEGetNthDesc 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 descriptor record to copy. 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, AEGetNthDesc attempts to coerce it to this type. However, if you pass a value of typeWildCard, no coercion is performed, and the descriptor type of the copied descriptor record is the same as the descriptor type of the original descriptor record.

theAEKeyword

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

result

A pointer to a descriptor record. On successful return, a copy of the descriptor record specified by the index parameter, coerced, if necessary, to the descriptor type specified by the desiredType parameter. On error, a null descriptor. Your application should always call the AEDisposeDesc function to dispose of the resulting descriptor record after it has finished using it.

function result

A result code.

DISCUSSION

If the Nth descriptor record in the list is itself an AERecord and the desired type is not wildcard, record, or list, AEGetNthDesc will fail with an errAECoercionFailed error. This behavior prevents coercion problems.

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)