Legacy Document

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

Inside Macintosh: Interapplication Communication /: Chapter 4 - Responding to Apple Events

Summary of Responding to 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 the back of }
                                          { event queue}
   kAEHighPriority         = nAttnMsg;    {put event at the 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 Responding to Apple Events

Creating and Managing the Apple Event Dispatch Tables

FUNCTION AEInstallEventHandler
(theAEEventClass: AEEventClass; 
theAEEventID: AEEventID; 
handler: EventHandlerProcPtr; 
handlerRefcon: LongInt; 
isSysHandler: Boolean): OSErr;
FUNCTION AEGetEventHandler(theAEEventClass: AEEventClass; 
theAEEventID: AEEventID; 
VAR handler: EventHandlerProcPtr; 
VAR handlerRefcon: LongInt; 
isSysHandler: Boolean): OSErr;
FUNCTION AERemoveEventHandler
(theAEEventClass: AEEventClass; theAEEventID: AEEventID; handler: EventHandlerProcPtr; isSysHandler: Boolean): OSErr;

Dispatching Apple Events

FUNCTION AEProcessAppleEvent
(theEventRecord: EventRecord): OSErr;

Getting Data or Descriptor Records Out of Apple Event Parameters and Attributes

FUNCTION AEGetParamPtr(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; 
desiredType: DescType; 
VAR typeCode: DescType; 
dataPtr: Ptr; maximumSize: Size; 
VAR actualSize: Size): OSErr;
FUNCTION AEGetParamDesc(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; desiredType: DescType; 
VAR result: AEDesc): OSErr;
FUNCTION AEGetAttributePtr(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; desiredType: DescType; 
VAR typeCode: DescType; 
dataPtr: Ptr; maximumSize: Size; 
VAR actualSize: Size): OSErr;
FUNCTION AEGetAttributeDesc(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; desiredType: DescType; 
VAR result: AEDesc): OSErr;

Counting the Items in Descriptor Lists

FUNCTION AECountItems(theAEDescList: AEDescList; 
VAR theCount: LongInt): OSErr;

Getting Items From Descriptor Lists

FUNCTION AEGetNthPtr(theAEDescList: AEDescList; index: LongInt; 
desiredType: DescType; 
VAR theAEKeyword: AEKeyword; 
VAR typeCode: DescType; dataPtr: Ptr; 
maximumSize: Size; 
VAR actualSize: Size): OSErr;
FUNCTION AEGetNthDesc(theAEDescList: AEDescList; index: LongInt; 
desiredType: DescType; 
VAR theAEKeyword: AEKeyword; 
VAR result: AEDesc): OSErr;
FUNCTION AEGetArray(theAEDescList: AEDescList; 
arrayType: AEArrayType; 
arrayPtr: AEArrayDataPointer; 
maximumSize: Size; 
VAR itemType: DescType; VAR itemSize: Size; 
VAR itemCount: LongInt): OSErr;

Getting Data and Keyword-Specified Descriptor Records Out of AE Records

FUNCTION AEGetKeyPtr(theAERecord: AERecord; 
theAEKeyword: AEKeyword; 
desiredType: DescType; VAR typeCode: DescType; 
dataPtr: Ptr; maximumSize: Size; 
VAR actualSize: Size): OSErr;
FUNCTION AEGetKeyDesc(theAERecord: AERecord; 
theAEKeyword: AEKeyword; 
desiredType: DescType; 
VAR result: AEDesc): OSErr;

Requesting User Interaction

FUNCTION AESetInteractionAllowed
(level: AEInteractAllowed): OSErr;
FUNCTION AEGetInteractionAllowed
(VAR level: AEInteractAllowed): OSErr;
FUNCTION AEInteractWithUser(timeOutInTicks: LongInt; nmReqPtr: NMRecPtr; 
idleProc: IdleProcPtr): OSErr;

Requesting More Time to Respond to Apple Events

FUNCTION AEResetTimer(reply: AppleEvent): OSErr;

Suspending and Resuming Apple Event Handling

FUNCTION AESuspendTheCurrentEvent
(theAppleEvent: AppleEvent): OSErr;
FUNCTION AEResumeTheCurrentEvent
(theAppleEvent, reply: AppleEvent; 			
dispatcher: EventHandlerProcPtr; handlerRefcon: LongInt): OSErr;
FUNCTION AESetTheCurrentEvent
(theAppleEvent: AppleEvent): OSErr;
FUNCTION AEGetTheCurrentEvent
(VAR theAppleEvent: AppleEvent): OSErr;

Getting the Sizes and Descriptor Types of Descriptor Records

FUNCTION AESizeOfNthItem(theAEDescList: AEDescList; index: LongInt; 
VAR typeCode: DescType; 
VAR dataSize: Size): OSErr;
FUNCTION AESizeOfKeyDesc(theAERecord: AERecord; 
theAEKeyword: AEKeyword; 
VAR typeCode: DescType; 
VAR dataSize: Size): OSErr;
FUNCTION AESizeOfParam(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; 
VAR typeCode: DescType; 
VAR dataSize: Size): OSErr;
FUNCTION AESizeOfAttribute(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword; 
VAR typeCode: DescType; 
VAR dataSize: Size): OSErr;

Deleting Descriptor Records

FUNCTION AEDeleteItem(theAEDescList: AEDescList; 
index: LongInt): OSErr;
FUNCTION AEDeleteKeyDesc(theAERecord: AERecord; 
theAEKeyword: AEKeyword): OSErr;
FUNCTION AEDeleteParam(theAppleEvent: AppleEvent; 
theAEKeyword: AEKeyword): OSErr;

Deallocating Memory for Descriptor Records

FUNCTION AEDisposeDesc(VAR theAEDesc: AEDesc): OSErr;

Coercing Descriptor Types

FUNCTION AECoercePtr(typeCode: DescType; dataPtr: Ptr; 
dataSize: Size; toType: DescType; 
VAR result: AEDesc): OSErr;
FUNCTION AECoerceDesc(theAEDesc: AEDesc; toType: DescType; 
VAR result: AEDesc): OSErr;

Creating and Managing the Coercion Handler Dispatch Tables

FUNCTION AEInstallCoercionHandler
(fromType: DescType; toType: DescType; 
handler: ProcPtr; handlerRefcon: LongInt; fromTypeIsDesc: Boolean; 
isSysHandler: Boolean): OSErr;
FUNCTION AEGetCoercionHandler
(fromType: DescType; toType: DescType; 
VAR handler: ProcPtr; 
VAR handlerRefcon: LongInt; 
VAR fromTypeIsDesc: Boolean; 
isSysHandler: Boolean): OSErr;
FUNCTION AERemoveCoercionHandler
(fromType: DescType; toType: DescType; 
handler: ProcPtr; 
isSysHandler: Boolean): OSErr;

Creating and Managing the Special Handler Dispatch Tables

FUNCTION AEInstallSpecialHandler
(functionClass: AEKeyword; handler: ProcPtr; isSysHandler: Boolean): OSErr;
FUNCTION AEGetSpecialHandler
(functionClass: AEKeyword; 
VAR handler: ProcPtr; 
isSysHandler: Boolean): OSErr;
FUNCTION AERemoveSpecialHandler
(functionClass: AEKeyword; handler: ProcPtr; isSysHandler: Boolean): OSErr;

Getting Information About the Apple Event Manager

{available only in version 1.01 and later versions of Apple Event Manager}
FUNCTION AEManagerInfo (keyword: AEKeyword; 
VAR result: LongInt): OSErr;

Application-Defined Routines

FUNCTION MyEventHandler(theAppleEvent: AppleEvent; reply: AppleEvent; 
handlerRefcon: LongInt): OSErr; 
FUNCTION MyCoercePtr(typeCode: DescType; dataPtr: Ptr; 
dataSize: Size; toType: DescType; 
handlerRefcon: LongInt; 
VAR result: AEDesc): OSErr; 
FUNCTION MyCoerceDesc(theAEDesc: AEDesc; toType: DescType; 
handlerRefcon: LongInt; 
VAR result: AEDesc): OSErr;

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 Responding to Apple Events

Creating and Managing the Apple Event Dispatch Tables

pascal OSErr AEInstallEventHandler
(AEEventClass theAEEventClass, 
AEEventID theAEEventID,
EventHandlerProcPtr handler,
long handlerRefcon, Boolean isSysHandler);
pascal OSErr AEGetEventHandler
(AEEventClass theAEEventClass,
AEEventID theAEEventID,
EventHandlerProcPtr *handler, 
long *handlerRefcon, Boolean isSysHandler);
pascal OSErr AERemoveEventHandler
(AEEventClass theAEEventClass,
AEEventID theAEEventID,
EventHandlerProcPtr handler, 
Boolean isSysHandler);

Dispatching Apple Events

pascal  OSErr  AEProcessAppleEvent 
   (const EventRecord *theEventRecord);

Getting Data or Descriptor Records Out of Apple Event Parameters and Attributes

pascal OSErr AEGetParamPtr(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType desiredType, 
DescType *typeCode, void* dataPtr, 
Size maximumSize, Size *actualSize);
pascal OSErr AEGetParamDesc(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType desiredType, 
AEDesc *result);
pascal OSErr AEGetAttributePtr
(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType desiredType, 
DescType *typeCode, void* dataPtr,
Size maximumSize, Size *actualSize); 
pascal OSErr AEGetAttributeDesc
(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType desiredType, 
AEDesc *result);

Counting the Items in Descriptor Lists

pascal OSErr AECountItems(const AEDescList *theAEDescList, 
long *theCount);

Getting Items From Descriptor Lists

pascal OSErr AEGetNthPtr(const AEDescList *theAEDescList, long index, 
DescType desiredType, AEKeyword *theAEKeyword, 
DescType *typeCode, void* dataPtr,
Size maximumSize, Size *actualSize);
pascal OSErr AEGetNthDesc(const AEDescList *theAEDescList, long index, 
DescType desiredType, AEKeyword *theAEKeyword, 
AEDesc *result);
pascal OSErr AEGetArray(const AEDescList *theAEDescList, 
AEArrayType arrayType, 
AEArrayDataPointer arrayPtr, Size maximumSize, 
DescType *itemType, Size *itemSize, 
long *itemCount);

Getting Data and Keyword-Specified Descriptor Records Out of AE Records

pascal OSErr AEGetKeyPtr(const AERecord *theAERecord, 
AEKeyword theAEKeyword, DescType desiredType, 
DescType *typeCode, void* dataPtr, 
Size maximumSize, Size *actualSize);
pascal OSErr AEGetKeyDesc(const AERecord *theAERecord, 
AEKeyword theAEKeyword, DescType desiredType, 
AEDesc *result);

Requesting User Interaction

pascal OSErr AESetInteractionAllowed
(AEInteractAllowed level);
pascal OSErr AEGetInteractionAllowed
(AEInteractAllowed *level);
pascal OSErr AEInteractWithUser
(long timeOutInTicks, NMRecPtr nmReqPtr, IdleProcPtr idleProc);

Requesting More Time to Respond to Apple Events

pascal OSErr AEResetTimer(const AppleEvent *reply);

Suspending and Resuming Apple Event Handling

pascal OSErr AESuspendTheCurrentEvent
(const AppleEvent *theAppleEvent);
pascal OSErr AEResumeTheCurrentEvent
(const AppleEvent *theAppleEvent,
const AppleEvent *reply,
EventHandlerProcPtr dispatcher,
long handlerRefcon);
pascal OSErr AESetTheCurrentEvent
(const AppleEvent *theAppleEvent);
pascal OSErr AEGetTheCurrentEvent
(AppleEvent *theAppleEvent);

Getting the Sizes and Descriptor Types of Descriptor Records

pascal OSErr AESizeOfNthItem
(const AEDescList *theAEDescList, long index, 
DescType *typeCode, Size *dataSize);
pascal OSErr AESizeOfKeyDesc
(const AERecord *theAERecord, 
AEKeyword theAEKeyword, DescType *typeCode, 
Size *dataSize);
pascal OSErr AESizeOfParam(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType *typeCode, 
Size *dataSize);
pascal OSErr AESizeOfAttribute
(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword, DescType *typeCode, Size *dataSize);

Deleting Descriptor Records

pascal OSErr AEDeleteItem(const AEDescList *theAEDescList, long index);
pascal OSErr AEDeleteKeyDesc
(const AERecord *theAERecord, 
AEKeyword theAEKeyword);
pascal OSErr AEDeleteParam(const AppleEvent *theAppleEvent, 
AEKeyword theAEKeyword);

Deallocating Memory for Descriptor Records

pascal OSErr AEDisposeDesc(AEDesc *theAEDesc);

Coercing Descriptor Types

pascal OSErr AECoercePtr(DescType typeCode, const void* dataPtr, 
Size dataSize, DescType toType, 
AEDesc *result);
pascal OSErr AECoerceDesc(const AEDesc *theAEDesc, DescType toType, 
AEDesc *result);

Creating and Managing the Coercion Handler Dispatch Tables

pascal OSErr AEInstallCoercionHandler
(DescType fromType, DescType toType, 
ProcPtr handler, long handlerRefcon, 
Boolean fromTypeIsDesc, Boolean isSysHandler);
pascal OSErr AEGetCoercionHandler
(DescType fromType, DescType toType, 
ProcPtr *handler, long *handlerRefcon, 
Boolean *fromTypeIsDesc, 
Boolean isSysHandler);
pascal OSErr AERemoveCoercionHandler
(DescType fromType, DescType toType, 
ProcPtr handler, Boolean isSysHandler);

Creating and Managing the Special Handler Dispatch Tables

pascal OSErr AEInstallSpecialHandler
(AEKeyword functionClass, ProcPtr handler, Boolean isSysHandler);
pascal OSErr AEGetSpecialHandler
(AEKeyword functionClass, ProcPtr *handler, 
Boolean isSysHandler);
pascal OSErr AERemoveSpecialHandler
(AEKeyword functionClass, ProcPtr handler, Boolean isSysHandler);

Getting Information About the Apple Event Manager

/*available only in version 1.01 and later versions of Apple Event Manager*/
pascal OSErr AEManagerInfo (AEKeyword keyword, long *result);

Application-Defined Routines

pascal OSErr MyEventHandler(const AppleEvent *theAppleEvent, 
const AppleEvent *reply, long handlerRefcon); 
pascal OSErr MyCoercePtr(DescType typeCode, const void* dataPtr, 
Size dataSize, DescType toType, 
long handlerRefcon, AEDesc *result); 
pascal OSErr MyCoerceDesc(const AEDesc *theAEDesc, DescType toType, long 
handlerRefcon, AEDesc *result);

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

_Pack8

Selector	Routine
$011E	AESetInteractionAllowed
$0204	AEDisposeDesc
$0219	AEResetTimer
$021A	AEGetTheCurrentEvent
$021B	AEProcessAppleEvent
$021D	AEGetInteractionAllowed
$022B	AESuspendTheCurrentEvent
$022C	AESetTheCurrentEvent
$0407	AECountItems
$040E	AEDeleteItem
$0413	AEDeleteKeyDesc
$0413	AEDeleteParam
$0441	AEManagerInfo
$0500	AEInstallSpecialHandler
$0501	AERemoveSpecialHandler
$052D	AEGetSpecialHandler
$0603	AECoerceDesc
$061C	AEInteractWithUser
$0720	AERemoveEventHandler
$0723	AERemoveCoercionHandler
$0812	AEGetKeyDesc
$0812	AEGetParamDesc
$0818	AEResumeTheCurrentEvent
$0826	AEGetAttributeDesc
$0828	AESizeOfAttribute
$0829	AESizeOfKeyDesc
$0829	AESizeOfParam
$082A	AESizeOfNthItem
$091F	AEInstallEventHandler
$0921	AEGetEventHandler
$0A02	AECoercePtr
$0A22	AEInstallCoercionHandler
$0A0B	AEGetNthDesc
$0B24	AEGetCoercionHandler
$0D0C	AEGetArray
$0E11	AEGetKeyPtr
$0E11	AEGetParamPtr
$0E15	AEGetAttributePtr
$100A	AEGetNthPtr

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