MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
� 2001 K. J. Bricknell

CHAPTER 10

APPLE EVENTS

Introduction

Apple events are high-level events whose structure and interpretation are determined by the Apple Event InterProcess Messaging Protocol (AEIMP). Applications typically use Apple events to request services and information from other applications and to provide services and information in response to such requests.

In the world of Apple events:

• The client application is the application that initiates communication between two applications that support Apple events. It sends the Apple event that requests a service or information.

• The server application is the application that provides the requested service or information.

As an example, Fig 1 shows a client application (the Finder) sending an Apple event known as the Open Documents event to the server application (My Application) requesting the latter to open the documents named Document A and Document B. My Application responds by opening windows for the specified documents.

An application can also send Apple events to itself, thus acting as both client and server.

Applications can rely on a vocabulary of standard Apple events, defined in the Apple Event Registry Standard Suites, to identify Apple events and respond appropriately. The standard suites (a suite being a group of Apple events that are usually implemented together) include:

• The required suite, which consists of five Apple events that the Finder sends to applications. The required Apple events are:
  • Open Application.

  • Re-open Application.

  • Open Documents.

  • Print Documents.

  • Quit Application.

  The Finder uses the required Apple events as part of the mechanism for launching and terminating applications. Your application must support the required Apple events.

• The core suite, which consists of the basic Apple events, including Get Data, Set Data, Move, Delete and Save, that nearly all applications use to communicate.

• The functional-area suite, which consists of a group of Apple events which support a related functional area, and which include the Text suite and the Database suite.

• The appearance suite, which pertains to Mac OS 8/9 only, and which consists of four Apple events used to advise all foreground applications when one of the following changes has been made in the Mac OS 8/9 Appearance control panel:

  • Appearance. (Since the only Appearance ever made available by Apple is Platinum, this event will not be considered further.)

  • Large system font.

  • Small system font.

  • Views font.

Another important Apple event, of relevance on Mac OS X only, is the Show Preferences event. This event is sent to your application when the user chooses the Preferences� item in the Mac OS X Application menu.

This chapter is primarily concerned with the required Apple events, the Appearance Manager Apple events, and the Show Preferences event ,exploring the subject of Apple events only to the extent necessary to gain an understanding of the measures involved in supporting these events.

Apple Event Attributes and Parameters

An Apple event comprises attributes and, possibly, parameters. Attributes identify the Apple event and denote the task to be performed. Parameters contain information to be used by the target application.

Apple Event Attributes

An Apple event attribute is a structure which identifies, principally, the event class, event ID, and target application.

Event Class

The event class is identifies a group of related Apple events. It appears in the message field of the event structure for an Apple event (see Fig 2). For example:

• The required Apple events have the value 'aevt' in the message field of their event structures. ('aevt' is represented by the constant kCoreEventClass.)

• The Appearance Manager Apple events have the value 'appr' in the message field of their event structures. 'appr' is represented by the constant kAppearanceEventClass.

Event ID

The event ID identifies the particular event within the event class, uniquely identifying the Apple event and communicating the action the Apple event should perform. As shown at Fig 2, the event ID appears in the where field of the event structure for an Apple event. For example, for an Open Documents event, the where field will contain the value 'odoc' (which is represented by the constant kAEOpenDocuments.)

The following are the event IDs for the five required Apple events and the four Appearance Manager Apple events.

Target Application

In addition to the event class and event ID, every Apple event must include an attribute which specifies the target application's address.

Apple Event Parameters

An Apple event parameter is a structure containing data that the target application uses. Apple events can use standard data types, such as strings of text, long integers, boolean values, and alias structures, for the data in their parameters.

There are various kinds of Apple event parameters, including direct parameters and additional parameters.

Direct Parameters

Direct parameters usually specify the data to be acted upon by the target application. For example, a list of documents is contained in the direct parameter of the Open Documents event.

Additional Parameters

Some Apple events also take additional parameters. The target application uses these additional parameters (for example, operands in an equation) in addition to the data specified in the direct parameter.

Required and Optional Parameters

All parameters are described as either required parameters or optional parameters in the Apple Event Registry: Standard Suites. Direct parameters are usually defined as required parameters.

Attributes and Parameters in an Open Documents Apple Event

Fig 3 shows the major Apple event attributes and the direct parameter for the Open Documents event.

To process this event, the application My Application would use the AEProcessAppleEvent function, which uses the event class and event ID attributes to dispatch the event to its Open Documents handler. The Open Documents handler opens the documents specified in the direct parameter.

Data Structures Within Apple Events

The Apple Event Manager constructs its own internal data structures to contain the information in an Apple event.

Descriptor Structures

The Apple Event Manager uses descriptor structures, which you can think of as building blocks, to construct Apple event attributes and parameters. Descriptor structures comprise a handle to data and a descriptor type. The descriptor type identifies the type of data to which the handle refers:

     struct AEDesc
     {
       DescType      descriptorType;  // Type of data.
       AEDataStorage dataHandle;      // Handle to data.
     };
     typedef struct AEDesc AEDesc;

In Carbon, the dataHandle field is opaque. You must use the accessor functions AEGetDescData and AEGetDescDataSize to access the data in this field.

The descriptor type is of type DescType, that is, a four-character code. The following are the codes for some of the major descriptor types, the constants used to represent them, and the kind of data they identify:

Fig 4 illustrates the logical arrangement of two descriptor structures. The first specifies that the data handle refers to an unterminated string. The second specifies that the data handle refers to a four-character code, in this case 'aevt' (which is represented by the constant kCoreEventClass).

Address Descriptor Structure

Every Apple event includes an attribute specifying the address of the target application. A descriptor structure which contains an application's address is called an address descriptor structure:

     typedef AEDesc AEAddressDesc;  // An AEDesc which contains addressing data.

Keyword-Specified Descriptor Structures

The Apple Event Manager assembles the various descriptor structures into an Apple event. Your application cannot access the contents of the Apple event directly; rather, Event Manager functions must be used to request each attribute and parameter by keyword. Keywords, which are four-character codes of type AEKeyword, are used to keep track of various descriptor structures.

The following are typical keywords and the constants used to represent them:

Keywords are associated with specific descriptor structures by means of keyword-specified descriptor structures:

     struct AEKeyDesc 
     {
       AEKeyword descKey;      // Keyword.
       AEDesc    descContent;  // Descriptor structure.
     };
     typedef struct AEKeyDesc AEKeyDesc;

Descriptor Lists, AE Structures, and AppleEvent Structures

Descriptor Lists

To extract data from an Apple event, you use Apple Event Manager functions to copy data to a buffer, to return a descriptor structure whose data handle refers to a copy of the data, or to return descriptor lists, which are lists of descriptor structures. A descriptor list is a descriptor structure whose handle refers to a list of other descriptor structures (unless it is an empty list).

Fig 5 illustrates the logical arrangement of the descriptor list that specifies the direct parameter of the Open Documents event shown at Fig 3.

This descriptor list provides the data for a keyword-specified descriptor structure.

AE Structure

Keyword-specified descriptor structures can in turn be combined into an AE structure. An AE structure is a descriptor list of type AERecord:

     typedef AEDescList AERecord;  // List of keyword-specified descriptor structures.

The handle for a descriptor list of type AERecord refers to a list of keyword-specified descriptor structures that can be used to construct Apple event parameters.

Apple Event Structure

An Apple event structure is another special descriptor list of data type AppleEvent:

     typedef AERecord AppleEvent;  // List of attributes and parameters for Apple event.

An Apple event structure describes an Apple event. The data for an Apple event structure, like the data for an AE structure, consists of a list of keyword-specified descriptor structures. The difference between an AE structure and an Apple event structure is that the data in the latter is divided into two parts, the first for attributes and the second for parameters.

Passing Descriptor Lists, AE Structures and Apple Event Structures to Apple Event Manager Functions

You can pass an Apple event structure to any Apple Event Manager function that expects an AE structure, and you can pass Apple event structures and AE structures, as well as descriptor lists and descriptor structures, to any Apple Event Manager functions that expect structures of data type AEDesc.

Example Complete Apple Event

Fig 6 shows an example of a complete Apple event. This is a data structure of type AppleEvent which contains a list of keyword-specified descriptor structures containing the attributes and parameters of an Open Documents event.

Handling Apple Events

To request a service or information, a client application uses the Apple Event Manager to create and send an Apple event. To respond, a server application uses the Apple Event Manager to extract data from the attributes and parameters of the Apple event. In addition, and where necessary, the server application adds requested data to the reply event returned to the client by the Apple Event Manager.

As previously stated, your application should, at the very least, support the required Apple events sent by the Finder. Your application must therefore:

• Set the isHighLevelEventAware flag in your application's 'SIZE' resource.

• Test for high-level events in the event loop. An Apple event (like all high-level events) is identified by a message class of kHighLevelEvent in the what field of the event structure.

• Use AEProcessAppleEvent to process the Apple events. AEProcessAppleEvent examines the data in the event class and event ID attributes so as to identify the Apple event and then calls the appropriate Apple event handler provided by your application.

• Provide handlers for the required Apple events in your application. Your Apple event handlers must extract the pertinent data from the Apple event, perform the requested action, and return a result.

• Use AEInstallEventHandler to install your Apple event handlers in an Apple event dispatch table for your application. The Apple event dispatch table is used by the Apple Event Manager to map Apple events to your application's handlers. Calls to AEProcessAppleEvent cause the Apple Event Manager to check the dispatch table and, if your application has installed a handler for the event, call the handler.

Apple Event Handlers

Each Apple event handler must be a function which uses this syntax:

     OSErr  theEventHandler(AppleEvent *appleEvent,
                                 AppleEvent *reply,
                                 long handlerRefcon);

Apple event handlers must generally perform the following tasks:

• Extract the attributes and parameters from the Apple event.

• Check that all required parameters have been extracted.

• Perform the action requested by the Apple event.

• Dispose of any copies of the descriptor structures that have been created.

• Add information to the reply Apple event if requested.

Extracting and Checking Data

You must use Apple Event Manager functions to extract the data from Apple events. The following are the main functions involved:

Data Type Coercion

You can specify the descriptor type in the resulting data from these functions. If this type is different from the descriptor type of the attribute or parameter, the Apple Event Manager attempts to coerce it to the specified type. In the direct parameter of the Open Documents event, for example, each descriptor structure in the descriptor list is an alias structure and each alias structure specifies a document to be opened. All your application usually needs to open a document is a file system specification structure (FSSpec) of the document. When you extract the descriptor structure from the descriptor list, you can request that the Apple Event Manager return the data to your application as a file system specification structure instead of an alias structure.

Checking That All Required Parameters Have Been Retrieved

After extracting all known Apple event parameters, your handler should check that it has retrieved all the parameters that the source application considered to be required. To do this, determine whether the keyMissedKeywordAttr attribute exists. If this attribute does exist, your handler has not retrieved all the required parameters, and it should return an error.

Performing the Requested Action and Returning a Result

When your application responds to an Apple event, it should perform the standard action requested by the event.

When your handler returns a non-zero result code, the Apple Event Manager adds a keyErrorNumber parameter, containing the result code that your handler returns, to the reply Apple event.

Disposing of Copies of Descriptor Structures

When your handler is finished with a copy of a descriptor structure created by AEGetParamDesc and related functions, it should dispose of it by calling AEDisposeDesc.

Required Apple Events - Contents and Required Action

Your application receives the five required Apple events from the Finder in these circumstances:

• If your application is not open and the user elects to open it from the Finder without opening or printing any documents (either by double clicking the application's icon, selecting the icon and choosing Open from the Finder's File menu, or choosing it from the Mac OS 8/9 Apple menu), the Finder calls the Process Manager to launch your application and then sends your application an Open Application event.

• If your application is already open and the user attempts to "open" it again, the Finder sends your application a Re-open Application event.

  The Re-open Application event was introduced with MAC OS 8 to cater for a situation which could confuse inexperienced users. The specific situation is where the application is open but has no open windows. Because of the absence of a window, the user does not realise that the application is running, attempts to "open" it from the Finder, and then fails to notice the menu bar change. The intention of the Re-open Application event in such circumstances is to cause the application to open a window, providing more obvious visible evidence to the user that the application is, in fact, open.

• If your application is not open and the user elects to open one of your application's documents from the Finder, the Finder calls the Process Manager to launch your application and then sends your application an Open Documents event.

• On Mac OS 8/9, if your application is not open and the user elects to print one of your application's documents from the Finder, the Finder calls the Process Manager to launch your application and then sends your application a Print Documents event. Your application should print the selected documents and remain open until it receives a Quit Application event from the Finder.

• If your application is open and the user elects to open or (on Mac OS 8/9 only) print any of your application's documents from the Finder, the Finder sends your application the Open Documents or (on Mac OS 8/9 only) Print Documents event.

• If your application is open and the user chooses Restart or Shut Down, the Finder sends your application the Quit Application event.

The following is a summary of the contents of the required Apple events sent by the Finder and the actions they request applications to perform:

Your application needs to recognise two descriptor types to handle the required Apple events: descriptor lists and alias structures.

As previously stated, in the event of an Open Documents or (on Mac OS 8/9 only) Print Documents event, you can retrieve the data which specifies the document as an alias structure, or you can request that the Apple Event Manager coerce the alias structure to a file system specification structure. The file system specification provides a standard method of identifying files.

Main Apple Event Manager and Appearance Manager Constants, Data Types, and Functions Relevant to Required Apple Events and Appearance Manager Apple Events

Constants

High Level Event

kHighLevelEvent  = 23

Event Classes for Required Apple Event and Appearance Manager Apple Event

kCoreEventClass        = FOUR_CHAR_CODE('aevt')  // Event class - required Apple events.
KAppearanceEventClass  = FOUR_CHAR_CODE('appr')  // Event Class - Appearance Manager Apple
                                                 // events.

Event IDs for Required Apple Events

kAEOpenApplication    = FOUR_CHAR_CODE('oapp')  // Event ID for Open Application event.
kAEReopenApplication  = FOUR_CHAR_CODE('rapp')  // Event ID for Re-open Application Event.
kAEOpenDocuments      = FOUR_CHAR_CODE('odoc')  // Event ID for Open Documents event.
kAEPrintDocuments     = FOUR_CHAR_CODE('pdoc')  // Event ID for Print Documents event.
kAEQuitApplication    = FOUR_CHAR_CODE('quit')  // Event ID for Quit Application event.

Event IDs for Appearance Manager Apple Events

kAESystemFontChanged       = FOUR_CHAR_CODE('sysf')  // System font changed.
KAESmallSystemFontChanged  = FOUR_CHAR_CODE('ssfn')  // Small system font changed.
kAEViewsFontChanged        = FOUR_CHAR_CODE('vfnt')  // Views font changed.

Event ID for Show Preferences Apple Event (Mac OS X)

kAEShowPreferences        = FOUR_CHAR_CODE('pref')  Preferences menu item chosen

Keywords for Apple Event Attributes

keyMissedKeywordAttr  = FOUR_CHAR_CODE('miss')  // First required parameter remaining in
                                                // an Apple event.

Keywords for Apple Event Parameters

keyDirectObject       = FOUR_CHAR_CODE('----')  // Direct parameter

Apple Event Descriptor Types

typeAEList    = FOUR_CHAR_CODE('list') // List of descriptor structures.
typeWildCard  = FOUR_CHAR_CODE('****')  // Matches any type.
typeFSS       = FOUR_CHAR_CODE('fss ')  // File system specification.

Result Codes

errAEDescNotFound  = -1701   // Descriptor structure was not found.
errAEParamMissed   = -1715   // Handler cannot understand a parameter
                             // the client considers is required.

Theme Font ID Constants

KThemeSystemFont                 = 0
KThemeSmallSystemFont            = 1
KThemeSmallEmphasizedSystemFont  = 2
KThemeViewsFont                  = 3

Data Types

typedef FourCharCode  AEEventClass;  // Event class for a high level event.
typedef FourCharCode  AEEventID;     // Event ID for a high level event.
typedef FourCharCode  AEKeyword;     // Keyword for a descriptor structure.
typedef ResType       DescType;      // Descriptor type.
typedef AEDesc        AEDescList;    // List of descriptor structures.
typedef AEDescList    AERecord;      // List af keyword-specified descriptor structures.
typedef AERecord      AppleEvent;    // List of attributes and parameters for Apple event.

Descriptor Structure

struct AEDesc
{
   DescType      descriptorType;  // Type of data being passed.
   AEDataStorage dataHandle;      // Handle to data being passed.
};
typedef struct AEDesc AEDesc;

Keyword-Specified Descriptor Structure

struct AEKeyDesc  
{
   AEKeyword  deskKey;      // Keyword.
   AEDesc     descContent;  // Descriptor structure.
};
typedef struct AEKeyDesc AEKeyDesc;

Functions

Creating and Managing Apple Event Dispatch Tables

OSErr  AEInstallEventHandler(AEEventClass theAEEventClass,AEEventID theAEEventID,
       AEEventHandlerUPP handler,long handlerRefcon,Boolean isSysHandler);

Dispatching Apple Events

OSErr  AEProcessAppleEvent(const EventRecord *theEventRecord);

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

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

Counting the Items in Descriptor Lists

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

Getting Items From Descriptor Lists

OSErr  AEGetNthPtr(const AEDescList *theAEDescList,long index,DescType desiredType,
       AEKeyword *theAEKeyword,DescType *typeCode,Ptr dataPtr,Size maximumSize,
       Size *actualSize);

Deallocating Memory for Descriptor Structures

OSErr  AEDisposeDesc(AEDesc *theAEDesc);