Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 5 - Creating and Sending Apple Events / Reference to Creating and Sending Apple Events

Routines for Creating and Sending Apple Events / Creating Descriptor Lists and AE Records

AECreateList

You can use the AECreateList function to create an empty descriptor list or AE record.

FUNCTION AECreateList (factoringPtr: Ptr; factoredSize: Size;
                       isRecord: Boolean; 
                       VAR resultList: AEDescList): OSErr;

factoringPtr

A pointer to the data at the beginning of each descriptor that is the same for all descriptor records in the list. If there is no common data, or if you decide not to isolate the common data, specify NIL as the value of this parameter.

factoredSize

The size of the common data. If there is no common data, or if you decide not to isolate the common data, the value of factoredSize must be 0. (See the description that follows for more information.)

isRecord

A Boolean value that specifies the kind of list to create. If you set it to TRUE, the Apple Event Manager creates an AE record. If you set it to FALSE, the Apple Event Manager creates a descriptor list.

resultList

The descriptor list or AE record that the AECreateList function creates.

DESCRIPTION

The AECreateList function creates an empty descriptor list or AE record. Your application is responsible for using the AEDisposeDesc function to dispose of the resulting descriptor record when you no longer need it. You normally do this after receiving a result code from the AESend function.

If you intend to use a descriptor list for a factored Apple event array, you must provide, in the factoringPtr parameter, a pointer to the data shared by all items in the array and, in the factoredSize parameter, the size of the common data. The common data must be 4, 8, or more than 8 bytes in length because it always consists of (a) the descriptor type (4 bytes); (b) the descriptor type (4 bytes) and the size of each item's data (4 bytes); or (c) the descriptor type (4 bytes), the size of each item's data (4 bytes), and some portion of the data itself (1 or more bytes).

If AECreateList returns a nonzero result code, it returns a null descriptor record unless the Apple Event Manager is not available because of limited memory.

RESULT CODES

noErr	0	No error
paramErr	-50	Parameter error (value of handler pointer is NIL or odd)
memFullErr	-108	Not enough room in heap zone

SEE ALSO

For an example of the use of AECreateList, see Listing 5-1 on page 5-9.

For information about data types used with Apple event arrays, see "Apple Event Array Data Types" on page 4-57.