Legacy Document

Inside Macintosh: Interapplication Communication /

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

Data Structures Used by the Apple Event Manager

Descriptor Records and Related Data Structures

Descriptor records are the fundamental data structures from which Apple events are constructed. A descriptor record is a data structure of type AEDesc.

TYPE AEDesc = 
   RECORD                           {descriptor record}
      descriptorType:   DescType;   {type of data being passed}
      dataHandle:       Handle;     {handle to data being passed}
   END;

Field Description

descriptorType

A four-character string of type DescType that indicates the type of data being passed.

dataHandle

A handle to the data being passed.

The descriptor type is a structure of type DescType, which in turn is of data type ResType--that is, a four-character code. Constants, rather than these four-character codes, are usually used to refer to descriptor types. Table 4-2 lists the constants for the basic descriptor types used by the Apple Event Manager.

Table 4-2 Descriptor types used by the Apple Event Manager (excluding those used with object specifier records)

Descriptor type	Value	Description
typeBoolean	'bool'	Boolean value
typeChar	'TEXT'	Unterminated string
typeLongInteger	'long'	32-bit integer
typeInteger	'long'	32-bit integer
typeShortInteger	'shor'	16-bit integer
typeSMInt	'shor'	16-bit integer
typeLongFloat	'doub'	SANE double
typeFloat	'doub'	SANE double
typeShortFloat	'sing'	SANE single
typeSMFloat	'sing'	SANE single
typeExtended	'exte'	SANE extended
typeComp	'comp'	SANE comp
typeMagnitude	'magn'	Unsigned 32-bit integer
typeAEList	'list'	List of descriptor records
typeAERecord	'reco'	List of keyword-specified descriptor records
typeAppleEvent	'aevt'	Apple event record
typeTrue	'true'	TRUE Boolean value
typeFalse	'fals'	FALSE Boolean value
typeAlias	'alis'	Alias record
typeEnumerated	'enum'	Enumerated data
typeType	'type'	Four-character code for event class or event ID
typeAppParameters	'appa'	Process Manager launch parameters
typeProperty	'prop'	Apple event property
typeFSS	'fss '	File system specification
typeKeyword	'keyw'	Apple event keyword
typeSectionH	'sect'	Handle to a section record
typeWildCard	'****'	Matches any type
typeApplSignature	'sign'	Application signature
typeSessionID	'ssid'	Session reference number
typeTargetID	'targ'	Target ID record
typeProcessSerialNumber	'psn '	Process serial number
typeNull	'null'	Nonexistent data (data handle is NIL)

For information about descriptor records and descriptor types used with object specifier records, see the chapter "Resolving and Creating Object Specifier Records" in this book.

Apple event attributes, Apple event parameters, object specifier records, tokens, and most of the other data structures used by the Apple Event Manager are constructed from one or more descriptor records. The Apple Event Manager identifies the various parts of an Apple event by means of keywords associated with the corresponding descriptor records. The AEKeyword data type is defined as a four-character code.

TYPE  AEKeyword = PACKED ARRAY[1..4] OF Char;

Constants are typically used for keywords. A keyword combined with a descriptor record forms a keyword-specified descriptor record, which is defined by a data structure of type AEKeyDesc.

TYPE  AEKeyDesc = 
      RECORD
         descKey:       AEKeyword;     {keyword}
         descContent:   AEDesc;        {descriptor record}
      END;

Field Description

descKey

A four-character code of type AEKeyword that identifies the data in the descContent field.

descContent

A descriptor record of type AEDesc.

Every Apple event includes an attribute that contains the address of the target application. A descriptor record that contains an application's address is called an address descriptor record.

TYPE  AEAddressDesc = AEDesc;       {address descriptor record}

Many Apple Event Manager functions take or return lists of descriptor records in a special descriptor record called a descriptor list. A descriptor list is a structure of data type AEDescList whose data consists of a list of other descriptor records.

TYPE  AEDescList = AEDesc;          {list of descriptor records}

Other Apple Event Manager functions take or return lists of keyword-specified descriptor records in the form of an AE record. An AE record is a structure of data type AERecord whose data handle refers to a list of keyword-specified descriptor records.

TYPE  AERecord = AEDescList;        {list of keyword-specified }
                                    { descriptor records}

The handle for a descriptor list of data type AERecord refers to a list of keyword-specified descriptor records that specify Apple event parameters; they cannot specify Apple event attributes.

Finally, a full-fledged Apple event, including both attributes and parameters, is an Apple event record, which is a structure of data type AppleEvent.

TYPE  AppleEvent = AERecord;        {list of attributes and }
                                    { parameters for an Apple }
                                    { event}

The event class and event ID of an Apple event are specified in Apple Event Manager routines by structures of data types AEEventClass and AEEventID, respectively.

TYPE AEEventClass = PACKED ARRAY[1..4] OF Char;
TYPE AEEventID = PACKED ARRAY[1..4] OF Char;

For more information about descriptor records and the other data structures described in this section, see "Data Structures Within Apple Events," which begins on page 3-10.

With the exception of array data records, which are described in the next section, the other Apple Event Manager data structures used in responding to Apple events are described in "Routines for Responding to Apple Events," beginning on page 4-62, under the descriptions of the routines that use them.