Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Reference to Responding to Apple Events

Routines for Responding to Apple Events / Getting Items From Descriptor Lists

AEGetNthPtr

You can use the AEGetNthPtr function to get a pointer to a buffer that contains a copy of a descriptor record from any descriptor list.

FUNCTION AEGetNthPtr (theAEDescList: AEDescList; index: LongInt; 
                      desiredType: DescType; 
                      VAR theAEKeyword: AEKeyword; 
                      VAR typeCode: DescType; dataPtr: Ptr; 
                      maximumSize: Size; 
                      VAR actualSize: Size): OSErr;

theAEDescList

The descriptor list containing the desired descriptor record.

index

The position of the desired descriptor record in the list (for example, 2 specifies the second descriptor record).

desiredType

The desired descriptor type for the copy of the descriptor record to be returned; if the desired descriptor record is not of this type, the Apple Event Manager attempts to coerce it to this type. If the value of desiredType is 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

The keyword of the specified descriptor record, if you are getting data from a list of keyword-specified descriptor records; otherwise, AEGetNthPtr returns the value typeWildCard.

typeCode

The descriptor type of the returned descriptor record.

dataPtr

A pointer to the buffer in which the returned descriptor record is stored.

maximumSize

The maximum length, in bytes, of the data to be returned. You must allocate at least this amount of storage for the buffer specified by the dataPtr parameter.

actualSize

The length, in bytes, of the data for the specified descriptor record. If this value is larger than the value of the maximumSize parameter, not all of the data for the descriptor record was returned.

DESCRIPTION

The AEGetNthPtr function uses a buffer to return 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.

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough room in heap zone
errAECoercionFail	-1700	Data could not be coerced to the requested descriptor type
errAEDescNotFound	-1701	Descriptor record was not found
errAEWrongDataType	-1703	Wrong descriptor type
errAENotAEDesc	-1704	Not a valid descriptor record
errAEReplyNotArrived	-1718	Reply has not yet arrived

SEE ALSO

For an example of the use of AEGetNthPtr, see Listing 4-10 on page 4-33.