Next Page >

Hide TOC

Apple Event Manager Reference

Framework	CoreServices/CoreServices.h, Carbon/Carbon.h
Declared in	AEDataModel.h AEHelpers.h AEInteraction.h AEMach.h AEObjects.h AEPackObject.h AERegistry.h AEUserTermTypes.h AppleEvents.h

Overview

The Apple Event Manager, a part of the Open Scripting Architecture (OSA), provides facilities for applications to send and respond to Apple events and to make their operations and data available to AppleScript scripts. For related API reference, see Open Scripting Architecture Reference.

An Apple event is a type of interprocess message that can specify complex operations and data. Apple events provide a data transport and event dispatching mechanism that can be used within a single application, between applications on the same computer, and between applications on different computers connected to a network.

Applications typically use Apple events to request services and information from other applications or to provide services and information in response to such requests. All applications that present a graphical interface to the user through the Human Interface Toolbox (Carbon applications) or the Cocoa application framework should be able to respond, if appropriate, to certain events sent by the Mac OS. These include the open application (or launch), reopen, open documents, print documents, and quit events.

Some Apple Event Manager functions are marked as being thread safe—for all other functions, you should call them only on the main thread.

For an overview of technologies that take advantage of the Apple Event Manager, see AppleScript Overview.

For information on working with Apple events, including events sent by the Mac OS, see “Responding to Apple Events” in Apple Events Programming Guide. For information about individual four-character codes used in Apple events, see AppleScript Terminology and Apple Event Codes Reference.

The Apple Event Manager is implemented by the AE framework, a subframework of the Core Services framework. You don’t link directly with the AE framework—instead, you typically link with the Carbon framework, which includes it. Some AppleEvent definitions are only available to clients of the Carbon framework, which includes, for example, AEInteraction.h in the HIToolbox framework.

The AE framework does not force a connection to the window server. This allows daemons and startup items that work with Apple events to continue working across log outs.

Functions by Task

Adding Items to Descriptor Lists

Adding Parameters and Attributes to Apple Events and Apple Event Records

Coercing Descriptor Types

Counting the Items in Descriptor Lists

Creating an Apple Event

Creating and Duplicating Descriptors

Creating, Calling, and Deleting Universal Procedure Pointers

Creating Descriptor Lists and Apple Event Records

Creating Object Specifiers

Deallocating Memory for Descriptors

Deallocating Memory for Tokens

Deleting Descriptors

Dispatching Apple Events

Getting, Calling, and Removing Object Accessor Functions

Getting Data or Descriptors From Apple Events and Apple Event Records

Getting Information About the Apple Event Manager

Getting Items From Descriptor Lists

Getting the Sizes and Descriptor Types of Descriptors

Initializing the Object Support Library

Locating Processes on Remote Computers

Available starting in Mac OS X version v10.3, these functions allow you to locate processes on remote computers (a task supported by the PPCToolbox in Mac OS 9).

Managing Apple Event Dispatch Tables

Managing Coercion Handler Dispatch Tables

Managing Special Handler Dispatch Tables

Operating On Descriptor Data

Requesting More Time to Respond to Apple Events

Requesting User Interaction

Resolving Object Specifiers

Sending an Apple Event

Creating Apple Event Structures in Memory

Creating Apple Event Structures Using Streams

Working With Lower Level Apple Event Functions

Serializing Apple Event Data

Suspending and Resuming Apple Event Handling

Miscellaneous

Functions

AEBuildAppleEvent

Constructs an entire Apple event in a single call.

OSStatus AEBuildAppleEvent (
   AEEventClass theClass,
   AEEventID theID,
   DescType addressType,
   const void *addressData,
   Size addressLength,
   SInt16 returnID,
   SInt32 transactionID,
   AppleEvent *result,
   AEBuildError *error,
   const char *paramsFmt,
   ...
);

Parameters

theClass: The event class for the resulting Apple event. See AEEventClass.
theID: The event id for the resulting Apple event. See AEEventID.
addressType: The address type for the addressing information described in the next two parameters: usually one of typeApplSignature, typeProcessSerialNumber, or typeKernelProcessID. See DescType.
addressData: A pointer to the address information.
addressLength: The number of bytes pointed to by the addressData parameter.
returnID: The return ID for the created Apple event. If you pass a value of kAutoGenerateReturnID, the Apple Event Manager assigns the created Apple event a return ID that is unique to the current session. If you pass any other value, the Apple Event Manager assigns that value for the ID.
transactionID: The transaction ID for this Apple event. A transaction is a sequence of Apple events that are sent back and forth between the client and server applications, beginning with the client’s initial request for a service. All Apple events that are part of a transaction must have the same transaction ID. You can specify the kAnyTransactionID constant if the Apple event is not one of a series of interdependent Apple events.
result: A pointer to a descriptor where the resulting descriptor should be stored. See AppleEvent for a description of the data type.
error: A pointer to an AEBuildError structure where additional information about any errors that occur will be saved. This is an optional parameter and you can pass NULL if this information is not required. See AEBuildError for a description of the data type.
paramsFmt: An AEBuild format string describing the AppleEvent record to be created. The format of these strings is described in Technical Note TN2106, AEBuild*, AEPrint*, and Friends. That technote also describes possible error return codes for syntax errors in the format string.

Return Value

A numeric result code indicating the success of the call. A value of AEBuildSyntaxNoErr (zero) means the call succeeded. You can use the error parameter to discover information about other errors. See “Apple Event Manager Result Codes.”

Discussion

IMPORTANT: Following the parameters described above, the AEBuildAppleEvent function takes a variable number of parameters as specified by the format string provided in the paramsFmt parameter.

This function and related “AEBuild” routines (including AEBuildDesc and AEBuildParameters, and the variable-argument versions, vAEBuildAppleEvent, vAEBuildDesc, and vAEBuildParameters) provide a very simple translation service for converting specially formatted strings into complex Apple event descriptors. Normally, creating complex Apple event descriptors requires a large number of calls to Apple event Manager routines to build up the descriptor piece by piece. The AEBuildAppleEvent function and related routines allow you to consolidate all of the calls required to construct a complex Apple event descriptor into a single system call that creates the desired structure as directed by a format string that you provide.

In many ways, the AEBuild routines are very much like the standard C library's printf suite of routines. The syntax for the format string that you provide is very simple and allows for the substitution of data items into the Apple event descriptors being created.

The AEBuildAppleEvent function is similar to AECreateAppleEvent, but in addition to creating the Apple event, it also constructs the parameters for the event from the last three arguments. You can use AEBuildAppleEvent to build an entire Apple event, or AEBuildParameters to add additional parameters to an existing Apple event.

The syntax of the formatting string for an entire Apple event (as passed to AEBuildAppleEvent) is almost identical to that used to represent the contents of an Apple event, without the curly braces. The event is defined as a sequence of name-value pairs, with optional parameters preceded with a tilde (~) character. The syntax is described in Technical Note TN2106, AEBuild*, AEPrint*, and Friends.

It is important to note that the identifier for the direct parameter in an Apple event, specified by the constant keyDirectObject, is four minus signs ('----'). The minus sign has special meaning in AEBuild strings, and it should always be enclosed in single quotes when it is used to identify the direct parameter for an Apple event in a descriptor string.

Version Notes

Prior to Mac OS X version 10.3, AEBuildAppleEvent would fail if you supplied a data parameter with size greater than 32767 bytes.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEBuildDesc

Provides a facility for compiling AEBuild descriptor strings into Apple event descriptors (AEDesc).

OSStatus AEBuildDesc (
   AEDesc *dst,
   AEBuildError *error,
   const char *src,
   ...
);

Parameters

dst: A pointer to a descriptor where the resulting descriptor should be stored. See AEDesc.
error: A pointer to an AEBuildError structure where additional information about any errors that occur will be saved. This is an optional parameter and you can pass NULL if this information is not required. See AEBuildError.
src: An AEBuild format string describing the descriptor to be created.

Return Value

Discussion

This function and related “AEBuild” routines provide a very simple translation service for converting specially formatted strings into complex Apple event descriptors. Normally, creating complex Apple event descriptors requires a large number of calls to Apple event Manager routines to build up the descriptor piece by piece. The AEBuildDesc function and related routines allow you to consolidate all of the calls required to construct a complex Apple event descriptor into a single system call that creates the desired structure as directed by a format string that you provide.

For additional information on using the AEBuild routines, see the descriptions for AEBuildAppleEvent and AEBuildParameters.

Version Notes

Prior to Mac OS X version 10.3, AEBuildDesc would fail if you supplied a data parameter with size greater than 32767 bytes.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEBuildParameters

Adds additional parameters or attributes to an existing Apple event.

OSStatus AEBuildParameters (
   AppleEvent *event,
   AEBuildError *error,
   const char *format,
   ...
);

Parameters

event: The Apple event to which you are adding parameters. See AppleEvent.
error: A pointer to an AEBuildError structure where additional information about any errors that occur will be saved. This is an optional parameter and you can pass NULL if this information is not required. See AEBuildError.
format: An AEBuild format string describing the parameters to be created.

Return Value

A result code. See “Apple Event Manager Result Codes.”

Discussion

This function can be called more than once to add any desired number of parameters or attributes to an existing Apple event. The Apple event should already have been created through either a call to AECreateAppleEvent or AEBuildAppleEvent.

For additional information on using the AEBuild routines, see the descriptions for AEBuildAppleEvent and AEBuildDesc.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AECallObjectAccessor

Invokes the appropriate object accessor function for a specific desired type and container type.

OSErr AECallObjectAccessor (
   DescType desiredClass,
   const AEDesc *containerToken,
   DescType containerClass,
   DescType keyForm,
   const AEDesc *keyData,
   AEDesc *token
);

Parameters

desiredClass: The type of the Apple event object requested. Some possible values are defined in “Object Class ID Constants.” See DescType.
containerToken: A pointer to the token that identifies the container for the desired object. (Token is defined in AEDisposeToken.) See AEDesc.
containerClass: The object class of the container for the desired objects. See DescType.
keyForm: The key form that specifies how to find the object within the container. Key form constants are described in “Key Form and Descriptor Type Object Specifier Constants.” See DescType.
keyData: A pointer to the key data that identifies the object within the container. The type of this data is form-specific. That is, formName typically has key data of type typeText. See AEDesc.
token: A pointer to a token. On return, a token specifying the desired object (or objects). Your application should dispose of this token when it is through with it by calling AEDisposeToken. See AEDesc.

Return Value

A result code. See “Apple Event Manager Result Codes.” AECallObjectAccessor returns any result codes returned by the object accessor function it calls.

Discussion

If you want your application to do some of the Apple event object resolution normally performed by the AEResolve function, you can use AECallObjectAccessor to invoke an object accessor function. This might be useful, for example, if you have installed an object accessor function using typeWildCard for the AEInstallObjectAccessor function’s desiredClass parameter and typeAEList for the containerType parameter. To return a list of tokens for a request like “line one of every window” the object accessor function can create an empty list, then call AECallObjectAccessor for each requested element, adding tokens for each element to the list one at a time.

The parameters of AECallObjectAccessor are identical to the parameters of an object accessor function, as described in OSLAccessorProcPtr with one exception—the Apple Event Manager adds a reference constant parameter each time it calls the object accessor function.

You can also call a specific object accessor function directly through its universal procedure pointer with one of the invoke functions described in “Creating, Calling, and Deleting Universal Procedure Pointers.”

Version Notes

In Mac OS X, your application can not make an object callback function available to other applications by installing it in a system object accessor dispatch table.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

AECheckIsRecord

Determines whether a descriptor is truly an AERecord.

Boolean AECheckIsRecord (
   const AEDesc *theDesc
);

Parameters

theDesc: A pointer to the descriptor to check.

Return Value

Returns true if the descriptor is an AERecord or an AppleEvent, false otherwise.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AECoerceDesc

Coerces the data in a descriptor to another descriptor type and creates a descriptor containing the newly coerced data.

OSErr AECoerceDesc (
   const AEDesc *theAEDesc,
   DescType toType,
   AEDesc *result
);

Parameters

theAEDesc: A pointer to the descriptor containing the data to coerce. See AEDesc.
toType: The desired descriptor type of the resulting descriptor. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
result: A pointer to a descriptor. On successful return, a descriptor containing the coerced data and matching the descriptor type specified in toType. On error, a null descriptor. If the function returns successfully, your application should call the AEDisposeDesc function to dispose of the resulting descriptor after it has finished using it.

Return Value

A result code. See “Apple Event Manager Result Codes.” If AECoerceDesc returns a nonzero result code, it returns a null descriptor record (a descriptor record of type typeNull, which does not contain any data) unless the Apple Event Manager is not available because of limited memory.

Version Notes

See the Version Notes section for the AECoercePtr function for information on when to use descriptor-based versus pointer-based coercion handlers starting in Mac OS X version 10.2.

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AECoercePtr

Coerces data to a desired descriptor type and creates a descriptor containing the newly coerced data.

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

Parameters

typeCode: The descriptor type of the source data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
dataPtr: A pointer to the data to coerce.
dataSize: The length, in bytes, of the data to coerce.
toType: The desired descriptor type of the resulting descriptor. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”
result: A pointer to a descriptor. On successful return, a descriptor containing the coerced data and matching the descriptor type specified in toType. On error, a null descriptor. If the function returns successfully, your application should call the AEDisposeDesc function to dispose of the resulting descriptor after it has finished using it. See AEDesc.

Return Value

A result code. See “Apple Event Manager Result Codes.”

Version Notes

Starting in Mac OS X version 10.2, pointer-based coercion handlers are not called if the input type is “structured”—that is, if the type to be coerced is typeAEList, typeAERecord, or coerced typeAERecord. If you want to add a coercion handler for one of these types, it must be a descriptor-based handler. This does not mean you are required to use descriptor-based coercion handlers everywhere—for “flat” data types, such as typeText, pointer-based handlers are still fine.

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AECountItems

Counts the number of descriptors in a descriptor list.

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

Parameters

theAEDescList: A pointer to the descriptor list to count. See AEDescList.
theCount: A pointer to a count variable. On return, the number of descriptors in the specified descriptor list, which can be 0, if the list is empty.

Return Value

A result code. See “Apple Event Manager Result Codes.”

Discussion

Your application typically counts the descriptors in a descriptor list when it is extracting data from an Apple event. You can use the functions in “Getting Items From Descriptor Lists” to get an individual item from a descriptor list or to iterate through the items.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AECreateAppleEvent

Creates an Apple event with several important attributes but no parameters.

OSErr AECreateAppleEvent (
   AEEventClass theAEEventClass,
   AEEventID theAEEventID,
   const AEAddressDesc *target,
   AEReturnID returnID,
   AETransactionID transactionID,
   AppleEvent *result
);

Parameters

theAEEventClass: The event class of the Apple event to create. This parameter becomes accessible through the keyEventClassAttr attribute of the Apple event. Some event classes are described in “Event Class Constants.” See AEEventClass.
theAEEventID: The event ID of the Apple event to create. This parameter becomes accessible through the keyEventIDAttr attribute of the Apple event. Some event IDs are described in “Event ID Constants.” See AEEventID.
target: A pointer to an address descriptor. Before calling AECreateAppleEvent, you set the descriptor to identify the target (or server) application for the Apple event. This parameter becomes accessible through the keyAddressAttr attribute of the Apple event. See AEAddressDesc.
returnID: The return ID for the created Apple event. If you pass a value of kAutoGenerateReturnID, the Apple Event Manager assigns the created Apple event a return ID that is unique to the current session. If you pass any other value, the Apple Event Manager assigns that value for the ID. This parameter becomes accessible through the keyReturnIDAttr attribute of the Apple event. The return ID constant is described in “ID Constants for the AECreateAppleEvent Function.” See AEReturnID.
transactionID: The transaction ID for this Apple ev