Apple Event Constants

The Apple Event Manager uses four-character codes (also referred to as Apple event codes) to identify the data within an Apple event. A four-character code is just four bytes of data that can be expressed as a string of four characters in the Mac OS Roman encoding. For example, 'capp' is the four-character code that specifies an application.

The Apple Event Manager defines four-character-code constants for many common commands (or verbs) and data objects (or nouns) that can be used in Apple events. These constants are defined primarily in the header files AppleEvents.h and AERegistry.h in the AE framework. They are documented in Apple Event Manager Reference. A subset of these constants is described in Selected Apple Event Constants in this document.

Listing 2-1 shows some constants from AERegistry.h. Each constant definition includes a comment showing the actual numeric value as a hex number.

Listing 2-1  Some four-character codes from AERegistry.h

enum {

  cApplication                  = 'capp', /*  0x63617070  */

  cArc                          = 'carc', /*  0x63617263  */

  cBoolean                      = 'bool', /*  0x626f6f6c  */

  cCell                         = 'ccel', /*  0x6363656c  */

  cChar                         = 'cha ', /*  0x63686120  */

  cDocument                     = 'docu', /*  0x646f6375  */

  cGraphicLine                  = 'glin', /*  0x676c696e  */

...

};

For the Apple event support in your application, you should use existing constants wherever they make sense, rather than defining new constants. For example, if your application supports an Apple event to get the name of a document, you can use the constant cDocument to denote a document.

Apple reserves all values that consist entirely of lowercase letters and spaces. You can generally avoid conflicts with Apple-defined constants by including at least one uppercase letter when defining a four-character code.

Event Class and Event ID

An Apple event is uniquely identified by its event class and event ID attributes, each of which is an arbitrary four-character code (described in Apple Event Constants). The Apple Event Manager uses these values in dispatching Apple events to code in your application (described in Apple Event Dispatching).

Apple defines event class and event ID values for standard Apple events, including those that it sends. For example, a delete Apple event has an event class value of 'core' (represented by the constant kAECoreSuite) and an event ID value of 'delo' (kAEDelete). For examples and descriptions of Apple-defined event class and event ID values, see Event Class Constants, Event ID Constants for Apple Events Sent by the Mac OS, and Event ID Constants for Standard AppleScript Commands.

You define the event class and event ID values for application-specific Apple events your application supports. While these values are arbitrary, you should follow the simple guidelines described in Apple Event Constants in choosing values.

You can use a common event class for multiple Apple events as a way to group related events that your application supports. For example, many Apple-defined Apple events share a common event class. This can be useful in organizing the name space for your Apple events and may simplify your coding, but it doesn’t result in any special treatment by the Apple Event Manager.

If you want other applications to be able to send Apple events to your application, you must publish event class and event ID values for those events. You should also describe the contents your application expects to find in each type of Apple event.

Similarly, if you want to send Apple events to other applications, you are dependent on those applications to provide the event class, event ID, and any other information you need to construct an Apple event the application can understand. One exception is that most applications, including yours, should be able to handle the Apple events described in Common Apple Events Sent by the Mac OS. So, for example, you might construct a quit Apple event that targets almost any Mac OS X application, and expect the application to handle it.

Descriptors, Descriptor Lists, and Apple Events

Descriptors and descriptor lists are the basic structural elements used in Apple events. A descriptor stores data and an accompanying descriptor type to form the basic building block of all Apple Events. The descriptor type is a four-character code that identifies the type of data associated with the descriptor. Table B-4 lists constants for some of the main descriptor types—for a complete list, see Apple Event Manager Reference. Figure 2-1 shows the format of a descriptor.

The data field of a descriptor is opaque—you should not attempt to access it directly. Table A-1 lists functions provided by the Apple Event Manager for accessing the data in a descriptor (and related data types).

Figure 2-2 shows a descriptor with a descriptor type of typeUTF8Text, which specifies that the descriptor’s data is text in UTF-8 encoding—in this case, the text is “Summary of Sales”.

A keyword is a four-character code used by the Apple Event Manager to identify a specific descriptor within an Apple event. A keyword-specified descriptor combines a keyword with a descriptor. This is the basic type used to specify attributes and parameters, which are described in detail in Apple Event Attributes and Parameters. Figure 2-3 shows the format of a keyword-specified descriptor.

An address descriptor is a descriptor that specifies a target address for an Apple event—that is, it specifies the application or other process to send the event to. The descriptor type can be specified by one of the constants shown in Table B-5.

A descriptor list is a descriptor whose data consists of a list of zero or more descriptors (it can be an empty list). A descriptor list can contain other lists, which allows for the construction of complex descriptors, and hence complex Apple events. Figure 2-4 shows the format of a descriptor list.

An Apple event record is a descriptor list whose data is a set of keyword-specified descriptors that describe Apple event parameters.

An Apple event is an Apple event record whose contents are conceptually divided into two parts, one for attributes and one for parameters, as shown in Figure 2-6.

Figure 2-5 shows the inheritance for descriptors and related data structures, with the corresponding data types shown in parentheses.

An Apple Event Manager function that operates on one of these data structures can also operate on any type that inherits from it. For example, Apple events inherit from Apple event records, which inherit from descriptor lists. As a result, you can pass an Apple event to any Apple Event Manager function that expects an Apple event record or a descriptor list. Similarly, you can pass Apple events and Apple event records, as well as descriptor lists and descriptors, to any Apple Event Manager function that expects a descriptor. See Table A-1 for a list of functions for working with the various data types.

Apple Event Attributes and Parameters

Every Apple event consists of attributes and, often, parameters, as shown in Figure 2-6. Taken together, the attributes of an Apple event denote the task to be performed, while the parameters provide additional information to be used in performing the task.

You use Apple Event Manager functions to create an Apple event, to add attributes or parameters to an Apple event, and to extract and examine the attributes or parameters from an Apple event.

Apple Event Parameters

An Apple event parameter is a keyword-specified descriptor that contains additional data for the command. Keywords for common Apple event parameters are shown in Table B-7.

As with attributes, there are various kinds of Apple event parameters. A direct parameter usually specifies the data to be acted upon by the target application. For example, Figure 2-7 shows the main Apple event attributes and the direct parameter for an open documents event that targets the AppleWorks application. The direct parameter specifies a descriptor list containing file aliases to the documents to open. An Apple event has at most one direct parameter.

Apple event parameters can contain standard data types, such as text strings, integers of various lengths, Boolean values, and others, listed in Table B-4.

An Apple event can include other parameters, in addition to the direct parameter. For example, an Apple event that represents an arithmetic operation might contain a direct parameter that specifies a pair of values to operate on, as well as an additional parameter that specifies the operator. A reply Apple event may contain an error number parameter and an error string parameter, added by your application when an error occurs, as described in Returning Error Information.

Creating an Apple Event in One Step

You can call the AEBuildAppleEventfunction to create an Apple event in one step. To do so, you pass event class, event ID, and other information that is used to create the Apple event’s attributes. The AEBuildAppleEvent function includes parameters for specifying the target address—you don’t have to separately create an address descriptor. You may need to prepare data you’ll pass to AEBuildAppleEvent—for example, you may need to create aliases to files you will insert into the Apple event as a descriptor list.

In addition, you provide a specially formatted string, similar to the string you might pass to a printf function, along with parameters that specify the data that corresponds to items in the format string. As a result, AEBuildAppleEvent can also create the parameters for your Apple event, resulting in a full-fledged Apple event.

The Apple Event Manager also provides the AEBuildDesc function as a one-step mechanism for adding potentially complex descriptors to an existing Apple event, and the AEBuildParameters function for adding parameters or attributes.

The one-step functions are most useful in situations where your application knows in advance all the information needed to create an Apple event or other data structure. They also make it easier to do parameterized substitution of values. For an example of this approach, see Creating an Apple Event With AEBuildAppleEvent.

Creating an Apple Event Sequentially

You can create the basic structure for an Apple event by calling the AECreateAppleEvent function. You pass information specifying event class, event ID, target address, return ID, and transaction ID; the function creates an Apple event containing the corresponding attributes. However, before you can call AECreateAppleEvent, you have to create a target address descriptor to pass to it, using a function such as AECreateDesc.

After calling AECreateAppleEvent, the resulting Apple event contains attributes for the event but no parameters. To add parameters to the event, you can use the AEBuildDesc and AEBuildParameters functions described in the previous section, or you can continue to work sequentially. For example, if the direct object of the event you are creating is a list of file aliases, you could create it sequentially by performing the following steps:

1. Call AECreateDesc once for each file alias to create a descriptor for it.

2. Call AECreateList to create a descriptor list.

3. Call AEPutDesc once for each descriptor to add it to the descriptor list.

4. Call AEPutParamDesc to add the descriptor list to the Apple event as a parameter.

This sequential approach is most useful for creating simple Apple events, or in situations where your application must factor the creation of an Apple event across several layers of code—for example, where you create an event, then pass it to various subsystems to add data to it.

For an example of how to create an Apple event step by step, see Creating an Apple Event With AECreateAppleEvent.

The Completed Apple Event

Figure 2-8 shows the main data structures of a complete Apple event, containing a list of keyword-specified descriptors that specify the attributes and parameters of an open documents Apple event. Although this is an event sent to your application by the Mac OS, events you create have a similar structure.

The figure includes attributes for the event class, event ID, and target address. It also shows the direct parameter—a keyword-specified descriptor with the keyword keyDirectObject. The entire figure corresponds to the open documents event shown in Figure 2-7.