Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Interapplication Communication /: Chapter 5 - Creating and Sending Apple Events

Summary of Creating and Sending Apple Events

Pascal Summary

Constants

CONST 
   gestaltAppleEventsAttr     = 'evnt';   {selector for Apple events}
   gestaltAppleEventsPresent  = 0;        {if this bit is set, then Apple }
                                          { Event Manager is available}

   {Apple event descriptor types}
   typeBoolean             = 'bool';      {1-byte Boolean value}
   typeChar                = 'TEXT';      {unterminated string}
   typeSMInt               = 'shor';      {16-bit integer}
   typeInteger             = 'long';      {32-bit integer}
   typeSMFloat             = 'sing';      {SANE single}
   typeFloat               = 'doub';      {SANE double}
   typeLongInteger         = 'long';      {32-bit integer}
   typeShortInteger        = 'shor';      {16-bit integer}
   typeLongFloat           = 'doub';      {SANE double}
   typeShortFloat          = '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';      {NULL or nonexistent data}
   
   {keywords for Apple event parameters}
   keyDirectObject         = '----';      {direct parameter}
   keyErrorNumber          = 'errn';      {error number parameter}
   keyErrorString          = 'errs';      {error string parameter}
   keyProcessSerialNumber  = 'psn ';      {process serial number param}

   {keywords for Apple event attributes}
   keyTransactionIDAttr    = 'tran';      {transaction ID}
   keyReturnIDAttr         = 'rtid';      {return ID}
   keyEventClassAttr       = 'evcl';      {event class}
   keyEventIDAttr          = 'evid';      {event ID}
   keyAddressAttr          = 'addr';      {address of target or }
                                          { client application}
   keyOptionalKeywordAttr  = 'optk';      {list of optional parameters }
                                          { for the Apple event}
   keyTimeoutAttr          = 'timo';      {number of ticks the client }
                                          { will wait}
   keyInteractLevelAttr    = 'inte';      {settings to allow Apple Event }
                                          { Manager to bring server }
                                          { to foreground}
   keyEventSourceAttr      = 'esrc';      {nature of source }
                                          { application}
   keyMissedKeywordAttr    = 'miss';      {first required parameter }
                                          { remaining in an Apple event}
   keyOriginalAddressAttr  = 'from';      {address of original source; }
                                          { available only in version } 
                                          { 1.01 and later versions of }
                                          { the Apple Event Manager}

   {keywords for special handlers}
   keyPreDispatch          = 'phac';      {identifies a handler routine }
                                          { called immediately before the }
                                          { Apple Event Manager dispatches }
                                          { an Apple event}


   keySelectProc           = 'selh';      {selector used with }
                                          { AERemoveSpecialHandler to }
                                          { disable the OSL}

   {keywords for use with AEManagerInfo; available only in version }
   { 1.0.1 and later versions of the Apple Event Manager}
   keyAERecorderCount      = 'recr';      {keyword for recording info}
   keyAEVersion            = 'vers';      {keyword for version info}

   {event class}
   kCoreEventClass         = 'aevt';      {event class for required Apple }
                                          { events}

   {event IDs for required Apple events}
   kAEOpenApplication      = 'oapp';      {event ID for Open }
                                          { Application event}
   kAEOpenDocuments        = 'odoc';      {event ID for Open Documents event}
   kAEPrintDocuments       = 'pdoc';      {event ID for Print Documents }
                                          { event}
   kAEQuitApplication      = 'quit';      {event ID for Quit Application }
                                          { event}
   kAEAnswer               = 'ansr';      {event ID for Apple event replies}
   kAEApplicationDied      = 'obit';      {event ID for Application Died }
                                          { event}

   {constants for setting the sendMode parameter of AESend}
   kAENoReply              = $00000001;   {client doesn't want reply}
   kAEQueueReply           = $00000002;   {client wants server to }
                                          { reply in event queue}
   kAEWaitReply            = $00000003;   {client wants a reply and }
                                          { will give up processor}
   kAENeverInteract        = $00000010;   {server application should }
                                          { not interact with user }
                                          { for this Apple event}
   kAECanInteract          = $00000020;   {server may interact with }
                                          { user for this Apple event }
                                          { to supply information}

   kAEAlwaysInteract       = $00000030;   {server may interact with user }
                                          { for this Apple event even if }
                                          { no information is required}
   kAECanSwitchLayer       = $00000040;   {server should come directly }
                                          { to foreground when appropriate}
   kAEDontReconnect        = $00000080;   {don't reconnect if there }
                                          { is a PPC session closed error}
   kAEWantReceipt          = nReturnReceipt; {client wants return }
                                          { receipt}
   kAEDontRecord           = $00001000;   {don't record this event}
   kAEDontExecute          = $00002000;   {don't excecute this event}

   {constants for setting the sendPriority parameter of AESend}
   kAENormalPriority       = $00000000;   {put event at back of }
                                          { event queue}
   kAEHighPriority         = nAttnMsg;    {put event at front of }
                                          { the event queue}

   {event IDs for recording events; available only in version 1.01 and }
   { later versions of the Apple Event Manager}
   kAEStartRecording       = 'reca';      {event ID for Start Recording }
                                          { event}
   kAEStopRecording        = 'recc';      {event ID for Stop Recording }
                                          { event}
   kAENotifyStartRecording = 'rec1';      {event ID for Recording On event}
   kAENotifyStopRecording  = 'rec0';      {event ID for Recording Off event}
   kAENotifyRecording      = 'recr';      {event ID for Receive Recordable }
                                          { Event event}

   {constant for the returnID parameter of AECreateAppleEvent}
   kAutoGenerateReturnID   = -1;          {tells Apple Event Manager to }
                                          { generate a unique return ID}

   {constant for transaction IDs}
   kAnyTransactionID       = 0;           {the Apple event is not }
                                          { part of a transaction}

   {constants for timeout durations}
   kAEDefaultTimeout       = -1;          {use default timeout value}
   kNoTimeOut              = -2;          {never time out}

   {constants for the dispatcher parameter of AEResumeTheCurrentEvent}
   kAENoDispatch           = 0;           {don't redispatch the Apple event}
   kAEUseStandardDispatch  = -1;          {redispatch the Apple event }
                                          { by using its entry in the }
                                          { Apple event dispatch table}

Data Types

TYPE
   AEEventClass = 
      PACKED ARRAY[1..4] OF Char;            {event class for a high-level }
                                             { event}
   AEEventID = 
      PACKED ARRAY[1..4] OF Char;            {event ID for a high-level }
                                             { event}

   AEKeyword = 
      PACKED ARRAY[1..4] OF Char;            {keyword for a descriptor }
                                             { record}

   DescType                   = ResType;     {descriptor type}

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

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

   AEAddressDesc              = AEDesc;      {address descriptor record}

   AEDescList                 = AEDesc;      {list of descriptor records}

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

   AppleEvent                 = AERecord;    {list of attributes and }
                                             { parameters necessary for }
                                             { an Apple event}
   AESendMode                 = LongInt;     {flags that determine how }
                                             { an Apple event is sent}

   AESendPriority             = Integer;     {send priority of an Apple }
                                             { event}
   AEInteractAllowed = (kAEInteractWithSelf, kAEInteractWithLocal,
                        kAEInteractWithAll); {what processes may }
                                             { interact with the user}

   AEEventSource = (kAEUnknownSource, kAEDirectCall, kAESameProcess,
                    kAELocalProcess, kAERemoteProcess);
                                             {the source of an Apple }
                                             { event}

   AEArrayType = (kAEDataArray, kAEPackedArray, kAEHandleArray, 
                  kAEDescArray, kAEKeyDescArray);
                                             {type of an Apple event array}
   AEArrayData = 
   RECORD                                    {data for an Apple event array}
      CASE AEArrayType OF
      kAEDataArray:
         (AEDataArray: ARRAY[0..0] OF Integer);
      kAEPackedArray:
         (AEPackedArray: Packed Array[0..0] OF Char);
      kAEHandleArray:
         (AEHandleArray: Array[0..0] OF Handle);
      kAEDescArray:
         (AEDescArray: Array[0..0] OF AEDesc);
      kAEKeyDescArray:
         (AEKeyDescArray: Array[0..0] OF AEKeyDesc);
   END;
   
   AEArrayDataPointer = ^AEArrayData;

   EventHandlerProcPtr = ProcPtr;            {pointer to an Apple event }
                                             { handler}
   IdleProcPtr = ProcPtr;                    {pointer to an application's }
                                             { idle function}
   EventFilterProcPtr = ProcPtr;             {pointer to an application's }
                                             { filter function}

Routines for Creating and Sending Apple Events

Creating Apple Events

FUNCTION AECreateAppleEvent(theAEEventClass: AEEventClass; 
theAEEventID: AEEventID; 
target: AEAddressDesc; returnID: Integer; 
transactionID: LongInt; 
VAR result: AppleEvent): OSErr;

Creating and Duplicating Descriptor Records

FUNCTION AECreateDesc(typeCode: DescType; dataPtr: Ptr; 
dataSize: Size; VAR result: AEDesc): OSErr;
FUNCTION AEDuplicateDesc(theAEDesc: AEDesc; VAR result: AEDesc): OSErr;

Creating Descriptor Lists and AE Records

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

Adding Items to Descriptor Lists

FUNCTION AEPutPtr(theAEDescList: AEDescList; index: LongInt; 
typeCode: DescType; dataPtr: Ptr; 
dataSize: Size): OSErr;
FUNCTION AEPutDesc(theAEDescList: AEDescList; index: LongInt; 
theAEDesc: AEDesc): OSErr;
FUNCTION AEPutArray(theAEDescList: AEDescList; 
arrayType: AEArrayType; 
arrayPtr: AEArrayDataPointer; 
itemType: DescType; itemSize: Size; 
itemCount: LongInt): OSErr;

Adding Data and Descriptor Records to AE Records

FUNCTION AEPutKeyPtr(theAERecord: AERecord; 
theAEKeyword: AEKeyword; typeCode: DescType; 
dataPtr: Ptr; dataSize: Size): OSErr;
FUNCTION AEPutKeyDesc(theAERecord: AERecord; 
theAEKeyword: AEKeyword; 
theAEDesc: AEDesc): OSErr;

Adding Parameters and Attributes to Apple Events

FUNCTION AEPutParamPtr(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; typeCode: DescType; 
dataPtr: Ptr; dataSize: Size): OSErr;
FUNCTION AEPutParamDesc(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; 
theAEDesc: AEDesc): OSErr;
FUNCTION AEPutAttributePtr(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; typeCode: DescType; 
dataPtr: Ptr; dataSize: Size): OSErr;
FUNCTION AEPutAttributeDesc(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; 
theAEDesc: AEDesc): OSErr;

Sending Apple Events

FUNCTION AESend(theAppleEvent: AppleEvent; 
VAR reply: AppleEvent; sendMode: AESendMode; 
sendPriority: AESendPriority; 
timeOutInTicks: LongInt; 
idleProc: IdleProcPtr; 
filterProc: EventFilterProcPtr): OSErr;

Application-Defined Routines

FUNCTION MyIdleFunction(VAR event: EventRecord;
VAR sleepTime: LongInt; 
VAR mouseRgn: RgnHandle): Boolean;
FUNCTION MyReplyFilter(VAR event: EventRecord; 
returnID: LongInt; transactionID: LongInt; 
sender: AEAddressDesc): Boolean;

C Summary

Constants

enum {
      #define gestaltAppleEventsAttr     'evnt' /*selector for Apple events*/
      gestaltAppleEventsPresent        = 0   /*if this bit is set, then */
                                             /* Apple Event Manager is */
};                                           /* available*/

      /*Apple event descriptor types*/
enum  {
      typeBoolean             = 'bool',      /*1-byte Boolean value*/
      typeChar                = 'TEXT',      /*unterminated string*/
      typeSMInt               = 'shor',      /*16-bit integer*/
      typeInteger             = 'long',      /*32-bit integer*/
      typeSMFloat             = 'sing',      /*SANE single*/
      typeFloat               = 'doub',      /*SANE double*/
      typeLongInteger         = 'long',      /*32-bit integer*/
      typeShortInteger        = 'shor',      /*16-bit integer*/
      typeLongFloat           = 'doub',      /*SANE double*/
      typeShortFloat          = '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*/
};

enum {
      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 ID*/
      typeTargetID            = 'targ',      /*target ID record*/
      typeProcessSerialNumber = 'psn ',      /*process serial number*/
      typeNull                = 'null'       /*NULL or nonexistent data*/
};

      /*keywords for Apple event parameters*/
enum {
      keyDirectObject         = '----',      /*direct parameter*/
      keyErrorNumber          = 'errn',      /*error number parameter*/
      keyErrorString          = 'errs',      /*error string parameter*/
      keyProcessSerialNumber  = 'psn '       /*process serial number param*/
};
      /*keywords for Apple event attributes*/
enum {
      keyTransactionIDAttr    = 'tran',      /*transaction ID*/
      keyReturnIDAttr         = 'rtid',      /*return ID*/
      keyEventClassAttr       = 'evcl',      /*event class*/
      keyEventIDAttr          = 'evid',      /*event ID*/
      keyAddressAttr          = 'addr',      /*address of target or */
                                             /* client application*/
      keyOptionalKeywordAttr  = 'optk',      /*list of optional parameters */
                                             /* for the Apple event*/
      keyTimeoutAttr          = 'timo',      /*number of ticks the client */
                                             /* will wait*/
      keyInteractLevelAttr    = 'inte',      /*settings to allow Apple */
                                             /* Event Mgr to bring */
                                             /* server to foreground*/
      keyEventSourceAttr      = 'esrc',      /*nature of source */
                                             /* application*/
      keyMissedKeywordAttr    = 'miss',      /*first required parameter */
                                             /* remaining in an Apple */
                                             /* event*/
      keyOriginalAddressAttr  = 'from'       /*address of original source; */
                                             /* available only in version */ 
                                             /* 1.01 and later versions of */
                                             /* the Apple Event Manager*/
};
      
      /*keywords for special handlers*/
enum {
      keyPreDispatch          = 'phac',      /*identifies a handler */
                                             /* routine that is called */
                                             /* immediately before the */
                                             /* Apple Event Manager */
                                             /* dispatches an Apple event*/
      keySelectProc           = 'selh',      /*selector used with */
                                             /* AERemoveSpecialHandler to */
                                             /* disable the OSL*/
      /*keywords for use with AEManagerInfo, available only in version */
      /* 1.0.1 and later versions of the Apple Event Manager*/
      keyAERecorderCount      = 'recr',      /*keyword for recording info*/
      keyAEVersion            = 'vers',      /*keyword for version info*/

      /*event class*/
      kCoreEventClass         = 'aevt'       /*event class for required */
                                             /* Apple events*/
};

      /*event IDs for required Apple events*/
enum {
      kAEOpenApplication      = 'oapp',      /*event ID for Open */
                                             /* Application event*/
      kAEOpenDocuments        = 'odoc',      /*event ID for Open */
                                             /* Documents event*/

      kAEPrintDocuments       = 'pdoc',      /*event ID for Print */
                                             /* Documents event*/
      kAEQuitApplication      = 'quit',      /*event ID for Quit */
                                             /* Application event*/
      kAEAnswer               = 'ansr',      /*event ID for Apple event */
                                             /* replies*/
      kAEApplicationDied      = 'obit'       /*event ID for Application */
                                             /* Died event*/
};
      /*constants for setting the sendMode parameter of AESend*/
enum {
      kAENoReply              = 0x00000001,  /*client doesn't want reply*/
      kAEQueueReply           = 0x00000002,  /*client wants server to */
                                             /* reply in event queue*/
      kAEWaitReply            = 0x00000003,  /*client wants a reply and */
                                             /* will give up processor*/
      kAENeverInteract        = 0x00000010,  /*server application should */
                                             /* not interact with user */
                                             /* for this Apple event*/
      kAECanInteract          = 0x00000020,  /*server may interact with */
                                             /* user for this Apple event */
                                             /* to supply information*/
      kAEAlwaysInteract       = 0x00000030,  /*server may interact with */
                                             /* user for this Apple event */
                                             /* even if no information */
                                             /* is required*/
      kAECanSwitchLayer       = 0x00000040,  /*server should come */
                                             /* directly to foreground */
                                             /* when appropriate*/
      kAEDontReconnect        = 0x00000080,  /*don't reconnect if there */
                                             /* is a PPC session closed */
                                             /* error*/
      kAEWantReceipt          = nReturnReceipt, /*client wants return */
                                             /* receipt*/
      kAEDontRecord           = 0x00001000,  /*don't record this event*/
      kAEDontExecute          = 0x00002000,  /*don't excecute this event*/

      /*constants for setting the sendPriority parameter of AESend*/
      kAENormalPriority       = 0x00000000,  /*post message at end of */
                                             /* event queue*/
      kAEHighPriority         = nAttnMsg     /*post message at front of */
                                             /* event queue*/
};
      /*event IDs for recording events; available only in version 1.01 and */
      /* later versions of the Apple Event Manager*/
enum {
      kAEStartRecording       = 'reca',      /*event ID for Start */
                                             /* Recording event*/
      kAEStopRecording        = 'recc',      /*event ID for Stop */
                                             /* Recording event*/
      kAENotifyStartRecording = 'rec1',      /*event ID for Recording On */
                                             /* event*/
      kAENotifyStopRecording  = 'rec0',      /*event ID for Recording Off */
                                             /* event*/
      kAENotifyRecording      = 'recr'       /*event ID for Receive */
                                             /* Recordable Event event*/
};
enum {
      /*constant for the returnID parameter of AECreateAppleEvent*/
      kAutoGenerateReturnID   = -1,          /*tells Apple Event Manager */
                                             /* to generate a unique */
                                             /* return ID*/
      /*constant for transaction IDs*/
      kAnyTransactionID       = 0,           /*the Apple event is not */
                                             /* part of a transaction*/

      /*constants for timeout durations*/
      kAEDefaultTimeout       = -1,          /*use default timeout value*/
      kNoTimeOut              = -2,          /*never time out*/
      /*constants for the dispatcher parameter of AEResumeTheCurrentEvent*/
      kAENoDispatch           = 0,           /*don't redispatch the */
                                             /* Apple event*/
      kAEUseStandardDispatch  = -1        /*redispatch the Apple event */
                                             /* by using its entry in the */
                                             /* Apple event dispatch table*/
};

Data Types

typedef unsigned long AEEventClass;          /*event class for a */
                                             /* high-level event*/
typedef unsigned long AEEventID;             /*event ID for a high-level */
                                             /* event*/
typedef unsigned long AEKeyword;             /*keyword for a descriptor */
                                             /* record*/
typedef ResType DescType;                    /*descriptor type*/

struct AEDesc {                              /*descriptor record*/
   DescType descriptorType;                  /*type of data being passed*/
   Handle dataHandle;                        /*handle to data being passed*/
};
typedef struct AEDesc AEDesc;

struct AEKeyDesc {                           /*keyword-specified */
                                             /* descriptor record*/
   AEKeyword descKey;                        /*keyword*/
   AEDesc descContent;                       /*descriptor record*/
};
typedef struct AEKeyDesc AEKeyDesc;

typedef AEDesc AEAddressDesc;                /*address descriptor record*/
typedef AEDesc AEDescList;                   /*list of descriptor records*/
typedef AEDescList AERecord;                 /*list of keyword-specified */
                                             /* descriptor records*/
typedef AERecord AppleEvent;                 /*list of attributes and */
                                             /* parameters necessary for */
                                             /* an Apple event*/
typedef long AESendMode;                     /*flags that determine how */
                                             /* an Apple event is sent*/



typedef short AESendPriority;                /*send priority of an Apple */
                                             /* event*/

enum { kAEInteractWithSelf, kAEInteractWithLocal,
       kAEInteractWithAll };                 /*what processes may */
typedef unsigned char AEInteractAllowed;     /* interact with the user*/

enum { kAEUnknownSource, kAEDirectCall, kAESameProcess, kAELocalProcess, 
       kAERemoteProcess };                   /*the source of an Apple */
typedef unsigned char AEEventSource;         /* event*/
enum { kAEDataArray, kAEPackedArray, kAEHandleArray, 
       kAEDescArray, kAEKeyDescArray };      /*type of an Apple event */
typedef unsigned char AEArrayType;           /* array*/

union AEArrayData {                          /*data for an Apple event */
   short kAEDataArray[1];                    /* array*/
   char kAEPackedArray[1];
   Handle kAEHandleArray[1];
   AEDesc kAEDescArray[1];
   AEKeyDesc kAEKeyDescArray[1];
};
typedef union AEArrayData AEArrayData;

typedef AEArrayData *AEArrayDataPointer;

typedef ProcPtr EventHandlerProcPtr;         /*pointer to an Apple event */
                                             /* handler*/
typedef ProcPtr IdleProcPtr;                 /*pointer to an application's */
                                             /* idle function*/
typedef ProcPtr EventFilterProcPtr;          /*pointer to an application's */
                                             /* filter function*/

Routines for Creating and Sending Apple Events

Creating Apple Events

pascal OSErr AECreateAppleEvent
(AEEventClass theAEEventClass, 
AEEventID theAEEventID, 
const AEAddressDesc *target, short returnID, long transactionID, AppleEvent *result);

Creating and Duplicating Descriptor Records

pascal OSErr AECreateDesc(DescType typeCode, const void* dataPtr, 
Size dataSize, AEDesc *result);
pascal OSErr AEDuplicateDesc
(const AEDesc *theAEDesc, AEDesc *result);

Creating Descriptor Lists and AE Records

pascal OSErr AECreateList(const void* factoringPtr, Size factoredSize, 
Boolean isRecord, AEDescList *resultList);

Adding Items to Descriptor Lists

pascal OSErr AEPutPtr(const AEDescList *theAEDescList, long index, 
DescType typeCode, const void* dataPtr, 
Size dataSize);
pascal OSErr AEPutDesc(const AEDescList *theAEDescList, long index, 
const AEDesc *theAEDesc);
pascal OSErr AEPutArray(const AEDescList *theAEDescList, 
AEArrayType arrayType, 
const AEArrayDataPointer *arrayPtr, 
DescType itemType, Size itemSize, 
long itemCount);

Adding Data and Descriptor Records to AE Records

pascal OSErr AEPutKeyPtr(const AERecord *theAERecord, 
AEKeyword theAEKeyword, DescType typeCode, 
const void* dataPtr, Size dataSize);
pascal OSErr AEPutKeyDesc(const AERecord *theAERecord, 
AEKeyword theAEKeyword, 
const AEDesc *theAEDesc);

Adding Parameters and Attributes to Apple Events

pascal OSErr AEPutParamPtr(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType typeCode, 
const void* dataPtr, Size dataSize);
pascal OSErr AEPutParamDesc(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, 
const AEDesc *theAEDesc);
pascal OSErr AEPutAttributePtr
(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType typeCode, const void* dataPtr, Size dataSize);
pascal OSErr AEPutAttributeDesc
(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, 
const AEDesc *theAEDesc);

Sending Apple Events

pascal OSErr AESend(const AppleEvent *theAppleEvent, 
AppleEvent *reply, AESendMode sendMode, 
AESendPriority sendPriority, 
long timeOutInTicks, IdleProcPtr idleProc, 
EventFilterProcPtr filterProc);

Application-Defined Routines

pascal Boolean MyIdleFunction
(const EventRecord *event,
long *sleepTime, RgnHandle *mouseRgn);
pascal Boolean MyReplyFilter
(const EventRecord *event, 
long returnID, long transactionID,
AEAddressDesc sender);

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

_Pack8

Selector	Routine
$0405	AEDuplicateDesc
$0609	AEPutDesc
$0610	AEPutKeyDesc
$0610	AEPutParamDesc
$0627	AEPutAttributeDesc
$0706	AECreateList
$0825	AECreateDesc
$0A08	AEPutPtr
$0A0F	AEPutKeyPtr
$0A0F	AEPutParamPtr
$0A16	AEPutAttributePtr
$0B0D	AEPutArray
$0B14	AECreateAppleEvent
$0D17	AESend

Result Codes
noErr 0 No error
paramErr -50 Parameter error (for example, value of handler pointer is `NIL` or odd)
eLenErr -92 Buffer too big to send
memFullErr -108 Not enough room in heap zone
userCanceledErr -128 User canceled an operation
procNotFound -600 No eligible process with specified process serial number
bufferIsSmall -607 Buffer is too small
noOutstandingHLE -608 No outstanding high-level event
connectionInvalid -609 Nonexistent signature or session ID
noUserInteractionAllowed -610 Background application sends event requiring authentication
`noPortErr` -903 Client hasn't set `'SIZE'` resource to indicate awareness of high-level events
destPortErr -906 Server hasn't set `'SIZE'` resource to indicate awareness of high-level events, or else is not present
sessClosedErr -917 The `kAEDontReconnect` flag in the `sendMode` parameter was set, and the server quit and then restarted
errAECoercionFail -1700 Data could not be coerced to the requested descriptor type
errAEDescNotFound -1701 Descriptor record was not found
errAECorruptData -1702 Data in an Apple event could not be read
errAEWrongDataType -1703 Wrong descriptor type
errAENotAEDesc -1704 Not a valid descriptor record
errAEBadListItem -1705 Operation involving a list item failed
errAENewerVersion -1706 Need a newer version of the Apple Event Manager
errAENotAppleEvent -1707 Event is not an Apple event
errAEEventNotHandled -1708 Event wasn't handled by an Apple event handler
errAEReplyNotValid -1709 `AEResetTimer` was passed an invalid reply
errAEUnknownSendMode -1710 Invalid sending mode was passed
errAEWaitCanceled -1711 User canceled out of wait loop for reply or receipt
errAETimeout -1712 Apple event timed out
errAENoUserInteraction -1713 No user interaction allowed
errAENotASpecialFunction -1714 The keyword is not valid for a special function
errAEParamMissed -1715 Handler cannot understand a parameter the client considers required
errAEUnknownAddressType -1716 Unknown Apple event address type
errAEHandlerNotFound -1717 No handler found for an Apple event or a coercion, or no object callback function found
errAEReplyNotArrived -1718 Reply has not yet arrived
errAEIllegalIndex -1719 Not a valid list index
errAEImpossibleRange -1720 The range is not valid because it is impossible for a range to include the first and last objects that were specified; an example is a range in which the offset of the first object is greater than the offset of the last object
errAEWrongNumberArgs -1721 The number of operands provided for the `kAENot` logical operator is not 1
errAEAccessorNotFound -1723 There is no object accessor function for the specified object class and token descriptor type
errAENoSuchLogical -1725 The logical operator in a logical descriptor record is not `kAEAnd`, `kAEOr`, or `kAENot`
errAEBadTestKey -1726 The descriptor record in a test key is neither a comparison descriptor record nor a logical descriptor record
errAENotAnObjectSpec -1727 The `objSpecifier` parameter of `AEResolve` is not an object specifier record
errAENoSuchObject -1728 A run-time resolution error, for example: object specifier record asked for the third element, but there are only two
errAENegativeCount -1729 Object-counting function returned negative value
errAEEmptyListContainer -1730 The container for an Apple event object is specified by an empty list
errAEUnknownObjectType -1731 Descriptor type of token returned by `AEResolve` is not known to server application
errAERecordingIsAlreadyOn -1732 Attempt to turn recording on when it is already on

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

noErr	0	No error
paramErr	-50	Parameter error (for example, value of handler pointer is `NIL` or odd)
eLenErr	-92	Buffer too big to send
memFullErr	-108	Not enough room in heap zone
userCanceledErr	-128	User canceled an operation
procNotFound	-600	No eligible process with specified process serial number
bufferIsSmall	-607	Buffer is too small
noOutstandingHLE	-608	No outstanding high-level event
connectionInvalid	-609	Nonexistent signature or session ID
noUserInteractionAllowed	-610	Background application sends event requiring authentication
`noPortErr`	-903	Client hasn't set `'SIZE'` resource to indicate awareness of high-level events
destPortErr	-906	Server hasn't set `'SIZE'` resource to indicate awareness of high-level events, or else is not present
sessClosedErr	-917	The `kAEDontReconnect` flag in the `sendMode` parameter was set, and the server quit and then restarted
errAECoercionFail	-1700	Data could not be coerced to the requested descriptor type
errAEDescNotFound	-1701	Descriptor record was not found
errAECorruptData	-1702	Data in an Apple event could not be read
errAEWrongDataType	-1703	Wrong descriptor type
errAENotAEDesc	-1704	Not a valid descriptor record
errAEBadListItem	-1705	Operation involving a list item failed
errAENewerVersion	-1706	Need a newer version of the Apple Event Manager
errAENotAppleEvent	-1707	Event is not an Apple event
errAEEventNotHandled	-1708	Event wasn't handled by an Apple event handler
errAEReplyNotValid	-1709	`AEResetTimer` was passed an invalid reply
errAEUnknownSendMode	-1710	Invalid sending mode was passed
errAEWaitCanceled	-1711	User canceled out of wait loop for reply or receipt
errAETimeout	-1712	Apple event timed out
errAENoUserInteraction	-1713	No user interaction allowed
errAENotASpecialFunction	-1714	The keyword is not valid for a special function
errAEParamMissed	-1715	Handler cannot understand a parameter the client considers required
errAEUnknownAddressType	-1716	Unknown Apple event address type
errAEHandlerNotFound	-1717	No handler found for an Apple event or a coercion, or no object callback function found
errAEReplyNotArrived	-1718	Reply has not yet arrived
errAEIllegalIndex	-1719	Not a valid list index
errAEImpossibleRange	-1720	The range is not valid because it is impossible for a range to include the first and last objects that were specified; an example is a range in which the offset of the first object is greater than the offset of the last object
errAEWrongNumberArgs	-1721	The number of operands provided for the `kAENot` logical operator is not 1
errAEAccessorNotFound	-1723	There is no object accessor function for the specified object class and token descriptor type
errAENoSuchLogical	-1725	The logical operator in a logical descriptor record is not `kAEAnd`, `kAEOr`, or `kAENot`
errAEBadTestKey	-1726	The descriptor record in a test key is neither a comparison descriptor record nor a logical descriptor record
errAENotAnObjectSpec	-1727	The `objSpecifier` parameter of `AEResolve` is not an object specifier record
errAENoSuchObject	-1728	A run-time resolution error, for example: object specifier record asked for the third element, but there are only two
errAENegativeCount	-1729	Object-counting function returned negative value
errAEEmptyListContainer	-1730	The container for an Apple event object is specified by an empty list
errAEUnknownObjectType	-1731	Descriptor type of token returned by `AEResolve` is not known to server application
errAERecordingIsAlreadyOn	-1732	Attempt to turn recording on when it is already on