AEGetNthDesc(_:_:_:_:_:)

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

Declaration

func AEGetNthDesc(_ theAEDescList: UnsafePointer<AEDescList>!, _ index: Int, _ desiredType: DescType, _ theAEKeyword: UnsafeMutablePointer<AEKeyword>!, _ result: UnsafeMutablePointer<AEDesc>!) -> OSErr

Parameters

theAEDescList:
A pointer to the descriptor list to get the descriptor from. See Aedesclist.
index:
A one-based positive integer indicating the position of the descriptor 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 to copy. For a list of AppleScript’s predefined descriptor types, see 1542788 Descriptor_type_constants.
If the descriptor 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 is the same as the descriptor type of the original descriptor.
See Desctype.
theAEKeyword:
A pointer to a keyword. On successful return, the keyword for the specified descriptor, if you are getting data from a list of keyword-specified descriptors; otherwise, AEGetNthDesc returns the value typeWildCard. Some keyword constants are described in 1542920 Keyword_attribute_constants and 1527206 Keyword_parameter_constants. See Aekeyword.
result:
A pointer to a descriptor. On successful return, a copy of the descriptor specified by the index parameter, coerced, if necessary, to the descriptor type specified by the desiredType parameter. On error, a null descriptor. If the function returns successfully, your application should call the 1444208 Aedisposedesc function to dispose of the resulting descriptor after it has finished using it. See Aedesc.

Return Value

A result code. See Result Codes.

Discussion

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

You may find the AEGetNthPtr(_:_:_:_:_:_:_:_:) function convenient for retrieving data for direct use in your application, as it includes automatic coercion.

Version-Notes

Thread safe starting in OS X v10.2.