Apple Events

Communicate messages across process boundaries that can be performed and responded to with a reply event.

Overview

When a script that targets an application is executed, commands are sent to the application in the form of Apple events, a kind of interprocess message. Cocoa scripting helps you create scriptable applications by doing much of the work of receiving these Apple events, extracting information from them, and invoking methods in your scriptable classes.

Topics

Structures

AEBuildAppleEvent

Constructs an entire Apple event in a single call.

AEBuildDesc

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

AEBuildParameters

Adds additional parameters or attributes to an existing Apple event.

AECallObjectAccessor

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

AECheckIsRecord

Determines whether a descriptor is truly an AERecord.

AECoerceDesc

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

AECoercePtr

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

AECountItems

Counts the number of descriptors in a descriptor list.

AECreateAppleEvent

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

AECreateDesc

Creates a new descriptor that incorporates the specified data.

AECreateDescFromExternalPtr

Creates a new descriptor that uses a memory buffer supplied by the caller.

AECreateList

Creates an empty descriptor list or Apple event record.

AECreateRemoteProcessResolver

Creates an object for resolving a list of remote processes.

AEDecodeMessage

Decodes a Mach message and converts it into an Apple event and its related reply.

AEDeleteItem

Deletes a descriptor from a descriptor list, causing all subsequent descriptors to move up one place.

AEDeleteParam

Deletes a keyword-specified parameter from an Apple event record.

AEDisposeDesc

Deallocates the memory used by a descriptor.

AEDisposeRemoteProcessResolver

Disposes of an AERemoteProcessResolverRef.

AEDisposeToken

Deallocates the memory used by a token.

AEDuplicateDesc

Creates a copy of a descriptor.

AEFlattenDesc

Flattens the specified descriptor and stores the data in the supplied buffer.

AEGetArray

Extracts data from an Apple event array created with the AEPutArray function and stores it as a standard array of fixed size items in the specified buffer.

AEGetAttributeDesc

Gets a copy of the descriptor for a specified Apple event attribute from an Apple event; typically used when your application needs to pass the descriptor on to another function.

AEGetAttributePtr

Gets a copy of the data for a specified Apple event attribute from an Apple event; typically used when your application needs to work with the data directly.

AEGetCoercionHandler

Gets the coercion handler for a specified descriptor type.

AEGetDescData

Gets the data from the specified descriptor.

AEGetDescDataRange

Retrieves a specified series of bytes from the specified descriptor.

AEGetDescDataSize

Gets the size, in bytes, of the data in the specified descriptor.

AEGetEventHandler

Gets an event handler from an Apple event dispatch table.

AEGetNthDesc

Copies a descriptor from a specified position in a descriptor list into a specified descriptor; typically used when your application needs to pass the extracted data to another function as a descriptor.

AEGetNthPtr

Gets a copy of the data from a descriptor at a specified position in a descriptor list; typically used when your application needs to work with the extracted data directly.

AEGetObjectAccessor

Gets an object accessor function from an object accessor dispatch table.

AEGetParamDesc

Gets a copy of the descriptor for a keyword-specified Apple event parameter from an Apple event or an Apple event record.

AEGetParamPtr

Gets a copy of the data for a specified Apple event parameter from an Apple event or an Apple event record.

AEGetRegisteredMachPort

Returns the Mach port (in the form of a mach_port_t) that was registered with the bootstrap server for this process.

AEGetSpecialHandler

Gets a specified handler from a special handler dispatch table.

AEInitializeDesc

Initializes a new descriptor.

AEInstallCoercionHandler

Installs a coercion handler in either the application or system coercion handler dispatch table.

AEInstallEventHandler

Adds an entry for an event handler to an Apple event dispatch table.

AEInstallObjectAccessor

Adds or replaces an entry for an object accessor function to an object accessor dispatch table.

AEInstallSpecialHandler

Installs a callback function in a special handler dispatch table.

AEManagerInfo

Provides information about the version of the Apple Event Manager currently available or the number of processes that are currently recording Apple events.

AEObjectInit

Initializes the Object Support Library.

AEPrintDescToHandle

Provides a pretty printer facility for displaying the contents of Apple event descriptors.

AEProcessMessage

Decodes and dispatches a low level Mach message event to an event handler, including packaging and returning the reply to the sender.

AEPutArray

Inserts the data for an Apple event array into a descriptor list, replacing any previous descriptors in the list.

AEPutAttributeDesc

Adds a descriptor and a keyword to an Apple event as an attribute.

AEPutAttributePtr

Adds a pointer to data, a descriptor type, and a keyword to an Apple event as an attribute.

AEPutDesc

Adds a descriptor to any descriptor list, possibly replacing an existing descriptor in the list.

AEPutParamDesc

Inserts a descriptor and a keyword into an Apple event or Apple event record as an Apple event parameter.

AEPutParamPtr

Inserts data, a descriptor type, and a keyword into an Apple event or Apple event record as an Apple event parameter.

AEPutPtr

Inserts data specified in a buffer into a descriptor list as a descriptor, possibly replacing an existing descriptor in the list.

AERemoteProcessResolverGetProcesses

Returns an array of objects containing information about processes running on a remote machine.

AERemoteProcessResolverScheduleWithRunLoop

Schedules a resolver for execution on a given run loop in a given mode.

AERemoveCoercionHandler

Removes a coercion handler from a coercion handler dispatch table.

AERemoveEventHandler

Removes an event handler entry from an Apple event dispatch table.

AERemoveObjectAccessor

Removes an object accessor function from an object accessor dispatch table.

AERemoveSpecialHandler

Removes a handler from a special handler dispatch table.

AEReplaceDescData

Copies the specified data into the specified descriptor, replacing any previous data.

AEResolve

Resolves an object specifier.

AESendMessage

Sends an AppleEvent to a target process without some of the overhead required by AESend.

AESetObjectCallbacks

Specifies the object callback functions for your application.

AESizeOfAttribute

Gets the size and descriptor type of an Apple event attribute from a descriptor of type AppleEvent.

AESizeOfFlattenedDesc

Returns the amount of buffer space needed to store the descriptor after flattening it.

AESizeOfNthItem

Gets the data size and descriptor type of the descriptor at a specified position in a descriptor list.

AESizeOfParam

Gets the size and descriptor type of an Apple event parameter from a descriptor of type AERecord or AppleEvent.

AEStreamClose

Closes and deallocates an AEStreamRef.

AEStreamCloseDesc

Marks the end of a descriptor in an AEStreamRef.

AEStreamCloseList

Marks the end of a list of descriptors in an AEStreamRef.

AEStreamCloseRecord

Marks the end of a record in an AEStreamRef.

AEStreamCreateEvent

Creates a new Apple event and opens a stream for writing data to it.

AEStreamOpen

Opens a new AEStreamRef for use in building a descriptor.

AEStreamOpenDesc

Marks the beginning of a descriptor in an AEStreamRef.

AEStreamOpenEvent

Opens a stream for an existing Apple event.

AEStreamOpenKeyDesc

Marks the beginning of a key descriptor in an AEStreamRef.

AEStreamOpenList

Marks the beginning of a descriptor list in an AEStreamRef.

AEStreamOpenRecord

Marks the beginning of an Apple event record in an AEStreamRef.

AEStreamOptionalParam

Designates a parameter in an Apple event as optional.

AEStreamSetRecordType

Sets the type of the most recently created record in an AEStreamRef.

AEStreamWriteAEDesc

Copies an existing descriptor into an AEStreamRef.

AEStreamWriteData

Appends data to the current descriptor in an AEStreamRef.

AEStreamWriteDesc

Appends the data for a complete descriptor to an AEStreamRef.

AEStreamWriteKey

Marks the beginning of a keyword/descriptor pair for a descriptor in an AEStreamRef.

AEStreamWriteKeyDesc

Writes a complete keyword/descriptor pair to an AEStreamRef.

AEUnflattenDesc

Unflattens the data in the passed buffer and creates a descriptor from it.

AEArrayData

Stores array information to be put into a descriptor list with the AEPutArray function or extracted from a descriptor list with the AEGetArray function.

AEBuildError

Defines a structure for storing additional error code information for “AEBuild” routines.

AEDesc

Stores data and an accompanying descriptor type to form the basic building block of all Apple Events.

AEKeyDesc

Associates a keyword with a descriptor to form a keyword-specified descriptor.

AERemoteProcessResolverContext

Supplied as a parameter when performing asynchronous resolution of remote processes.

Constants

kAERemoteProcessNameKey

Use this key to obtain the visible name of the remote process, in the localization supplied by the server, as a CFStringRef.

kAERemoteProcessProcessIDKey

Use this key to obtain the process ID of the remote process, if available; if so, returned as a CFNumberRef.

kAERemoteProcessURLKey

Use this key to obtain the full URL to the remote process, as a CFURLRef.

kAERemoteProcessUserIDKey

Use this key to obtain the user ID of the remote process, if available; if so, returned as a CFNumberRef.

Data Types

OSLAccessorProcPtr

Your object accessor function either finds elements or properties of an Apple event object.

OSLAccessorUPP

Defines a data type for the universal procedure pointer for the OSLAccessorProcPtr callback function pointer.

OSLAdjustMarksProcPtr

Defines a pointer to an adjust marks callback function. Your adjust marks function unmarks objects previously marked by a call to your marking function.

OSLAdjustMarksUPP

Defines a data type for the universal procedure pointer for the OSLAdjustMarksProcPtr callback function pointer.

OSLCompareProcPtr

Defines a pointer to an object comparison callback function. Your object comparison function compares one Apple event object to another or to the data for a descriptor.

OSLCompareUPP

Defines a data type for the universal procedure pointer for the OSLCompareProcPtr callback function pointer.

OSLCountProcPtr

Defines a pointer to an object counting callback function. Your object counting function counts the number of Apple event objects of a specified class in a specified container object.

OSLCountUPP

Defines a data type for the universal procedure pointer for the OSLCountProcPtr callback function pointer.

OSLDisposeTokenProcPtr

Defines a pointer to a dispose token callback function. Your dispose token function, required only if you use a complex token format, disposes of the specified token.

OSLDisposeTokenUPP

Defines a data type for the universal procedure pointer for the OSLDisposeTokenProcPtr callback function pointer.

OSLGetErrDescProcPtr

Defines a pointer to an error descriptor callback function. Your error descriptor callback function supplies a pointer to an address where the Apple Event Manager can store the current descriptor if an error occurs during a call to the AEResolve function.

OSLGetErrDescUPP

Defines a data type for the universal procedure pointer for the OSLGetErrDescProcPtr callback function pointer.

OSLGetMarkTokenProcPtr

Defines a pointer to a mark token callback function. Your mark token function returns a mark token.

OSLGetMarkTokenUPP

Defines a data type for the universal procedure pointer for the OSLGetMarkTokenProcPtr callback function pointer.

OSLMarkProcPtr

Defines a pointer to an object marking callback function. Your object-marking function marks a specific Apple event object.

OSLMarkUPP

Defines a data type for the universal procedure pointer for the OSLMarkProcPtr callback function pointer.

AEAddressDesc

A descriptor that contains the address of an application. Typically used to describe the target application for an Apple event.

AEArrayDataPointer

A pointer to a union of type AEArrayData.

AEArrayType

Stores a value that specifies an array type.

AEBuildErrorCode

Represents syntax errors found by an “AEBuild” routine.

AECoerceDescProcPtr

Defines a pointer to a function that coerces data stored in a descriptor. Your descriptor coercion callback function coerces the data from the passed descriptor to the specified type, returning the coerced data in a second descriptor.

AECoerceDescUPP

Defines a data type for the universal procedure pointer for the AECoerceDescProcPtr callback function pointer.

AECoercePtrProcPtr

Defines a pointer to a function that coerces data stored in a buffer. Your pointer coercion callback routine coerces the data from the passed buffer to the specified type, returning the coerced data in a descriptor.

AECoercePtrUPP

Defines a data type for the universal procedure pointer for the AECoercePtrProcPtr callback function pointer.

AECoercionHandlerUPP

Defines a data type for the universal procedure pointer for the AECoercionHandlerUPP callback function pointer.

AEDataStorage

A pointer to an opaque data type that provides storage for an AEDesc descriptor.

AEDataStorageType

An opaque data type used to store data in Apple event descriptors.

AEDescList

A descriptor whose data consists of a list of one or more descriptors.

AEDisposeExternalProcPtr

Defines a pointer to a function the Apple Event Manager calls to dispose of a descriptor created by the AECreateDescFromExternalPtr function. Your callback function disposes of the buffer you originally passed to that function.

AEDisposeExternalUPP

Defines a universal procedure pointer to a function the Apple Event Manager calls to dispose of a descriptor created by the AECreateDescFromExternalPtr function.

AEEventClass

Specifies the event class of an Apple event.

AEEventHandlerProcPtr

Defines a pointer to a function that handles one or more Apple events. Your Apple event handler function performs any action requested by the Apple event, adds parameters to the reply Apple event if appropriate (possibly including error information), and returns a result code.

AEEventHandlerUPP

Defines a data type for the universal procedure pointer for the AEEventHandlerUPP callback function pointer.

AEEventID

Specifies the event ID of an Apple event.

AEEventSource

A data type for values that specify how an Apple event was delivered.

AEKeyword

A four-character code that uniquely identifies a descriptor in an Apple event record or an Apple event.

AERecord

A descriptor whose data is a list of keyword-specified descriptors.

AERemoteProcessResolverCallback

Defines a pointer to a function the Apple Event Manager calls when the asynchronous execution of a remote process resolver completes, either due to success or failure, after a call to the AERemoteProcessResolverScheduleWithRunLoop function. Your callback function can use the reference passed to it to get the remote process information.

AERemoteProcessResolverRef

An opaque reference to an object that encapsulates the mechanism for obtaining a list of processes running on a remote machine.

AEReturnID

Specifies a return ID for a created Apple event.

AESendMode

Specify send preferences to the AESend function.

AESendPriority

Specifies the processing priority for a sent Apple event.

AEStreamRef

An opaque data structure for storing stream-based descriptor data.

AETransactionID

Specifies a transaction ID.

Enumerations

kAEUseHTTPProxyAttr

Web Services Proxy support—these constants should be added as attributes of the event that is being sent (not as part of the direct object).

Apple Event Recording Event ID Constants

Specify event IDs for events that deal with Apple event recording.

Callback Constants for the AEResolve Function

Specify supported callback features to the AEResolve function.

Constants for Object Specifiers, Positions, and Logical and Comparison Operations

Specify the types of the four keyword-specified descriptors that make up the data in an object specifier, as well as constants for position, logical operations, and comparison operations.

Data Array Constants

Specify an array type for storing or extracting descriptor lists with the AEPutArray and AEGetArray functions.

Descriptor Type Constants

Specify types for descriptors.

Event Class Constants

Specify the event class for an Apple event.

Event ID Constants

Specify the event ID for an Apple event.

Event Source Constants

Identify how an Apple event was delivered.

ID Constants for the AECreateAppleEvent Function

Specify values for the ID parameters of the AECreateAppleEvent function.

Key Form and Descriptor Type Object Specifier Constants

Specify possible values for the keyAEKeyForm field of an object specifier, as well as descriptor types used in resolving object specifiers.

Keyword Attribute Constants

Specify keyword values for Apple event attributes.

Keyword Parameter Constants

Specify keyword values for Apple event parameters, as well as information for the AEManagerInfo function to retrieve. Some common key word values are shown here.

Launch Apple Event Constants

In a kAEOpenApplication event, specify information about how the receiving application was launched.

Numeric Descriptor Type Constants

Specify types for numeric descriptors.

Object Class ID Constants

Specify the object class for an Apple event object.

Other Descriptor Type Constants

Specify types for Boolean and character descriptors.

Priority Constants for the AESend Function (Deprecated in macOS)

Specify a value for the sendPriority parameter of the AESend function.

Special Handler Callback Constants

Specify an object callback function to install, get, or remove from the special handler dispatch table.

Timeout Constants

Specify a timeout value.

See Also