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.

Related Sample Code

CarbonSketch

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.

Related Sample Code

QTCarbonShell

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 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. This parameter becomes accessible through the keyTransactionIDAttr attribute of the Apple event. This transaction ID constant is described in “ID Constants for the AECreateAppleEvent Function.” See AETransactionID.
result: A pointer to an Apple event. On successful return, the new Apple event. On error, a null descriptor (one with descriptor type typeNull). If the function returns successfully, your application should call the AEDisposeDesc function to dispose of the resulting Apple event after it has finished using it. See the AppleEvent data type.

Return Value

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

Discussion

The AECreateAppleEvent function creates an empty Apple event. You can add parameters to the Apple event after you create it with the functions described in “Adding Parameters and Attributes to Apple Events and Apple Event Records.”

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

AECreateDesc

Creates a new descriptor that incorporates the specified data.

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

Parameters

typeCode: The descriptor type for the new descriptor. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
dataPtr: A pointer to the data for the new descriptor. This data is copied into a newly-allocated block of memory for the descriptor that is created. To minimize copying overhead, consider using AECreateDescFromExternalPtr.
dataSize: The length, in bytes, of the data for the new descriptor.
result: A pointer to a descriptor. On successful return, a descriptor that incorporates the data specified by the dataPtr parameter. 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.”

Discussion

While it is possible to create an Apple event descriptor or a descriptor list or a descriptor with the AECreateDesc function (assuming you have access to the raw data for an Apple event, list, or descriptor), you typically create these structured objects with their specific creation routines—AECreateAppleEvent, AECreateList, or AECreateDesc.

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

AECreateDescFromExternalPtr

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

OSStatus AECreateDescFromExternalPtr (
   OSType descriptorType,
   const void *dataPtr,
   Size dataLength,
   AEDisposeExternalUPP disposeCallback,
   SRefCon disposeRefcon,
   AEDesc *theDesc
);

Parameters

descriptorType

The descriptor type for the new descriptor.

dataPtr

A pointer to the data for the new descriptor. The memory that is pointed to cannot be a Handle (which may move in memory), cannot be modified by the caller, and must be preserved in place (and not freed), until the disposeCallback function is called.

If possible, the descriptor will be mapped into the address space of the recipient using shared memory, avoiding an actual memory copy.

The pointer that is passed in does not need to be aligned to any particular boundary, but is optimized to transfer data on a page boundary. You can get the current page size (4096 on all current Mac OS X systems) with the getpagesize(3) call. (Type man 3 getpagesize in a Terminal window for documentation.)

dataLength

The length, in bytes, of the data for the new descriptor.

disposeCallback

A universal procedure pointer to a dispose callback function of type AEDisposeExternalProcPtr. Your callback function will be called when the block of memory provided by dataPtr is no longer needed by the Apple Event Manager. The function can be called at any time, including during creation of the descriptor.

disposeRefcon

A reference constant the Apple Event Manager passes to the disposeCallback function whenever it calls the function. If your dispose function doesn’t require a reference constant, pass 0 for this parameter.

theDesc

A pointer to a descriptor. On successful return, a descriptor that incorporates the data specified by the dataPtr parameter. 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.”

Discussion

This function is different than AECreateDesc, in that it creates a descriptor that uses the data block provided by the caller “in place,” rather than allocate a block of memory and copy the data to it. This function can provide dramatically improved performance if you’re working with large chunks of data. It attempts to copy the descriptor to the address space of any recipient process using virtual memory APIs, avoiding an actual memory copy. For example, you might want to use this function to pass a large image in an Apple event.

You can use the AEGetDescDataRange function to access a specific section of a large block of data.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AEDataModel.h

AECreateList

Creates an empty descriptor list or Apple event record.

OSErr AECreateList (
   const void *factoringPtr,
   Size factoredSize,
   Boolean isRecord,
   AEDescList *resultList
);

Parameters

factoringPtr: A pointer to the data at the beginning of each descriptor that is the same for all descriptors in the list. If there is no common data, or if you decide not to isolate the common data, pass NULL as the value of this parameter.
factoredSize: The size of the common data. If there is no common data, or if you decide not to isolate the common data, pass 0 as the value of this parameter. (See the Discussion section for more information.)
isRecord: A Boolean value that specifies the kind of list to create. Pass a value of TRUE to create an Apple event record (a data structure of type AERecord) or FALSE to create a descriptor list.
resultList: A pointer to a descriptor list variable. On successful return, the descriptor list or Apple event record that the AECreateList function creates. On error, a null descriptor. See AEDescList.

Return Value

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

Discussion

The AECreateList function creates an empty descriptor list or Apple event record. You can use the functions described in “Adding Items to Descriptor Lists” to populate the list as part of creating an Apple event. After sending the Apple event with the AESend function, you should dispose of the descriptor list with the AEDisposeDesc function when you no longer need it.

If you intend to use a descriptor list for a factored Apple event array, you must provide, in the factoringPtr parameter, a pointer to the data shared by all items in the array and, in the factoredSize parameter, the size of the common data. The common data must be 4, 8, or more than 8 bytes in length because it always consists of (a) the descriptor type (4 bytes) (b) the descriptor type (4 bytes) and the size of each item’s data (4 bytes) or (c) the descriptor type (4 bytes), the size of each item’s data (4 bytes), and some portion of the data itself (1 or more bytes).

For information about data types used with Apple event arrays, see “Apple Event Manager Data Types.”

Version Notes

The factoringPtr and factoredSize parameters are not supported in Mac OS X v10.2 and later. You should pass NULL and zero, respectively, for these parameters.

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AECreateRemoteProcessResolver

Creates an object for resolving a list of remote processes.

AERemoteProcessResolverRef AECreateRemoteProcessResolver (
   CFAllocatorRef allocator,
   CFURLRef url
);

Parameters

allocator: An object that is used to allocates and deallocate any Core Foundation types created or returned by this API. You can pass kCFAllocatorDefault to get the default allocation behavior. The allocator is based on CFAllocatorRef, an opaque data type described in the Core Foundation Reference Documentation.
url: A CFURL reference identifying the remote host and port on which to look for processes. See the Core Foundation Reference Documentation for a description of the CFURLRef data type.

Return Value

An AERemoteProcessResolverRef, which must be disposed of with AEDisposeRemoteProcessResolver. A resolver can only be used one time; once it has obtained a list of remote processes from a server, or gotten an error, it can no longer be scheduled. To retrieve a new list of processes, create a new instance of this object.

Discussion

You supply this function with the URL for a remote host and port; it returns a reference to a resolver object. To obtain a list of remote processes from the resolver, you can query it synchronously with AERemoteProcessResolverGetProcesses, which blocks until the request completes (either successfully or with an error).

If asynchronous behavior is desired, you can optionally use AERemoteProcessResolverScheduleWithRunLoop to schedule the resolver asynchronously on a run loop. If so, you supply a callback routine (see AERemoteProcessResolverCallback) that is executed when the resolver completes. To obtain information about the remote processes, you will again have to call AERemoteProcessResolverGetProcesses.

A resolver can only be used once; once it has fetched the data or gotten an error it can no longer be scheduled. The data obtained by the resolver is a CFArrayRef of CFDictionaryRef objects. For information on the format of the returned remote process information, see the description of the function result for the function AERemoteProcessResolverGetProcesses, and also “Remote Process Dictionary Keys.”

Version Notes

Thread safe starting in Mac OS X v10.3.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AppleEvents.h

AEDecodeMessage

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

OSStatus AEDecodeMessage (
   mach_msg_header_t *header,
   AppleEvent *event,
   AppleEvent *reply
);

Parameters

header

A pointer to a Mach message header for the event to be decoded.

event

A pointer to a null Apple event descriptor (one with descriptor type typeNull). On successful completion, contains the decoded Apple event. If the function returns successfully, your application should call the AEDisposeDesc function to dispose of the resulting descriptor after it has finished using it.

reply

A pointer to a null Apple event descriptor. On successful completion, contains the reply event from the decoded Apple event. To send the reply, you use the following:

AESendMessage(reply, NULL, kAENoReply, kAEDefaultTimeout);

Return Value

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

Discussion

The Apple Event Manager provides the following functions (on Mac OS X only) for working with Apple events at a lower level: AEGetRegisteredMachPort, AEDecodeMessage, AESendMessage, and AEProcessMessage. See the descriptions for those functions for more information on when you might use them.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEMach.h

AEDeleteItem

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

OSErr AEDeleteItem (
   AEDescList *theAEDescList,
   long index
);

Parameters

theAEDescList: A pointer to the descriptor list containing the descriptor to delete. See AEDescList.
index: A one-based positive integer indicating the position of the descriptor to delete. AEDeleteItem returns an error if you pass zero, a negative number, or a value that is out of range.

Return Value

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

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

AEDeleteKeyDesc

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

OSErr AEDeleteKeyDesc (
   AERecord *theAERecord,
   AEKeyword theAEKeyword
);

Parameters

theAERecord: A pointer to the Apple event record to delete the parameter from.
theAEKeyword: The keyword that specifies the parameter to delete. Some keyword constants are described in “Keyword Parameter Constants.” See AEKeyword.

Return Value

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

Discussion

This function is declared as a macro that invokes AEDeleteParam, which can operate on an Apple event or an Apple event record. See the Discussion for that function for more information.

Version Notes

See AEDeleteParam.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AEDeleteParam

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

OSErr AEDeleteParam (
   AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword
);

Parameters

theAppleEvent: A pointer to the Apple event or Apple event record to delete the parameter from. See AppleEvent.
theAEKeyword: The keyword that specifies the parameter to delete. Some keyword constants are described in “Keyword Parameter Constants.” See AEKeyword.

Return Value

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

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

AEDisposeDesc

Deallocates the memory used by a descriptor.

OSErr AEDisposeDesc (
   AEDesc *theAEDesc
);

Parameters

theAEDesc: A pointer to the descriptor to deallocate. On return, a null descriptor. If you pass a null descriptor in this parameter, AEDisposeDesc returns noErr. See AEDesc.

Return Value

A result code. See “Apple Event Manager Result Codes.” As currently implemented, AEDisposeDesc always returns noErr.

Discussion

The AEDisposeDesc function deallocates the memory used by a descriptor. After calling this method, the descriptor becomes an empty descriptor with a type of typeNULL. Because all Apple event structures (except for keyword-specified descriptors) are descriptors, you can use AEDisposeDesc for any of them.

Do not call AEDisposeDesc on a descriptor obtained from another Apple Event Manager function (such as the reply event from a call to AESend) unless that function returns successfully.

Special Considerations

If the AEDesc might contain an OSL token, dispose of it with AEDisposeToken.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

AEDataModel.h

AEDisposeRemoteProcessResolver

Disposes of an AERemoteProcessResolverRef.

void AEDisposeRemoteProcessResolver (
   AERemoteProcessResolverRef ref
);

Parameters

ref: The AERemoteProcessResolverRef to dispose of. Acquired from a previous call to AECreateRemoteProcessResolver.

Discussion

If this resolver is currently scheduled on a run loop, it is unscheduled, and the asynchronous callback is not executed.

Version Notes

Thread safe starting in Mac OS X v10.3.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AppleEvents.h

AEDisposeToken

Deallocates the memory used by a token.

OSErr AEDisposeToken (
   AEDesc *theToken
);

Parameters

theToken: A pointer to the token to dispose of. On successful return, the pointer is set to the null descriptor. See AEDesc.

Return Value

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

Discussion

Your application calls the AEResolve function to resolve an object specifier, with the help of the object accessor functions described in “Object Accessor Callbacks” and the application object callback functions described in “Object Callback Functions”.

When AEResolve returns a final token to your event handler as the result of the resolution of an object specifier, your application must deallocate the memory used by the token. When your application calls the AEDisposeToken function, the Apple Event Manager first calls your application’s token disposal function, if you have provided one. The token disposal function is described in OSLDisposeTokenProcPtr.

If you haven’t provided a token disposal function, or if your application’s token disposal function returns errAEEventNotHandled as the function result, the Apple Event Manager calls the system token disposal function if one is available. If there is no system token disposal function or the function returns errAEEventNotHandled as the function result, the Apple Event Manager calls the AEDisposeDesc function to dispose of the token.

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

AEDuplicateDesc

Creates a copy of a descriptor.

OSErr AEDuplicateDesc (
   const AEDesc *theAEDesc,
   AEDesc *result
);

Parameters

theAEDesc: A pointer to the descriptor to duplicate. See AEDesc.
result: A pointer to a descriptor. On return, the descriptor contains a copy of the descriptor specified by the theAEDesc parameter. 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.”

Discussion

It is common for applications to send Apple events that have one or more attributes or parameters in common. For example, if you send a series of Apple events to the same application, the address attribute is the same. In these cases, the most efficient way to create the necessary Apple events is to make a template Apple event that you can then copy—by calling the AEDuplicateDesc function—as needed. You then fill in or change the remaining parameters and attributes of the copy, send the copy by calling the AESend function and, after AESend returns a result code, dispose of the copy by calling AEDisposeDesc. You can use this approach to prepare structures of type AEDesc, AEDescList, AERecord, and AppleEvent.

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

AEFlattenDesc

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

OSStatus AEFlattenDesc (
   const AEDesc *theAEDesc,
   Ptr buffer,
   Size bufferSize,
   Size *actualSize
);

Parameters

theAEDesc

A pointer to the descriptor to be flattened. See AEDesc.

buffer

A pointer to memory, allocated by the application, where the flattened data will be stored. See the bufferSize parameter for information on how large a buffer you should allocate.

bufferSize

The size of the buffer pointed to by buffer. Prior to calling AEFlattenDesc, you call the AESizeOfFlattenedDesc function to determine the required size of the buffer for the flatten operation.

If bufferSize is too small, AEFlattenDesc returns errAEBufferTooSmall and doesn’t store any data in the buffer.

actualSize

A pointer to a size variable. On return, the variable contains the actual size of the flattened data. You can specify NULL for this parameter if you do not care about the returned size.

Return Value

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

Discussion

Flattening a descriptor serializes the data it contains. That is, it reduces a complex, possibly deeply nested structure to a series of bytes that can conveniently be stored. The descriptor can be reconstituted from the stored bytes with the AEUnflattenDesc function.

Applications can be scriptable and work with Apple events without needing to flatten and unflatten descriptors. Flattening is a special-purpose capability that is useful in circumstances where it may be convenient to store data by saving and restoring a descriptor, rather than having to manually extract the data from it, store the data as a separate step, then manually recreate the descriptor (if necessary). For example, you might use flattening to store a preference setting received through an Apple event.

Flattening and unflattening should work without loss of data on descriptors that represent AEDesc, AEList, and AERecord structures. You can also use the process with AppleEvent descriptors. However, keep in mind that Apple events may contain attributes that are relevant only to a running process, and these attributes may not keep their meaning when the event is reconstituted.

Flattening and unflattening works across OS versions, including between Mac OS 9 and Mac OS X.

Flattening is endian-neutral. That is, you can save flattened data on a machine that is either big-endian or little-endian, then retrieve and unflatten the data on either type of machine, without any special steps by your application.

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

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.

OSErr AEGetArray (
   const AEDescList *theAEDescList,
   AEArrayType arrayType,
   AEArrayDataPointer arrayPtr,
   Size maximumSize,
   DescType *itemType,
   Size *itemSize,
   long *itemCount
);

Parameters

theAEDescList: A pointer to the descriptor list to get the array from. If the array is of type kAEDataArray, kAEPackedArray, or kAEHandleArray, the descriptor list must be factored. A factored descriptor list is one in which the Apple Event Manager automatically isolates the data that is common to all the elements of the list so that the common data only appears in the list once. To create a factored descriptor list, you call the AECreateList function and specify the data that is common to all elements in the descriptor array. See the Discussion section for related information. See AEDescList.
arrayType: The Apple event array type to convert. Pass one of the constants: described in “Data Array Constants.” See AEArrayType.
arrayPtr: A pointer to a buffer, allocated and disposed of by your application, for storing the array. The size in bytes must be at least as large as the value you pass in the maximumSize parameter. On return, the buffer contains the array of fixed-size items. See AEArrayDataPointer.
maximumSize: The maximum length, in bytes, of the expected data. The AEGetArray function will not return more data than you specify in this parameter.
itemType: A pointer to a descriptor type. On return, for arrays of type kAEDataArray, kAEPackedArray, or kAEHandleArray, the descriptor type of the items in the returned array. The AEGetArray function doesn’t supply a value in itemType for arrays of type kAEDescArray and kAEKeyDescArray because they may contain descriptors of different types. Possible descriptor types are listed in “Descriptor Type Constants.” See DescType.
itemSize: A pointer to a size variable. On return, for arrays of type kAEDataArray or kAEPackedArray, the size (in bytes) of each item in the returned array. You don’t get an item size for arrays of type kAEDescArray, kAEKeyDescArray, or kAEHandleArray because descriptors and handles (though not the data they point to) have a known size.
itemCount: A pointer to a size variable. On return, the number of items in the returned array.

Return Value

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

Discussion

The AEGetArray function uses a buffer identified by the pointer in the arrayPtr parameter to store the converted data for the Apple event array specified by the theAEDescList parameter. For example, AEGetArray may convert an array of descriptors of type typeLongInteger into a simple array of integer values or an array of descriptors of type typeFSS into an array of file specification records.

Even if the descriptor list that contains the array is factored, the converted data for each array item includes the data common to all the descriptors in the list. The Apple Event Manager automatically reconstructs the common data for each item when you call AEGetArray.

For information about creating and factoring descriptor lists for Apple event arrays, see AECreateList. For information about adding an Apple event array to a descriptor list, see AEPutArray.

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

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.

OSErr AEGetAttributeDesc (
   const AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType desiredType,
   AEDesc *result
);

Parameters

theAppleEvent: A pointer to the Apple event to get the attribute descriptor from. See AppleEvent.
theAEKeyword: The keyword that specifies the desired attribute. Some keyword constants are described in “Keyword Attribute Constants.” See AEKeyword.
result: A pointer to a descriptor. On successful return, a copy of the specified Apple event attribute, coerced, if necessary, to the descriptor type specified in desiredType. 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.”

Discussion

To get Apple event attribute data for your application to use directly, call AEGetAttributePtr. To get a descriptor for an Apple event attribute to pass on to another Apple Event Manager routine, call AEGetAttributeDesc.

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

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.

OSErr AEGetAttributePtr (
   const AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType desiredType,
   DescType *typeCode,
   void *dataPtr,
   Size maximumSize,
   Size *actualSize
);

Parameters

theAppleEvent

A pointer to the Apple event to get the attribute data from. See AppleEvent.

theAEKeyword

The keyword that specifies the desired attribute. Some keyword constants are described in “Keyword Attribute Constants.” See AEKeyword.

desiredType

The desired descriptor type for the copied data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If the descriptor specified by the theAEKeyword parameter is not of the desired type, AEGetAttributePtr attempts to coerce the data to this type. However, if you pass a value of typeWildCard, no coercion is performed, and the descriptor type of the returned data is the same as the descriptor type of the Apple event attribute.

On return, you can determine the actual descriptor type by examining the typeCode parameter.

See DescType.

typeCode

A pointer to a descriptor type. On return, specifies the descriptor type of the attribute data pointed to by dataPtr. The returned type is either the same as the type specified by the desiredType parameter or, if the desired type was type wildcard, the true type of the descriptor. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.

dataPtr

A pointer to a buffer, local variable, or other storage location, created and disposed of by your application. The size in bytes must be at least as large as the value you pass in the maximumSize parameter. On return, contains the attribute data.

maximumSize

The maximum length, in bytes, of the expected attribute data. The AEGetAttributePtr function will not return more data than you specify in this parameter.

actualSize

A pointer to a size variable. On return, the length, in bytes, of the data for the specified Apple event attribute. If this value is larger than the value you passed in the maximumSize parameter, the buffer pointed to by dataPtr was not large enough to contain all of the data for the attribute, though AEGetAttributePtr does not write beyond the end of the buffer. If the buffer was too small, you can resize it and call AEGetAttributePtr again.

Return Value

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

Discussion

Before calling AEGetAttributePtr, you can call the AESizeOfAttribute function to determine a size for the dataPtr buffer. However, unless you specify typeWildCard for the desiredType parameter, AEGetAttributePtr may coerce the data, which may cause the size of the data to change.

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

AEGetCoercionHandler

Gets the coercion handler for a specified descriptor type.

OSErr AEGetCoercionHandler (
   DescType fromType,
   DescType toType,
   AECoercionHandlerUPP *handler,
   SRefCon *handlerRefcon,
   Boolean *fromTypeIsDesc,
   Boolean isSysHandler
);

Parameters

fromType: The descriptor type of the data coerced by the handler. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
toType: The descriptor type of the resulting data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”
handler: A universal procedure pointer. On return, a pointer to the specified handler, if a coercion table entry exists that exactly matches the values supplied in the parameters fromType and toType. See AECoercionHandlerUPP.
handlerRefcon: A pointer to a reference constant. On return, the reference constant from the coercion table entry for the specified coercion handler. The Apple Event Manager passes this reference constant to the handler each time it calls the handler. The reference constant may have a value of 0.
fromTypeIsDesc: A pointer to a Boolean value. The AEGetCoercionHandler function returns a value of TRUE in this parameter if the coercion handler expects the data as a descriptor or FALSE, if the coercion handler expects a pointer to the data.
isSysHandler: Specifies the coercion table to get the handler from. Pass TRUE to get the handler from the system coercion table or FALSE to get the handler from your application’s coercion table. Use of the system coercion table is not recommended.

Return Value

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

Version Notes

Thread safe starting in Mac OS X v10.2.

Your application should not install a coercion handler in a system coercion handler dispatch table with the goal that the handler will get called when other applications perform coercions—this won’t work in Mac OS X. For more information, see “Writing and Installing Coercion Handlers” in Apple Events Programming Guide.

In Mac OS 7.1 through 9.x and Mac OS X version v10.2 and later, AEGetCoercionHandler returns errAEHandlerNotInstalled when there’s not an exact match, even if a wildcard handler is installed that could handle the coercion. Mac OS X version v10.0.x and v10.1.x will return the wildcard handler.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AEGetDescData

Gets the data from the specified descriptor.

OSErr AEGetDescData (
   const AEDesc *theAEDesc,
   void *dataPtr,
   Size maximumSize
);

Parameters

theAEDesc: A pointer to the descriptor to get the data from. See AEDesc.
dataPtr: A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size in bytes should be the same as the value you pass in the maximumSize parameter. On return, contains the data from the descriptor.
maximumSize: The length, in bytes, of the expected descriptor data. The AEGetDescData function will not return more data than you specify in this parameter. You typically determine the maximum size by calling AEGetDescDataSize.

Return Value

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

Discussion

Your application can call AEGetDescDataSize to get the size, in bytes, of the data in a descriptor, allocate a buffer or variable of that size, then call AEGetDescData to get the data.

This function works only with value descriptors created by AECreateDesc. You cannot get the data of an AERecord or AEDescList, for example.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

AEDataModel.h

AEGetDescDataRange

Retrieves a specified series of bytes from the specified descriptor.

OSStatus AEGetDescDataRange (
   const AEDesc *dataDesc,
   void *buffer,
   Size offset,
   Size length
);

Parameters

dataDesc: A pointer to the descriptor to get the data from. See AEDesc.
buffer: A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size in bytes should be at least as large as the value you pass in the length parameter. On return, contains the specified data from the descriptor.
offset: The zero-based offset to the data to be retrieved from the descriptor.
length: The number of bytes of contiguous data to retrieve.

Return Value

A result code. If the requested offset and length are such that they do not fit entirely within the descriptor’s data, AEGetDescDataRange returns errAEBufferTooSmall. See also “Apple Event Manager Result Codes.”

Discussion

This function is valid only for value type descriptors (such astypeUTF8Text). You can use this function when you know the precise location of a subset of data within the descriptor. For example, if the descriptor contains a block of your private data, you might retrieve just a particular chunk you need at a known offset, representing an image, a string, or some other data type. Or if a descriptor contains an RGB color, you can access just the blue field.

When used in conjunction with AECreateDescFromExternalPtr, AEGetDescDataRange can provide greatly improved performance, especially when working with large blocks of data.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AEDataModel.h

AEGetDescDataSize

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

Size AEGetDescDataSize (
   const AEDesc *theAEDesc
);

Parameters

theAEDesc: A pointer to the descriptor to obtain the data size for. See AEDesc.

Return Value

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

Discussion

This function works only with value descriptors created by AECreateDesc. You cannot get the data size of an AERecord or AEDescList, for example.

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

AEGetEventHandler

Gets an event handler from an Apple event dispatch table.

OSErr AEGetEventHandler (
   AEEventClass theAEEventClass,
   AEEventID theAEEventID,
   AEEventHandlerUPP *handler,
   SRefCon *handlerRefcon,
   Boolean isSysHandler
);

Parameters

theAEEventClass

The event class for the desired handler. See AEEventClass.

theAEEventID

The event ID for the desired handler. See AEEventID.

handler

A universal procedure pointer. On return, a pointer to the specified handler, if a dispatch table entry exists that exactly matches the values supplied in the parameters theAEEventClass and theAEEventID.

If you use the typeWildCard constant for either or both of these parameters, AEGetEventHandler will return an error unless an entry exists that specifies typeWildCard in exactly the same way. For example, if you specify typeWildCard in both the theAEEventClass parameter and the theAEEventID parameter, the Apple Event Manager will not return the first handler for any event class and event ID in the dispatch table; instead, it will only return a handler if an entry exists that specifies type typeWildCard for both the event class and the event ID.

For an explanation of wildcard values, see the Discussion section for AEInstallEventHandler.

See AEEventHandlerUPP.

handlerRefcon

A pointer to a reference constant. On return, the reference constant from the dispatch table entry for the specified handler. The reference constant may have a value of 0.

isSysHandler

Specifies the Apple event dispatch table to get the handler from. Pass TRUE to get the handler from the system dispatch table or FALSE to get the handler from your application’s dispatch table. See Version Notes for related information.

Return Value

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

Version Notes

Thread safe starting in Mac OS X v10.2.

Your application should not install a handler in a system dispatch table with the goal that the handler will get called when other applications receive events—this won’t work in Mac OS X. For more information, see “The System Dispatch Table” in “Apple Event Dispatching” in Apple Events Programming Guide.

In Mac OS 7.1 through 9.x and Mac OS X version v10.2 and later, AEGetEventHandler returns errAEHandlerNotInstalled when there’s not an exact match, even if a wildcard handler is installed that could handle the event. Mac OS X version v10.0.x and v10.1.x will return the wildcard handler.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AppleEvents.h

AEGetInteractionAllowed

Gets your application’s current user interaction preferences for responding to an Apple event as a server application.

OSErr AEGetInteractionAllowed (
   AEInteractAllowed *level
);

Parameters

level: A pointer to an interaction level variable. On return, the variable specifies the current user interaction level, matching one of the values described in “User Interaction Level Constants.”

Return Value

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

Discussion

The current user interaction preference for responding to an Apple event is set either by default (to kAEInteractWithLocal) or by a previous call to AESetInteractionAllowed.

For additional information on interaction level, see AESend and “AESendMode”.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AEGetKeyDesc

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

OSErr AEGetKeyDesc (
   AERecord *theAERecord,
   AEKeyword theAEKeyword,
   DescType desiredType,
   AEDesc *result
);

Parameters

theAERecord

A pointer to the Apple event record to get the parameter descriptor from.

theAEKeyword

A keyword that specifies the desired Apple event parameter. Some keyword constants are described in “Keyword Parameter Constants.” See AEKeyword.

desiredType

The descriptor type for the desired Apple event parameter. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If the requested Apple event parameter is not of the desired type, the Apple Event Manager attempts to coerce it to the desired type. However, if you pass a value of typeWildCard, no coercion is performed, and the descriptor type of the returned descriptor is the same as the descriptor type of the Apple event parameter.

See DescType.

result

A pointer to a descriptor. On successful return, a copy of the descriptor for the specified Apple event parameter, coerced, if necessary, to the descriptor type specified by the desiredType parameter. 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.”

Discussion

This function is declared as a macro that invokes AEGetParamDesc, which can operate on an Apple event or an Apple event record. See the Discussion for that function for more information.

Version Notes

See AEGetParamDesc.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AEGetKeyPtr

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

OSErr AEGetKeyPtr (
   AERecord *theAERecord,
   AEKeyword theAEKeyword,
   DescType desiredType,
   DescType *actualType,
   void *dataPtr,
   Size maximumSize,
   Size *actualSize
);

Parameters

theAERecord

A pointer to the Apple event record to get the parameter data from.

theAEKeyword

The keyword that specifies the desired Apple event record parameter. Some keyword constants are described in “Keyword Parameter Constants.”

desiredType

The desired descriptor type for the copied data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If the descriptor specified by the theAEKeyword parameter is not of the desired type, AEGetKeyPtr attempts to coerce the data to this type. However, if the desired type is typeWildCard, no coercion is performed.

On return, you can determine the actual descriptor type by examining the typeCode parameter.

typeCode

A pointer to a descriptor type. On return, specifies the descriptor type of the data pointed to by dataPtr. The returned type is either the same as the type specified by the desiredType parameter or, if the desired type was type wildcard, the true type of the descriptor. Specify NULL if you do not care about this return value. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

dataPtr

A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size in bytes must be at least as large as the value you pass in the maximumSize parameter. On return, contains the parameter data. Specify NULL if you do not care about this return value.

maximumSize

The maximum length, in bytes, of the expected Apple event record parameter data. The AEGetKeyPtr function will not return more data than you specify in this parameter.

actualSize

A pointer to a variable of type Size. On return, the length, in bytes, of the data for the specified Apple event record parameter. If this value is larger than the value you passed in the maximumSize parameter, the buffer pointed to by dataPtr was not large enough to contain all of the data for the parameter, though AEGetKeyPtr does not write beyond the end of the buffer. If the buffer was too small, you can resize it and call AEGetKeyPtr again. Specify NULL if you do not care about this return value.

Return Value

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

Discussion

This function is declared as a macro that invokes AEGetParamPtr, which can operate on an Apple event or an Apple event record. See the Discussion for that function for more information.

Version Notes

See AEGetParamPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

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.

OSErr AEGetNthDesc (
   const AEDescList *theAEDescList,
   long index,
   DescType desiredType,
   AEKeyword *theAEKeyword,
   AEDesc *result
);

Parameters

theAEDescList

A pointer to the descriptor list to get the descriptor from. See AEDescList.

index

A one-based positive integer indicating the position of the descriptor to get. AEGetNthDesc returns an error if you pass zero, a negative number, or a value that is out of range.

desiredType

The desired descriptor type for the descriptor to copy. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If the descriptor specified by the index parameter is not of the desired type, AEGetNthDesc attempts to coerce it to this type. However, if you pass a value of typeWildCard, no coercion is performed, and the descriptor type of the copied descriptor is the same as the descriptor type of the original descriptor.

See DescType.

theAEKeyword

A pointer to a keyword. On successful return, the keyword for the specified descriptor, if you are getting data from a list of keyword-specified descriptors; otherwise, AEGetNthDesc returns the value typeWildCard. Some keyword constants are described in “Keyword Attribute Constants” and “Keyword Parameter Constants.” See AEKeyword.

result

A pointer to a descriptor. On successful return, a copy of the descriptor specified by the index parameter, coerced, if necessary, to the descriptor type specified by the desiredType parameter. 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.”

Discussion

If the Nth descriptor in the list is itself an Apple event record and the desired type is not wildcard, record, or list, AEGetNthDesc will fail with an errAECoercionFailed error. This behavior prevents coercion problems.

You may find the AEGetNthPtr function convenient for retrieving data for direct use in your application, as it includes automatic coercion.

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

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.

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

Parameters

theAEDescList

A pointer to the descriptor list that contains the descriptor. See AEDescList.

index

A one-based positive integer indicating the position in the descriptor list of the descriptor to get the data from. AEGetNthPtr returns an error if you pass zero, a negative number, or a value that is out of range.

desiredType

The desired descriptor type for the copied data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If the descriptor specified by the index parameter is not of the desired type, AEGetNthPtr attempts to coerce the data to this type. If you pass a value of typeWildCard, no coercion is performed, and the descriptor type of the copied data is the same as the descriptor type of the original descriptor.

See DescType.

theAEKeyword

A pointer to a keyword. On return, the keyword for the specified descriptor, if you are getting data from a list of keyword-specified descriptors; otherwise, AEGetNthPtr returns the value typeWildCard. Some keyword constants are described in “Keyword Attribute Constants” and “Keyword Parameter Constants.” See AEKeyword.

typeCode

A pointer to a descriptor type. On return, specifies the descriptor type of the data pointed to by dataPtr. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

dataPtr

A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size in bytes must be at least as large as the value you pass in the maximumSize parameter. On return, contains the data from the descriptor at the position in the descriptor list specified by the index parameter.

maximumSize

The maximum length, in bytes, of the expected data. The AEGetNthPtr function will not return more data than you specify in this parameter.

actualSize

A pointer to a size variable. On return, the length, in bytes, of the data for the specified descriptor. If this value is larger than the value of the maximumSize parameter, the buffer pointed to by dataPtr was not large enough to contain all of the data for the descriptor, though AEGetNthPtr does not write beyond the end of the buffer. If the buffer was too small, you can resize it and call AEGetNthPtr again.

Return Value

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

Discussion

The AEGetNthPtr function uses a buffer to return the data for a specified descriptor from a specified descriptor list. The function attempts to coerce the descriptor to the descriptor type specified by the desiredType parameter.

Before calling AEGetNthPtr, you can call the AESizeOfNthItem function to determine a size for the dataPtr buffer. However, unless you specify typeWildCard for the desiredType parameter, AESizeOfNthItem may coerce the data, which may cause the size of the data to change. If you are using AEGetNthPtr to iterate through a list of descriptors of the same type with a fixed size, such as a list of descriptors of type typeFSS, you can get the size once, allocate a buffer, and reuse it for each call.

The order of items in an Apple event record may change after an insertion or deletion. In addition, duplicating an Apple event record is not guaranteed to preserve the item order.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

AEDataModel.h

AEGetObjectAccessor

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

OSErr AEGetObjectAccessor (
   DescType desiredClass,
   DescType containerType,
   OSLAccessorUPP *accessor,
   SRefCon *accessorRefcon,
   Boolean isSysHandler
);

Parameters

desiredClass: The object class of the Apple event objects located by the object accessor function to get. Pass the value typeWildCard to get an object accessor function whose entry in an object accessor dispatch table specifies typeWildCard as the object class. Pass the value cProperty to get an object accessor function whose entry in an object accessor dispatch table specifies cProperty (a constant used to specify a property of any object class). Some other possible values are defined in “Object Class ID Constants.” See DescType.
containerType: The descriptor type of the token that identifies the container for the objects located by the requested accessor function. (Token is defined in AEDisposeToken.) Pass the value typeWildCard to get an object accessor function whose entry in an object accessor dispatch table specifies typeWildCard as the descriptor type of the token used to specify the container type. See DescType.
accessor: A universal procedure pointer. On return, a pointer to the requested object accessor function, if an object accessor dispatch table entry exists that exactly matches the values supplied in the parameters desiredClass and containerType. See OSLAccessorUPP.
accessorRefcon: A pointer to a reference constant. On return, points to the reference constant from the object accessor dispatch table entry for the specified object accessor function. The reference constant may have a value of 0.
isSysHandler: Specifies the object accessor dispatch table to get the object accessor function from. Pass TRUE to get the object accessor function from the system object accessor dispatch table or FALSE to get the object accessor function from your application’s object accessor dispatch table. Use of the system object accessor dispatch table is not recommended.

Return Value

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

Discussion

Calling AEGetObjectAccessor does not remove the object accessor function from an object accessor dispatch table.

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

AEGetParamDesc

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

OSErr AEGetParamDesc (
   const AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType desiredType,
   AEDesc *result
);

Parameters

theAppleEvent

A pointer to the Apple event to get the parameter descriptor from.

theAEKeyword

A keyword that specifies the desired Apple event parameter. Some keyword constants are described in “Keyword Parameter Constants.”

desiredType

The descriptor type for the desired Apple event parameter. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

result

Return Value

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

Discussion

You typically call AEGetParamDesc to get a descriptor for an Apple event parameter to pass on to another Apple Event Manager routine. To get Apple event parameter data for your application to use directly, call AEGetParamPtr.

If the actual parameter you are getting with AEGetParamDesc is a record, you can only request it as a typeAERecord, typeAEList, or typeWildcard. For any other type, AEGetParamDesc will return errAECoercionFail.

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

QTCarbonShell

Declared In

AEDataModel.h

AEGetParamPtr

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

OSErr AEGetParamPtr (
   const AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType desiredType,
   DescType *actualType,
   void *dataPtr,
   Size maximumSize,
   Size *actualSize
);

Parameters

theAppleEvent

A pointer to the Apple event to get the parameter data from.

theAEKeyword

The keyword that specifies the desired Apple event parameter. Some keyword constants are described in “Keyword Parameter Constants.”

desiredType

The desired descriptor type for the copied data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If the descriptor specified by the theAEKeyword parameter is not of the desired type, AEGetParamPtr attempts to coerce the data to this type. However, if the desired type is typeWildCard, no coercion is performed.

On return, you can determine the actual descriptor type by examining the typeCode parameter.

typeCode

dataPtr

maximumSize

The maximum length, in bytes, of the expected Apple event parameter data. The AEGetParamPtr function will not return more data than you specify in this parameter.

actualSize

A pointer to a variable of type Size. On return, the length, in bytes, of the data for the specified Apple event parameter. If this value is larger than the value you passed in the maximumSize parameter, the buffer pointed to by dataPtr was not large enough to contain all of the data for the parameter, though AEGetParamPtr does not write beyond the end of the buffer. If the buffer was too small, you can resize it and call AEGetParamPtr again. Specify NULL if you do not care about this return value.

Return Value

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

Discussion

You should use this function only to extract data from value descriptors such as typeUTF8Text.

Because this function allows you to specify a desired type, it can result in coercion. When used correctly, this has the positive effect of returning the data in the desired format. However, it can have side effects you may not be expecting, such as the overhead of calls to coercion handlers. See also the Version Notes section below for possible problems with coercion.

To get Apple event parameter data for your application to use directly, call AEGetParamPtr. To get a descriptor for an Apple event parameter to pass on to another Apple Event Manager routine, call AEGetParamDesc.

Before calling AEGetParamPtr, you can call the AESizeOfParam function to determine a size for the dataPtr buffer. However, unless you specify typeWildCard for the desiredType parameter, AEGetParamPtr may coerce the data, which may cause the size of the data to change.

In some cases, you may get improved efficiency extracting information from an Apple event with the AEGetDescDataRange function.

Version Notes

Thread safe starting in Mac OS X v10.2.

If the actual parameter you are getting with AEGetParamPtr is a record, AEGetParamPtr will erroneously allow you to get the parameter as any type at all, when it really should allow only typeAERecord, typeAEList, or typeWildcard. For other types, it will place raw record data into the designated buffer. With AppleScript 1.1.2, it would then return errAECoercionFail, as expected. With AppleScript 1.3 and later, however, it returns noErr.

You can work around this problem by checking the returned parameter from any call to AEGetParamPtr. If the source type is typeAERecord and the type you asked for was anything other than typeAERecord, typeAEList, or typeWildcard, you should assume the coercion failed.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AEGetRegisteredMachPort

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

mach_port_t AEGetRegisteredMachPort (
   void
);

Return Value

Returns a Mach message port header.

Discussion

Apple events on Mac OS X are implemented in terms of Mach messages. If your application links with the Carbon umbrella framework, it includes the HIToolbox framework, which initializes a Mach port and registers it with the run loop for the application. That port is considered public, and is used for sending and receiving Apple events.

Linking with the HIToolbox also requires that the application have a connection to the window server. To facilitate writing server processes that can send and receive Apple events, the Apple Event Manager provides the following functions (on Mac OS X only): AEGetRegisteredMachPort, AEDecodeMessage, AESendMessage, and AEProcessMessage. Daemons and other processes with no user interface can take advantage of these functions, while typical high-level applications will have no need for them.

If your code doesn’t link with the HIToolbox or doesn’t have a run loop, it can call AEGetRegisteredMachPort to register a port directly, then listen on that port for Apple events. It can use the other low-level functions to process incoming Apple events on the port and to send Apple events through it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEMach.h

AEGetSpecialHandler

Gets a specified handler from a special handler dispatch table.

OSErr AEGetSpecialHandler (
   AEKeyword functionClass,
   AEEventHandlerUPP *handler,
   Boolean isSysHandler
);

Parameters

functionClass: The keyword for the special handler to get. You can specify any of the constants described in “Special Handler Callback Constants.” See AEKeyword.
handler: A universal procedure pointer. On return, a pointer to the specified special handler, if one exists that matches the value supplied in the functionClass parameter. See AEEventHandlerUPP.
isSysHandler: Specifies the special handler dispatch table to get the handler from. Pass TRUE to get the handler from the system special handler dispatch table or FALSE to get the handler from your application’s special handler dispatch table. Use of the system special handler dispatch table is not recommended.

Return Value

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

Discussion

Version Notes

Thread safe starting in Mac OS X v10.2.

In Mac OS X, you should generally install all handlers in the application dispatch table. For Carbon applications running in Mac OS 8 or Mac OS 9, a special handler in the system dispatch table could reside in the system heap, where it would be available to other applications. However, this won’t work in Mac OS X.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AppleEvents.h

AEGetTheCurrentEvent

Gets the Apple event that is currently being handled.

OSErr AEGetTheCurrentEvent (
   AppleEvent *theAppleEvent
);

Parameters

theAppleEvent: A pointer to an Apple event. On return, the Apple event that is currently being handled. If no Apple event is currently being handled, AEGetTheCurrentEvent supplies a descriptor of descriptor type typeNull, which does not contain any data. See AppleEvent.

Return Value

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

Discussion

In many applications, the handling of an Apple event involves one or more long chains of calls to internal functions. The AEGetTheCurrentEvent function makes it unnecessary for these calls to include the current Apple event as a parameter; the functions can simply call AEGetTheCurrentEvent to get the current Apple event when it is needed.

You can also use the AEGetTheCurrentEvent function to make sure that no Apple event is currently being handled. For example, suppose your application always uses an application-defined function to delete a file. That function can first call AEGetTheCurrentEvent and delete the file only if AEGetTheCurrentEvent returns a null descriptor (that is, only if no Apple event is currently being handled).

Special Considerations

This function is not thread-safe and should only be called on the main thread.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AEInitializeDesc

Initializes a new descriptor.

void AEInitializeDesc (
   AEDesc *desc
);

Parameters

desc: A pointer to a new descriptor. See AEDesc.

Discussion

The function sets the type of the descriptor to typeNull and sets the data handle to NULL. If you need to initialize a descriptor that already has some data in it, use AEDisposeDesc to deallocate the memory and initialize the descriptor.

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

AEInstallCoercionHandler

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

OSErr AEInstallCoercionHandler (
   DescType fromType,
   DescType toType,
   AECoercionHandlerUPP handler,
   SRefCon handlerRefcon,
   Boolean fromTypeIsDesc,
   Boolean isSysHandler
);

Parameters

fromType

The descriptor type of the data coerced by the handler. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.

toType

The descriptor type of the resulting data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.”

If there was already an entry in the specified coercion handler table for the same source descriptor type and result descriptor type, the existing entry is replaced. See DescType.

handler

A universal procedure pointer to the coercion handler function to install. See AECoercionHandlerUPP.

handlerRefcon

A reference constant. The Apple Event Manager passes this value to the handler each time it calls it. If your handler doesn’t require a reference constant, pass 0 for this parameter.

fromTypeIsDesc

Specifies the form of the data to coerce. Pass TRUE if the coercion handler expects the data as a descriptor or FALSE if the coercion handler expects a pointer to the data. The Apple Event Manager can provide a pointer to data more efficiently than it can provide a descriptor, so all coercion functions should accept a pointer to data if possible.

isSysHandler

Specifies the coercion table to add the handler to. Pass TRUE to add the handler to the system coercion table or FALSE to add the handler to your application’s coercion table. Use of the system coercion table is not recommended.

Return Value

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

Discussion

Before using AEInstallCoercionHandler to install a handler for a particular descriptor type, you can use the AEGetCoercionHandler function to determine whether the table already contains a coercion handler for that type.

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

AEInstallEventHandler

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

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

Parameters

theAEEventClass: The event class for the Apple event or events to dispatch to this event handler. The Discussion section describes interactions between this parameter and the theAEEventID parameter. See AEEventClass.
theAEEventID: The event ID for the Apple event or events to dispatch to this event handler. The Discussion section describes interactions between this parameter and the theAEEventClass parameter. See AEEventID.
handler: A universal procedure pointer to the Apple event handler function to install. See AEEventHandlerUPP.
handlerRefcon: A reference constant. The Apple Event Manager passes this value to the handler each time it calls it. If your handler doesn’t require a reference constant, pass 0 for this parameter.
isSysHandler: Specifies the Apple event dispatch table to add the handler to. Pass TRUE to add the handler to the system dispatch table or FALSE to add the handler to your application’s dispatch table. See Version Notes for related information.

Return Value

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

Discussion

The parameters theAEEventClass and theAEEventID specify the event class and event ID of the Apple events handled by the handler for this dispatch table entry. If there is already an entry in the specified dispatch table for the same event class and event ID, it is replaced. For these parameters, you must provide one of the following combinations:

the event class and event ID of a single Apple event to dispatch to the handler (for example, an event class of kAECoreSuite and an event ID of kAEDelete so that a specific kind of delete event is dispatched to the handler)
the typeWildCard constant for theAEEventClass and an event ID for theAEEventID, which indicates that Apple events from all event classes whose event IDs match theAEEventID should be dispatched to the handler (for example, an event class of typeWildCard and an event ID of kAEDelete so that for all event classes, the delete event is dispatched to the handler)
an event class for theAEEventClass and the typeWildCard constant for theAEEventID, which indicates that all events from the specified event class should be dispatched to the handler (for example, an event class of kAECoreSuite and an event ID of typeWildCard so that all events for the core suite are dispatched to the handler)
the typeWildCard constant for both the theAEEventClass and theAEEventID parameters, which indicates that all Apple events should be dispatched to the handler

If you use the typeWildCard constant for either the theAEEventClass or the theAEEventID parameter (or for both parameters), the corresponding handler must return the error errAEEventNotHandled if it does not handle a particular event.

If an Apple event dispatch table contains one entry for an event class and a specific event ID, and also contains another entry that is identical except that it specifies a wildcard value for either the event class or the event ID, the Apple Event Manager dispatches the more specific entry. For example, if an Apple event dispatch table includes one entry that specifies the event class as kAECoreSuite and the event ID as kAEDelete, and another entry that specifies the event class as kAECoreSuite and the event ID as typeWildCard, the Apple Event Manager dispatches the Apple event handler associated with the entry that specifies the event ID as kAEDelete.

In addition to the Apple event handler dispatch tables, applications can add entries to special handler dispatch tables, as described in “Managing Special Handler Dispatch Tables.”

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

AppleEvents.h

AEInstallObjectAccessor

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

OSErr AEInstallObjectAccessor (
   DescType desiredClass,
   DescType containerType,
   OSLAccessorUPP theAccessor,
   SRefCon accessorRefcon,
   Boolean isSysHandler
);

Parameters

desiredClass: The object type of the Apple event objects located by this accessor. See DescType.
containerType: The type of the token whose objects are accessed by this accessor. (Token is defined in AEDisposeToken.) The accessor function finds objects in containers specified by tokens of this type. See DescType.
theAccessor: A universal procedure pointer to the object accessor function to install. See OSLAccessorUPP.
accessorRefcon: A reference constant the Apple Event Manager passes to the object accessor function whenever it calls the function. If your object accessor function doesn’t require a reference constant, pass 0 for this parameter. To change the value of the reference constant, you must call AEInstallObjectAccessor again.
isSysHandler: Specifies the object accessor dispatch table to add the entry to. Pass TRUE to add the entry to the system object accessor dispatch table or FALSE to add the entry to your application’s object accessor dispatch table. Use of the system object accessor dispatch table is not recommended.

Return Value

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

Discussion

The AEInstallObjectAccessor function adds or replaces an entry to either the application or system object accessor dispatch table.

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.

If your Carbon application running in Mac OS 8 or OS 9 installs a system object accessor function in its application heap, rather than in the system heap, you must call AERemoveObjectAccessor to remove the function before your application terminates.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

AEInstallSpecialHandler

Installs a callback function in a special handler dispatch table.

OSErr AEInstallSpecialHandler (
   AEKeyword functionClass,
   AEEventHandlerUPP handler,
   Boolean isSysHandler
);

Parameters

functionClass

A value that specifies the type of handler to install. You can use any of the constants defined in “Special Handler Callback Constants.”

If there is already an entry in the specified special handler dispatch table for the value you specify in this parameter, it is replaced.

See AEKeyword.

handler

A universal procedure pointer to the special handler to install. See AEEventHandlerUPP.

isSysHandler

Specifies the special handler dispatch table to add the handler to. Pass TRUE to add the handler to the system special handler dispatch table or FALSE to add the handler to your application’s special handler dispatch table. Use of the system special handler dispatch table is not recommended.

Return Value

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

Discussion

An Apple event special handler dispatch table contains entries with a function class keyword, the address of the handler function that handles the Apple events indicated by the keyword, and a reference constant. Depending on which handlers you choose to install, a special handler dispatch table can have entries for any of the following:

a predispatch handler (an Apple event handler that the Apple Event Manager calls immediately before it dispatches an Apple event)
up to one each of the callback functions described in “Object Callback Functions” these functions, such as an object comparison function and an object-counting function, can be installed with AEInstallSpecialHandler or with the AEInstallObjectAccessor function

See also AEGetSpecialHandler and AERemoveSpecialHandler.

Version Notes

Thread safe starting in Mac OS X v10.2.

For Carbon applications running in Mac OS 8 or Mac OS 9, a handler in the system special handler dispatch table should reside in the system heap, where it may be available to other applications. If you put your system handler code in your application heap, be sure to use AERemoveSpecialHandler to remove the handler when your application quits. Otherwise, your handler will still have an entry in the system dispatch table with a pointer a handler that no longer exists. Another application may dispatch an Apple event that attempts to call your handler, leading to a system crash.

Your application should not install a handler in a system dispatch table with the goal that the handler will get called when other applications receive events—this won’t work in Mac OS X.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AppleEvents.h

AEInteractWithUser

Initiates interaction with the user when your application is a server application responding to an Apple event.

OSErr AEInteractWithUser (
   SInt32 timeOutInTicks,
   NMRecPtr nmReqPtr,
   AEIdleUPP idleProc
);

Parameters

timeOutInTicks: The amount of time (in ticks) that your handler is willing to wait for a response from the user. You can specify a number of ticks or use one of the constants defined in “Timeout Constants.”
nmReqPtr: A pointer to a Notification Manager record provided by your application. You can specify NULL for this parameter to get the default notification handling provided by the Apple Event Manager. See the Notification Manager documentation for a description of the NMRecPtr data type.
idleProc: A universal procedure pointer to your application’s idle function, which handles events while waiting for the Apple Event Manager to return control. See AEIdleUPP.

Return Value

A result code. See “Apple Event Manager Result Codes.” The AEInteractWithUser function returns the errAENoUserInteraction result code if the user interaction preferences don’t allow user interaction. If AEInteractWithUser returns the noErr result code, then your application is in the foreground and is free to interact with the user.

Discussion

Your application should call the AEInteractWithUser function before displaying a dialog box or alert box or otherwise interacting with the user in response to an Apple event. The AEInteractWithUser function checks whether the client application set the kAENeverInteract flag for the current Apple event, if any, and if so, returns an error. If not, then AEInteractWithUser checks the server application’s preference set by the AESetInteractionAllowed function and compares it against the source of the Apple event—that is, whether it came from the same application, another process on the same computer, or a process running on another computer.

If the user interaction preference settings permit the application to come to the foreground, this function brings your application to the front, either directly or by posting a notification request.

Your application should normally pass a notification record in the nmReqPtr parameter rather than specifying NULL for default notification handling. If you specify NULL, the Apple Event Manager looks for an application icon with the ID specified by the application’s bundle ('BNDL') resource and the application’s file reference ('FREF') resource. The Apple Event Manager first looks for an 'SICN' resource with the specified ID if it can’t find an 'SICN' resource, it looks for the 'ICN#' resource and compresses the icon to fit in the menu bar. The Apple Event Manager won’t look for any members of an icon family other than the icon specified in the 'ICN#' resource.

If the application doesn’t have 'SICN' or 'ICN#' resources, or if it doesn’t have a file reference resource, the Apple Event Manager passes no icon to the Notification Manager, and no icon appears in the upper-right corner of the screen. Therefore, if you want to display any icon other than those of type 'SICN' or 'ICN#', you must specify a notification record as the second parameter to the AEInteractWithUser function.

If you want the Notification Manager to use a color icon when it posts a notification request, you should provide a Notification Manager record that specifies a 'cicn' resource.

For additional information on interaction level, see AESend and “AESendMode”.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AEManagerInfo

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

OSErr AEManagerInfo (
   AEKeyword keyWord,
   long *result
);

Parameters

keyWord

A value that determines the kind of information the function supplies in the result parameter.

Pass the value keyAERecorderCount to obtain the number of processes that are currently recording Apple events.

Pass the value keyAEVersion to obtain version information for the Apple Event Manager, in NumVersion format.

Some keyword constants are defined in “Keyword Parameter Constants.”

See AEKeyword.

result

A pointer to a long value. On return, provides information that depends on what you pass in the keyword parameter.

If you pass keyAERecorderCount, result specifies the number of processes that are currently recording Apple events.

If you pass keyAEVersion, result supplies version information for the Apple Event Manager, in a format that matches the 'vers' resource.

Return Value

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

Discussion

For recordable applications, the information provided by AEManagerInfo may be useful when the application is responding to Apple events that it sends to itself.

For information on determining whether the Apple Event Manager is available, see the Apple Event Manager Gestalt Selector, described in Inside Mac OS X: Gestalt Manager Reference.

Version Notes

Thread safe starting in Mac OS X v10.2.

The AEManagerInfo function is available only in version 1.01 and later of the Apple Event Manager.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AppleEvents.h

AEObjectInit

Initializes the Object Support Library.

OSErr AEObjectInit (
   void
);

Return Value

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

Discussion

You must call this function before calling any of the Apple Event Manager functions that describe or manipulate Apple event objects.

You should call the AEObjectInit function to initialize the Apple Event Manager functions that handle object specifiers and Apple event objects.

Version Notes

To make these functions available to your application with version 1.01 and earlier versions of the Apple Event Manager, you must also link the Apple Event Object Support Library with your application when you build it. For more information, see the Version Notes section for the AppleScript Gestalt Selector described in Inside Mac OS X: Gestalt Manager Reference and the function AERemoveSpecialHandler.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

AEPrintDescToHandle

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

OSStatus AEPrintDescToHandle (
   const AEDesc *desc,
   Handle *result
);

Parameters

desc: A pointer to a descriptor containing the information to be printed. See AEDesc.
result: A pointer to a location for a new Handle data type. On return, contains a new handle allocated by the Memory Manager.

Return Value

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

Discussion

The data handle returned in the result parameter contains a text string formatted using the “AEBuild” syntax. This string is useful for looking at the contents of Apple events sent by other applications and for debugging your own descriptors.

AEPrintDescToHandle prints the contents of AEDesc, AERecord, and AEDescList descriptors in a format that is suitable for input to AEBuildDesc. AEPrintDescToHandle also attempts display coerced Apple event records as the coerced record type instead of as the original type. Any data structures that cannot be identified are displayed as hexadecimal data.

AEPrintDescToHandle prints the contents of Apple events in a slightly different format. For these events, the event class and event ID appear at the beginning of the output string, followed by the contents of the event enclosed in curly braces. In addition, each attribute is printed with its four-character identifier and preceded by an ampersand character. You cannot use the output string to recreate the Apple event from AEBuildAppleEvent.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEProcessAppleEvent

Calls the handler, if one exists, for a specified Apple event.

OSErr AEProcessAppleEvent (
   const EventRecord *theEventRecord
);

Parameters

theEventRecord: A pointer to the event record for the Apple event to process. See the Event Manager documentation for a description of the EventRecord data type.

Return Value

A result code. See “Apple Event Manager Result Codes.” This is the error result from the Apple event handler (or errAEHandlerNotFound). In most cases your application should ignore this error because it will be seen by the Apple event sender as the keyErrorNumber parameter in the reply.

Discussion

After receiving a high-level event (and optionally determining whether it is a type of high-level event other than an Apple event that your application might support), your application typically calls the AEProcessAppleEvent function to determine the type of Apple event received and call the corresponding handler. Your application should always handle high-level events immediately, or the Apple Event Manager may return the event to the sending application with the errAEEventNotHandled result code.

The AEProcessAppleEvent function looks first in the application’s special handler dispatch table for an entry that was installed by the AEInstallSpecialHandler function with the constant keyPreDispatch. If the application’s special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, AEProcessAppleEvent looks in the application’s Apple event dispatch table for an entry that matches the event class and event ID of the specified Apple event. You install handlers in the application’s dispatch table with the AEInstallEventHandler function.

If the application’s Apple event dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, the AEProcessAppleEvent function looks in the system special handler dispatch table for an entry that was installed with the constant keyPreDispatch. If the system special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, AEProcessAppleEvent looks in the system Apple event dispatch table for an entry that matches the event class and event ID of the specified Apple event.

If the system Apple event dispatch table does not include such a handler, the Apple Event Manager returns the result code errAEEventNotHandled to the server (or target) application and, if the client application is waiting for a reply, to the client application.

If AEProcessAppleEvent finds an entry in one of the dispatch tables that matches the event class and event ID of the specified Apple event, it calls the corresponding handler.

If an Apple event dispatch table contains one entry for an event class and a specific event ID, and also contains another entry that specifies a wildcard value for either the event class or the event ID, the Apple Event Manager uses the more specific entry. For example, if one entry specifies an event class of kAECoreSuite and an event ID of kAEDelete and another entry specifies an event class of kAECoreSuite and an event ID of typeWildCard, the Apple Event Manager will dispatch an Apple event with an event ID of kAEDelete to the handler from the entry that specifies the event ID as kAEDelete.

Version Notes

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Simple DrawSprocket

Declared In

AEInteraction.h

AEProcessMessage

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

OSStatus AEProcessMessage (
   mach_msg_header_t *header
);

Parameters

header: A pointer to the received Mach message that should be processed. The contents of the message header are invalid after calling this method.

Return Value

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

Discussion

If your daemon or other code has initialized a Mach port and is listening on it for Apple events and other messages, it can call AEProcessMessage to handle any incoming events it identifies as Apple events, while handling other types of events itself. AEProcessMessage will dispatch the event to an event handler (by calling AEDecodeMessage for you) and package and return the reply to the sender, simplifying handling for your code.

The Apple Event Manager reserves Mach message IDs in the range 0 to 999 for its own use. AEProcessMessage returns a paramErr result code if the Mach message did not contain an Apple event.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEMach.h

AEPutArray

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

OSErr AEPutArray (
   AEDescList *theAEDescList,
   AEArrayType arrayType,
   const AEArrayData *arrayPtr,
   DescType itemType,
   Size itemSize,
   long itemCount
);

Parameters

theAEDescList

A pointer to the descriptor list to put the Apple event array into. If there are any descriptors already in the descriptor list, they are replaced. If the array type is kAEKeyDescArray, theAEDescList must point to an Apple event record; otherwise, it can point to either a descriptor list or an Apple event record.

If you pass a pointer to a factored descriptor list, created by calling the AECreateList function, each array item in the array pointed to by the arrayPtr parameter must include the data that is common to all the descriptors in the list. The Apple Event Manager automatically isolates the common data you specified in the call to AECreateList. A factored descriptor list is described in the Discussion section.

See AEDescList.

arrayType

The Apple event array type to create. Pass a value specified by one of the constants described in “Data Array Constants.” See AEArrayType.

arrayPtr

A pointer to a buffer, local variable, or other storage location, created and disposed of by your application, that contains the array to put into the descriptor list. See AEArrayData.

itemType

For arrays of type kAEDataArray, kAEPackedArray, or kAEHandleArray, the descriptor type of the array items to create. Use one of the constants described in “Descriptor Type Constants,” such as typeLongInteger. You don’t need to specify an item type for arrays of type kAEDescArray or kAEKeyDescArray because the data is already stored in descriptors which contain a descriptor type. See DescType.

itemSize

For arrays of type kAEDataArray or kAEPackedArray, the size (in bytes) of the array items to create. You don’t need to specify an item size for arrays of type kAEDescArray, kAEKeyDescArray, or kAEHandleArray because their descriptors (though not the data they point to) have a known size.

itemCount

The number of elements in the array.

Return Value

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

Discussion

A factored descriptor list is one in which the Apple Event Manager automatically isolates the data that is common to all the elements of the list so that the common data only appears in the list once. To create a factored descriptor list, you call the AECreateList function and specify the data that is common to all elements in the descriptor array.

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

AEPutAttributeDesc

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

OSErr AEPutAttributeDesc (
   AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   const AEDesc *theAEDesc
);

Parameters

theAppleEvent

A pointer to the Apple event to add an attribute to. See the AppleEvent data type.

theAEKeyword

The keyword for the attribute to add. If the Apple event already includes an attribute with this keyword, the attribute is replaced.

Some keyword constants are described in “Keyword Attribute Constants.”

See AEKeyword.

theAEDesc

A pointer to the descriptor to assign to the attribute. The descriptor type of the specified descriptor should match the defined descriptor type for that attribute. See AEDesc.

Return Value

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

Discussion

The AEPutAttributeDesc function takes a descriptor and a keyword and adds them to an Apple event as an attribute. If the descriptor type required for the attribute is different from the descriptor type of the descriptor, the Apple Event Manager attempts to coerce the descriptor into the required type, with one exception: the Apple Event Manager does not attempt to coerce the data for an address attribute, thereby allowing applications to use their own address types.

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

AEPutAttributePtr

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

OSErr AEPutAttributePtr (
   AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType typeCode,
   const void *dataPtr,
   Size dataSize
);

Parameters

theAppleEvent

A pointer to the Apple event to add an attribute to. See the AppleEvent data type.

theAEKeyword

The keyword for the attribute to add. If the Apple event already includes an attribute with this keyword, the attribute is replaced.

Some keyword constants are described in “Keyword Attribute Constants.”

See AEKeyword.

typeCode

The descriptor type for the attribute to add. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.

dataPtr

A pointer to the data for the attribute to add.

dataSize

The length, in bytes, of the data for the attribute to add.

Return Value

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

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

AEPutDesc

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

OSErr AEPutDesc (
   AEDescList *theAEDescList,
   long index,
   const AEDesc *theAEDesc
);

Parameters

theAEDescList

A pointer to the descriptor list to add a descriptor to. See AEDescList.

index

A one-based positive integer indicating the position to insert the descriptor at. If there is already a descriptor in the specified position, it is replaced.

You can pass a value of zero or count + 1 to add the descriptor at the end of the list. AEPutDesc returns an error (AEIllegalIndex) if you pass a negative number or a value that is out of range.

theAEDesc

A pointer to the descriptor to add to the list. See AEDesc.

Return Value

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

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

AEPutKeyDesc

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

OSErr AEPutKeyDesc (
   AERecord *theAERecord,
   AEKeyword theAEKeyword,
   const AEDesc *theAEDesc
);

Parameters

theAERecord

A pointer to the Apple event record to add a parameter to.

theAEKeyword

The keyword specifying the parameter to add. If the Apple event record already has a parameter with this keyword, the parameter is replaced.

Some keyword constants are described in “Keyword Parameter Constants.”

See AEKeyword.

theAEDesc

A pointer to the descriptor for the parameter to add. See AEDesc.

Return Value

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

Discussion

This function is declared as a macro that invokes AEPutParamDesc, which can operate on an Apple event or an Apple event record. See the Discussion for that function for more information.

Version Notes

See AEPutParamDesc.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AEPutKeyPtr

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

OSErr AEPutKeyPtr (
   AERecord *theAERecord,
   AEKeyword theAEKeyword,
   DescType typeCode,
   const void *dataPtr,
   Size dataSize
);

Parameters

theAERecord

A pointer to the Apple event record to add a parameter to.

theAEKeyword

The keyword for the parameter to add. If the Apple event record already includes a parameter with this keyword, the parameter is replaced.

Some keyword constants are described in “Keyword Parameter Constants.”

See AEKeyword.

typeCode

The descriptor type for the parameter to add. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.

dataPtr

A pointer to the data for the parameter to add.

dataSize

The length, in bytes, of the data for the parameter to add.

Return Value

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

Discussion

This function is declared as a macro that invokes AEPutParamPtr, which can operate on an Apple event or an Apple event record. See the Discussion for that function for more information.

Version Notes

See AEPutParamPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AEPutParamDesc

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

OSErr AEPutParamDesc (
   AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   const AEDesc *theAEDesc
);

Parameters

theAppleEvent

A pointer to the Apple event to add a parameter to. See the AppleEvent data type.

theAEKeyword

The keyword specifying the parameter to add. If the Apple event already has a parameter with this keyword, the parameter is replaced.

Some keyword constants are described in “Keyword Parameter Constants.”

See AEKeyword.

theAEDesc

A pointer to the descriptor for the parameter to add. See AEDesc.

Return Value

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

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

AEPutParamPtr

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

OSErr AEPutParamPtr (
   AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType typeCode,
   const void *dataPtr,
   Size dataSize
);

Parameters

theAppleEvent

A pointer to the Apple event to add a parameter to. See the AppleEvent data type.

theAEKeyword

The keyword for the parameter to add. If the Apple event already includes an parameter with this keyword, the parameter is replaced.

Some keyword constants are described in “Keyword Parameter Constants.”

See AEKeyword.

typeCode

The descriptor type for the parameter to add. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.

dataPtr

A pointer to the data for the parameter to add.

dataSize

The length, in bytes, of the data for the parameter to add.

Return Value

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

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

AEPutPtr

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

OSErr AEPutPtr (
   AEDescList *theAEDescList,
   long index,
   DescType typeCode,
   const void *dataPtr,
   Size dataSize
);

Parameters

theAEDescList

A pointer to the descriptor list to add a descriptor to. See AEDescList.

index

A one-based positive integer indicating the position to insert the descriptor at. If there is already a descriptor in the specified position, it is replaced.

You can pass a value of zero or count + 1 to add the descriptor at the end of the list. AEPutPtr returns an error (AEIllegalIndex) if you pass a negative number or a value that is out of range.

typeCode

The descriptor type for the descriptor to be put into the list. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.

dataPtr

A pointer to the data for the descriptor to add.

dataSize

The length, in bytes, of the data for the descriptor to add.

Return Value

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

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

QTCarbonShell

Declared In

AEDataModel.h

AERemoteProcessResolverGetProcesses

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

CFArrayRef AERemoteProcessResolverGetProcesses (
   AERemoteProcessResolverRef ref,
   CFStreamError *outError
);

Parameters

ref: The AERemoteProcessResolverRef to query. Acquired from a previous call to AECreateRemoteProcessResolver.
outError: If the function result is NULL, outError contains information about the failure. See the Core Foundation Reference Documentation for a description of the CFStreamError data type.

Return Value

In the case of an error, returns NULL, in which case the outError parameter provides error information. If successful, returns a CFArrayRef of CFDictionaryRef objects containing information about the discovered remote processes. Each dictionary contains the URL of a remote application and its human readable name; it may also contain a CFNumberRef specifying a user ID for the application, if it has one; and it may also contain a CFNumberRef specifying the process ID for the process. The array is owned by the resolver, so you must retain it before disposing of the resolver object itself. For information on the keys for getting information from the dictionary, see “Remote Process Dictionary Keys.”

Discussion

You first call AECreateRemoteProcessResolver to obtain a reference to a resolver object you can use to obtain a list of processes running on a specified remote machine. See the description for that function for additional information. You then pass that reference to AERemoteProcessResolverGetProcesses to get an array of objects containing information about the discovered remote processes.

If the resolver was not previously scheduled for execution (by a call to the AERemoteProcessResolverScheduleWithRunLoop function), AERemoteProcessResolverGetProcesses will block until the resulting array is available or an error occurs. If the resolver was previously scheduled but had not yet completed fetching the array, this call will block until the resolver does complete.

Version Notes

Thread safe starting in Mac OS X v10.3.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AppleEvents.h

AERemoteProcessResolverScheduleWithRunLoop

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

void AERemoteProcessResolverScheduleWithRunLoop (
   AERemoteProcessResolverRef ref,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode,
   AERemoteProcessResolverCallback callback,
   const AERemoteProcessResolverContext *ctx
);

Parameters

ref: The AERemoteProcessResolverRef to query. Acquired from a previous call to AECreateRemoteProcessResolver.
runLoop: The run loop on which to schedule resolution of remote processes. For information on run loops, see Introduction to Run Loops. See the Core Foundation Reference Documentation for a description of the CFRunLoop data type.
runLoopMode: Specifies the run loop mode. See Input Modes for information on available modes. See the Core Foundation Reference Documentation for a description of the CFStringRef data type.
callback: A callback function to be executed when the resolver completes. See AERemoteProcessResolverCallback for information on the callback definition.
ctx: Optionally supplies information of use while resolving remote processes. If this parameter is not NULL, the info field of this structure is passed to the callback function (otherwise, the info parameter to the callback function will explicitly be NULL). See AERemoteProcessResolverContext for a description of this data type.

Discussion

Schedules a resolver for execution on a given run loop in a given mode. The resolver will move through various internal states as long as the specified run loop is run. When the resolver completes, either with success or with an error condition, the callback is executed. There is no explicit unschedule of the resolver; you must dispose of it to remove it from the run loop.

Version Notes

Thread safe starting in Mac OS X v10.3.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AppleEvents.h

AERemoveCoercionHandler

Removes a coercion handler from a coercion handler dispatch table.

OSErr AERemoveCoercionHandler (
   DescType fromType,
   DescType toType,
   AECoercionHandlerUPP handler,
   Boolean isSysHandler
);

Parameters

fromType: The descriptor type of the data coerced by the handler. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
toType: The descriptor type of the resulting data. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
handler: A universal procedure pointer to the coercion handler to remove. Although the parameters fromType and toType are sufficient to identify the handler, you can identify the handler explicitly as a safeguard. If you pass NULL for this parameter, the Apple Event Manager relies solely on the event class and event ID to identify the handler. See AECoercionHandlerUPP.
isSysHandler: Specifies the coercion table to remove the handler from. Pass TRUE to remove the handler from the system coercion table or FALSE to remove the handler from your application’s coercion table. Use of the system coercion table is not recommended.

Return Value

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

Version Notes

Thread safe starting in Mac OS X v10.2.

Use of system coercion tables is not recommended. For more information, see “Writing and Installing Coercion Handlers” in Apple Events Programming Guide.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AERemoveEventHandler

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

OSErr AERemoveEventHandler (
   AEEventClass theAEEventClass,
   AEEventID theAEEventID,
   AEEventHandlerUPP handler,
   Boolean isSysHandler
);

Parameters

theAEEventClass

The event class for the handler to remove. See AEEventClass.

theAEEventID

The event ID for the handler to remove. See AEEventID.

handler

A universal procedure pointer to the handler to remove. Although the parameters theAEEventClass and theAEEventID are sufficient to identify the handler, you can identify the handler explicitly as a safeguard. If you pass NULL for this parameter, the Apple Event Manager relies solely on the event class and event ID to identify the handler.

If you use the typeWildCard constant for either or both of the event class and event ID parameters, AERemoveEventHandler will return an error unless an entry exists that specifies typeWildCard in exactly the same way. For example, if you specify typeWildCard in both the theAEEventClass parameter and the theAEEventID parameter, AERemoveEventHandler will not remove the first handler for any event class and event ID in the dispatch table; instead, it will only remove a handler if an entry exists that specifies type typeWildCard for both the event class and the event ID.

For an explanation of wildcard values, see the Discussion section for AEInstallEventHandler.

See AEEventHandlerUPP.

isSysHandler

Specifies the Apple event dispatch table to remove the handler from. Pass TRUE to remove the handler from the system dispatch table or FALSE to remove the handler from your application’s dispatch table. See Version Notes for related information.

Return Value

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

Version Notes

Thread safe starting in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AppleEvents.h

AERemoveObjectAccessor

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

OSErr AERemoveObjectAccessor (
   DescType desiredClass,
   DescType containerType,
   OSLAccessorUPP theAccessor,
   Boolean isSysHandler
);

Parameters

desiredClass: The object class of the Apple event objects located by the object accessor function to remove. Pass the value typeWildCard to remove an object accessor function whose entry in an object accessor dispatch table specifies typeWildCard as the object class. Pass the value cProperty to remove an object accessor function whose entry in an object accessor dispatch table specifies cProperty (a constant used to specify a property of any object class). Some other possible values are defined in “Object Class ID Constants.” See DescType.
containerType: The descriptor type of the token that identifies the container for the objects located by the object accessor function to remove. (Token is defined in AEDisposeToken.) Pass the value typeWildCard to remove an object accessor function whose entry in an object accessor dispatch table specifies typeWildCard as the descriptor type of the token used to specify the container type. See DescType.
theAccessor: A universal procedure pointer to the special handler to remove. Although the functionClass parameter is sufficient to identify the handler to remove, you can identify the handler explicitly as a safeguard. If you pass NULL for this parameter, the Apple Event Manager relies solely on the function class to identify the handler. A universal procedure pointer (UPP) to the object accessor function to remove. Although the parameters desiredClass and containerType are sufficient to identify the function to remove, you can identify the function explicitly by providing a UPP in this parameter. If you pass NULL for this parameter, the Apple Event Manager relies solely on the desired class and container type. See OSLAccessorUPP.
isSysHandler: Specifies the object accessor dispatch table to remove the object accessor function from. Pass TRUE to remove the object accessor function from the system object accessor dispatch table or FALSE to remove the object accessor function from your application’s object accessor dispatch table. Use of the system object accessor dispatch table is not recommended.

Return Value

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

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

AERemoveSpecialHandler

Removes a handler from a special handler dispatch table.

OSErr AERemoveSpecialHandler (
   AEKeyword functionClass,
   AEEventHandlerUPP handler,
   Boolean isSysHandler
);

Parameters

functionClass: The keyword for the special handler to remove. Pass one of the constants described in “Special Handler Callback Constants.” See AEKeyword.
handler: A universal procedure pointer to the special handler to remove. Although the functionClass parameter is sufficient to identify the handler to remove, you can identify the handler explicitly as a safeguard. If you pass NULL for this parameter, the Apple Event Manager relies solely on the function class to identify the handler. See AEEventHandlerUPP.
isSysHandler: Specifies the special handler dispatch table to remove the handler from. Pass TRUE to remove the handler from the system special handler dispatch table or FALSE to remove the handler from your application’s special handler dispatch table. Use of the system special handler dispatch table is not recommended.

Return Value

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

Discussion

See also AEInstallSpecialHandler and AEGetSpecialHandler.

Version Notes

Thread safe starting in Mac OS X v10.2.

Your application should not install a special handler in a system dispatch table with the goal that the handler will get called when other applications receive events—this won’t work in Mac OS X.

In some previous versions of the Mac OS, applications might have reason to disable, within the application only, all Apple Event Manager functions that support Apple event objects—that is, all the functions available to an application as a result of linking the Object Support Library (OSL) and calling the AEObjectInit function.

To disable the OSL, you should pass the keyword keySelectProc in the functionClass parameter, NULL in the handler parameter, and FALSE in the isSysHandler parameter. An application that expects its copy of the OSL to move after it is installed—for example, an application that keeps it in a stand-alone code resource—would need to disable the OSL. When an application calls AEObjectInit to initialize the OSL, the OSL installs the addresses of its functions as extensions to the pack. If those functions move, the addresses become invalid.

Once you have called the AERemoveSpecialHandler function to disable the OSL, subsequent calls by your application to any of the Apple Event Manager functions that support Apple event objects will return errors. To initialize the OSL after disabling it with the AERemoveSpecialHandler function, your application must call AEObjectInit again.

If you expect to initialize the OSL and disable it several times, you should call AERemoveObjectAccessor to remove your application’s object accessor functions from your application’s object accessor dispatch table before you call AERemoveSpecialHandler.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AppleEvents.h

AEReplaceDescData

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

OSErr AEReplaceDescData (
   DescType typeCode,
   const void *dataPtr,
   Size dataSize,
   AEDesc *theAEDesc
);

Parameters

typeCode: Specifies the descriptor type of the data pointed to by dataPtr. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
dataPtr: A pointer to the data to store in the specified descriptor.
dataSize: The size, in bytes, of the data pointed to by the dataSize parameter.
theAEDesc: A pointer to a descriptor. On return, contains the copied data. See AEDesc.

Return Value

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

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

AEResetTimer

Resets the timeout value for an Apple event to its starting value.

OSErr AEResetTimer (
   const AppleEvent *reply
);

Parameters

reply: A pointer to the default reply for an Apple event, provided by the Apple Event Manager. See AppleEvent.

Return Value

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

Discussion

The AEResetTimer function resets the timeout value for an Apple event to its starting value. A server application can call this function when it knows it cannot fulfill a client application’s request (either by returning a result or by sending back a reply Apple event) before the client application is due to time out.

When your application calls AEResetTimer, the Apple Event Manager for the server application uses the default reply to send a Reset Timer event to the client application the Apple Event Manager for the client application’s computer intercepts this Apple event and resets the client application’s timer for the Apple event. (The Reset Timer event is never dispatched to a handler, so the client application does not need a handler for it.)

Version Notes

Prior to Mac OS X version 10.3, calling AEResetTimer did not reset the timeout value.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AEResolve

Resolves an object specifier.

OSErr AEResolve (
   const AEDesc *objectSpecifier,
   short callbackFlags,
   AEDesc *theToken
);

Parameters

objectSpecifier

A pointer to the object specifier to resolve. See AEDesc.

callbackFlags

A value that determines what additional assistance, if any, your application can give the Apple Event Manager when it parses the object specifier. The value is specified by adding the desired constants described in “Callback Constants for the AEResolve Function.” Most applications use kAEIDoMinimum.

theToken

A pointer to a descriptor. On return, a token that identifies the Apple event objects specified by the objectSpecifier parameter. (Token is defined in AEDisposeToken.)

Your object accessor functions may need to create many tokens to resolve a single object specifier; this parameter contains only the final token that identifies the requested Apple event object.

Whenever the AEResolve function returns final token to your event handler as the result of the resolving an object specifier passed to AEResolve, your application must deallocate the memory used by the token. If your application uses complex tokens, it must dispose of the token by calling AEDisposeToken. If your application uses simple tokens, you can use either AEDisposeToken or AEDisposeDesc. See AEDesc.

Return Value

A result code. See “Apple Event Manager Result Codes.” The AEResolve function returns any result code returned by one of your application’s object accessor functions or object callback functions. For example, an object accessor function can return errAENoSuchObject (–1728) when it can’t find an Apple event object, or it can return more specific result codes. If any object accessor function or object callback function returns a result code other than noErr or errAEEventNotHandled, AEResolve immediately disposes of any existing tokens and returns. The result code it returns in this case is the result code returned by the object accessor function or the object callback function.

Discussion

If an Apple event parameter consists of an object specifier, your handler for the event typically calls the AEResolve function to begin the process of resolving the object specifier.

The AEResolve function resolves the object specifier passed in the objectSpecifier parameter with the help of your object accessor functions, described in “Object Accessor Callbacks,” and the object callback functions, described in “Object Callback Functions.”

For information on how to receive error information from the AEResolve function, see OSLGetErrDescProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

AEResumeTheCurrentEvent

Informs the Apple Event Manager that your application wants to resume the handling of a previously suspended Apple event or that it has completed the handling of the Apple event.

OSErr AEResumeTheCurrentEvent (
   const AppleEvent *theAppleEvent,
   const AppleEvent *reply,
   AEEventHandlerUPP dispatcher,
   SRefCon handlerRefcon
);

Parameters

theAppleEvent

A pointer to the Apple event to resume handling for. See AppleEvent.

reply

A pointer to the default reply provided by the Apple Event Manager for the Apple event. See AppleEvent.

dispatcher

One of the following:

a universal procedural pointer to a function that the Apple Event Manager calls to handle the resumed event, or
the constant kAEUseStandardDispatch, which tells the Apple Event Manager to handle the resumed event with its standard dispatching mechanism, or
the constant kAENoDispatch, which tells the Apple Event Manager the Apple event has been completely processed and doesn’t need to be dispatched.

See the handlerRefcon parameter for more information.

The dispatch constants are described in “Resume Event Dispatch Constants.”

See AEEventHandlerUPP.

handlerRefcon

If the dispatcher parameter specifies a universal procedure pointer to your routine, the reference constant is passed to your handler. If you pass the value kAEUseStandardDispatch or kAENoDispatch for the dispatcher parameter, you must pass 0 for the handlerRefcon parameter.

If the value of dispatcher is kAEUseStandardDispatch, the Apple Event Manager ignores the handlerRefcon parameter and instead passes the reference constant stored in the Apple event dispatch table entry for the resumed Apple event.

If the value of dispatcher is any other value then it is a universal procedure pointer to an event handler, and the Apple Event Manager passes the value from the handlerRefcon parameter as the reference constant when it calls the handler.

Return Value

Discussion

Applications call AESuspendTheCurrentEvent to suspend handling of an Apple event and AEResumeTheCurrentEvent to resume it again. You typically call the AESuspendTheCurrentEvent function when your application needs to do some lengthy processing before responding to the event.

When your application calls the AEResumeTheCurrentEvent function, the Apple Event Manager resumes handling the specified Apple event using the handler specified in the dispatcher parameter, if any. If kAENoDispatch is specified in the dispatcher parameter, AEResumeTheCurrentEvent simply informs the Apple Event Manager that the specified event has been handled.

Special Considerations

This function is not thread-safe and, along with AESuspendTheCurrentEvent, should be called only on the main thread.

When your application suspends an Apple event, it does not need to dispose of the Apple event or the reply Apple event passed to the handler that suspends the event, whether or not the application eventually resumes the event. However, if the application will later resume the event, the handler that suspends the event should save a copy of the underlying data storage for the Apple event and the reply event. When resuming the event, you pass those copies to AEResumeTheCurrentEvent, which uses the information they contain to identify the original event and reply. For related information, see AESuspendTheCurrentEvent.

Make sure all processing involving the event or the reply has been completed before your application calls AEResumeTheCurrentEvent. Do not call AEResumeTheCurrentEvent for an event that was not suspended.

An Apple event handler that suspends an event should not immediately call AEResumeTheCurrentEvent, because the handler will generate an error. Instead, the handler should just return after suspending the event.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AESend

Sends the specified Apple event.

OSErr AESend (
   const AppleEvent *theAppleEvent,
   AppleEvent *reply,
   AESendMode sendMode,
   AESendPriority sendPriority,
   SInt32 timeOutInTicks,
   AEIdleUPP idleProc,
   AEFilterUPP filterProc
);

Parameters

theAppleEvent

A pointer to the Apple event to send. See AppleEvent.

reply

A pointer to a reply Apple event. On return, contains the reply Apple event from the server application, if you specified the kAEWaitReply flag in the sendMode parameter. If you specify the kAEQueueReply flag in the sendMode parameter, you receive the reply Apple event in your event queue. If you specify kAENoReply flag, the reply Apple event is a null descriptor (one with descriptor type typeNull). If you specify kAEWaitReply in the sendMode parameter, and if the function returns successfully (see function result below), your application is responsible for using the AEDisposeDesc function to dispose of the descriptor returned in the reply parameter.

sendMode

Specifies various options for how the server application should handle the Apple event. To obtain a value for this parameter, you add together constants to set bits that specify the reply mode, the interaction level, the application switch mode, the reconnection mode, and the return receipt mode. For more information, see “AESendMode”.

sendPriority

See the Version Notes section below for important information. A value that specifies the priority for processing the Apple event. You can specify normal or high priority, using the constants described in “AESendMode”. See AESendPriority.

timeOutInTicks

If the reply mode specified in the sendMode parameter is kAEWaitReply, or if a return receipt is requested, this parameter specifies the length of time (in ticks) that the client application is willing to wait for the reply or return receipt from the server application before timing out. Most applications should use the kAEDefaultTimeout constant, which tells the Apple Event Manager to provide an appropriate timeout duration. If the value of this parameter is kNoTimeOut, the Apple event never times out. These constants are described in “Timeout Constants.”

idleProc

A universal procedure pointer to a function that handles events (such as update, operating-system, activate, and null events) that your application receives while waiting for a reply. Your idle function can also perform other tasks (such as displaying a wristwatch or spinning beach ball cursor) while waiting for a reply or a return receipt.

If your application specifies the kAEWaitReply flag in the sendMode parameter and you wish your application to get periodic time while waiting for the reply to return, you must provide an idle function. Otherwise, you can pass a value of NULL for this parameter. For more information on the idle function, see AEIdleProcPtr.

filterProc

A universal procedure pointer to a function that determines which incoming Apple events should be received while the handler waits for a reply or a return receipt. If your application doesn’t need to filter Apple events, you can pass a value of NULL for this parameter. If you do so, no application-oriented Apple events are processed while waiting. For more information on the filter function, see AEFilterProcPtr.

Return Value

A result code. See “Apple Event Manager Result Codes.” The AESend function returns noErr if the Event Manager successfully sends the Apple event—this value does not indicate that the Apple event was handled successfully. If the handler returns a result code other than noErr, and if the client is waiting for a reply, AESend returns the result code in the keyErrorNumber parameter of the reply Apple event. For a result code other than noErr, you should not call the AEDisposeDesc function to dispose of the descriptor returned in the reply parameter, because the descriptor is invalid.

Discussion

You typically create an Apple event to send with the AECreateAppleEvent function and add information to it with the functions described in “Adding Parameters and Attributes to Apple Events and Apple Event Records.”

If the Apple Event Manager cannot find a handler for the Apple event in the server application’s dispatch table or in the system dispatch table, it returns the result code errAEEventNotHandled to the server application (as the result of the AEProcessAppleEvent function). If the client application is waiting for a reply, the Apple Event Manager also returns this result code to the client in the keyErrorNumber parameter of the reply event.

In addition to specifying the wait duration for replies, the timeOutInTicks parameter is used as a wait value when queuing events for other applications. The Apple Event Manager waits for the specified duration as it attempts to queue the event. If you specify kAEWaitReply and the target application quits or crashes after the event is queued but before the reply is returned, the Apple Event Manager returns a sessionClosedErr result code.

In some situations, there are advantages to sending Apple events with the AESendMessage function. That function requires less overhead than AESend and it allows you to send Apple events without linking to the entire Carbon framework (and window server), as required by AESend. For more information on sending Apple events, see “Sending an Apple Event” in Apple Events Programming Guide.

Version Notes

In Mac OS 9 and earlier, you use the sendMode parameter to specify how the server should handle the Apple event. “AESendMode” provides a complete description of the constants you use with this parameter. The sendPriority parameter is deprecated in Mac OS X and later.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AESendMessage

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

OSStatus AESendMessage (
   const AppleEvent *event,
   AppleEvent *reply,
   AESendMode sendMode,
   long timeOutInTicks
);

Parameters

event: A pointer to the Apple event to send.
reply: A pointer to a reply Apple event. On return, contains the reply Apple event from the server application, if you specified the kAEWaitReply flag in the sendMode parameter. If you specify the kAEQueueReply flag in the sendMode parameter, you receive the reply Apple event in your event queue. If you specify kAENoReply flag, the reply Apple event is a null descriptor (one with descriptor type typeNull). If you specify kAEWaitReply in the sendMode parameter, and if the function returns successfully (see function result below), your application is responsible for using the AEDisposeDesc function to dispose of the descriptor returned in the reply parameter.
sendMode: Specifies various options for how the server application should handle the Apple event. To obtain a value for this parameter, you add together constants to set bits that specify the reply mode, the interaction level, the application switch mode, the reconnection mode, and the return receipt mode. For more information, see “AESendMode”.
timeOutInTicks: If the reply mode specified in the sendMode parameter is kAEWaitReply, or if a return receipt is requested, this parameter specifies the length of time (in ticks) that the client application is willing to wait for the reply or return receipt from the server application before timing out. Most applications should use the kAEDefaultTimeout constant, which tells the Apple Event Manager to provide an appropriate timeout duration. If the value of this parameter is kNoTimeOut, the Apple event never times out. These constants are described in “Timeout Constants.”

Return Value

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

Discussion

The AESendMessage function allows you to send Apple events without linking to the entire Carbon framework, as required by AESend. Linking with Carbon brings in the HIToolbox framework, which requires that your application have a connection to the window server. Daemons and other applications that have no interface but wish to send and receive Apple events can use the following functions for working with Apple events at a lower level: AESendMessage, AEGetRegisteredMachPort, AEDecodeMessage, and AEProcessMessage. See the descriptions for those functions for more information on when you might use them.

If the target of an event sent with AESendMessage is the current process (as specified by using typeProcessSerialNumber of { 0, kCurrentProcess } in the Apple event being sent), the Apple event is dispatched directly to the appropriate event handler in your process and not serialized.

Special Considerations

The AESendMessage function is both asynchronous and thread-safe, so you could, for example, set up a thread to send an Apple event and wait for a reply. If you use threads, you must add a typeReplyPortAttr attribute to your event that identifies the Mach port on which to receive the reply.

However, due to a bug that was present prior to Mac OS X version 10.5, you could not safely dispose of a Mach port you created to use as the reply port. Disposing of the port could, rarely, lead to a crash, while failing to dispose of if leaked resources. The sample code project AESendThreadSafe shows how to safely work around the bug in earlier Mac OS versions.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEMach.h

AESetInteractionAllowed

Specifies user interaction preferences for responding to an Apple event when your application is the server application.

OSErr AESetInteractionAllowed (
   AEInteractAllowed level
);

Parameters

level: The desired user interaction level. Pass one of the values described in “User Interaction Level Constants.”

Return Value

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

Discussion

If you don’t set the user interaction level by calling AESetInteractionAllowed, the default level is kAEInteractWithLocal (which indicates that your server application may interact with the user in response to an Apple event only if the client application is on the same computer as the server application).

For additional information on interaction level, see AESend and “AESendMode”.

See also AESetInteractionAllowed and AEInteractWithUser.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AESetObjectCallbacks

Specifies the object callback functions for your application.

OSErr AESetObjectCallbacks (
   OSLCompareUPP myCompareProc,
   OSLCountUPP myCountProc,
   OSLDisposeTokenUPP myDisposeTokenProc,
   OSLGetMarkTokenUPP myGetMarkTokenProc,
   OSLMarkUPP myMarkProc,
   OSLAdjustMarksUPP myAdjustMarksProc,
   OSLGetErrDescUPP myGetErrDescProcPtr
);

Parameters

myCompareProc: Either a universal procedure pointer to the object comparison function provided by your application or NULL if no function is provided. See OSLCompareUPP.
myCountProc: Either a universal procedure pointer to the object-counting function provided by your application or NULL if no function is provided. See OSLCountUPP.
myDisposeTokenProc: Either a universal procedure pointer to the token disposal function provided by your application or NULL if no function is provided. (Token is defined in AEDisposeToken. See OSLDisposeTokenUPP.
myGetMarkTokenProc: Either a universal procedure pointer to the function for returning a mark token provided by your application or NULL if no function is provided. See OSLGetMarkTokenUPP.
myMarkProc: Either a universal procedure pointer to the object-marking function provided by your application or NULL if no function is provided. See OSLMarkUPP.
myAdjustMarksProc: Either a universal procedure pointer to the mark-adjusting function provided by your application or NULL if no function is provided. See OSLAdjustMarksUPP.
myGetErrDescProcPtr: Either a universal procedure pointer to the error callback function provided by your application or NULL if no function is provided. See OSLGetErrDescUPP.

Return Value

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

Discussion

This function is just a convenient wrapper for AEInstallSpecialHandler. You can manipulate the special handler table with more control using the routines described in “Managing Special Handler Dispatch Tables.”

Your application can provide only one each of the object callback functions specified by AESetObjectCallbacks—one object comparison function, one object-counting function, and so on. As a result, each of these callback functions must perform the requested task (comparing, counting, and so on) for all the object classes that your application supports. In contrast, your application may provide many different object accessor functions if necessary, depending on the object classes and token types your application supports. You install object accessor functions with AEInstallObjectAccessor.

To replace object callback functions that have been previously installed, you can call AESetObjectCallbacks again. Each additional call to AESetObjectCallbacks replaces any object callback functions installed by previous calls. Only those functions you specify are replaced; to avoid replacing existing callback functions, specify a value of NULL for the functions you don’t want to replace.

You cannot use AESetObjectCallbacks to replace system object callback functions or object accessor functions. To install system object callback functions, use the function AEInstallSpecialHandler.

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

AESetTheCurrentEvent

Specifies a current Apple event to take the place of the one your application has suspended.

OSErr AESetTheCurrentEvent (
   const AppleEvent *theAppleEvent
);

Parameters

theAppleEvent: A pointer to the Apple event to handle as the current event. See AppleEvent.

Return Value

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

Discussion

There is usually no reason for your application to use the AESetTheCurrentEvent function. Instead of calling this function, your application should let the Apple Event Manager set the current Apple event through its standard dispatch mechanism.

If you need to avoid the dispatch mechanism, you must use the AESetTheCurrentEvent function only in the following way:

Your application suspends handling of an Apple event by calling the AESuspendTheCurrentEvent function.
Your application calls the AESetTheCurrentEvent function. This informs the Apple Event Manager that your application is handling the suspended Apple event. In this way, any functions that call the AEGetTheCurrentEvent function can ascertain which event is currently being handled.
When your application finishes handling the Apple event, it calls the AEResumeTheCurrentEvent function with the value kAENoDispatch to tell the Apple Event Manager that the event has been processed and need not be dispatched.

Special Considerations

This function is not thread-safe and should only be called on the main thread.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AESizeOfAttribute

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

OSErr AESizeOfAttribute (
   const AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType *typeCode,
   Size *dataSize
);

Parameters

theAppleEvent: A pointer to the Apple event to get the attribute data from. See AppleEvent.
theAEKeyword: The keyword that specifies the attribute. Some keyword constants are described in “Keyword Attribute Constants.” See AEKeyword.
typeCode: A pointer to a descriptor type. On return, specifies the descriptor type of the attribute. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” Can be NULL. See DescType.
dataSize: A pointer to a size variable. On return, the length, in bytes, of the data in the attribute. Can be NULL.

Return Value

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

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

AESizeOfFlattenedDesc

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

Size AESizeOfFlattenedDesc (
   const AEDesc *theAEDesc
);

Parameters

theAEDesc: A pointer to the descriptor to be flattened. See AEDesc.

Return Value

The size, in bytes, required to store the flattened descriptor.

Discussion

You call this function before calling AEFlattenDesc to determine the required size of the buffer for the flatten operation.

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

AESizeOfKeyDesc

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

OSErr AESizeOfKeyDesc (
   const AppleEvent *theAERecord,
   AEKeyword theAEKeyword,
   DescType *typeCode,
   Size *dataSize
);

Parameters

theAERecord: A pointer to the Apple event record to get the parameter data from.
theAEKeyword: The keyword that specifies the desired parameter. Some keyword parameter constants are described in “Keyword Parameter Constants.” See AEKeyword.
typeCode: A pointer to a descriptor type. On return, specifies the descriptor type of the Apple event parameter. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
dataSize: A pointer to a size variable. On return, the length, in bytes, of the data in the Apple event parameter.

Return Value

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

Discussion

This function is declared as a macro that invokes AESizeOfParam, which can operate on an Apple event or an Apple event record. See the Discussion for that function for more information.

Version Notes

See AESizeOfParam.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

AESizeOfNthItem

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

OSErr AESizeOfNthItem (
   const AEDescList *theAEDescList,
   long index,
   DescType *typeCode,
   Size *dataSize
);

Parameters

theAEDescList: A pointer to the descriptor list containing the descriptor. See AEDescList.
index: A one-based positive integer indicating the position of the descriptor to get the data size for. AESizeOfNthItem returns an error if you pass zero, a negative number, or a value that is out of range.
typeCode: A pointer to a descriptor type. On return, specifies the descriptor type of the descriptor. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
dataSize: A pointer to a size variable. On return, the length (in bytes) of the data in the descriptor.

Return Value

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

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

AESizeOfParam

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

OSErr AESizeOfParam (
   const AppleEvent *theAppleEvent,
   AEKeyword theAEKeyword,
   DescType *typeCode,
   Size *dataSize
);

Parameters

theAppleEvent: A pointer to the Apple event to get the parameter data from. See AppleEvent.
theAEKeyword: The keyword that specifies the desired parameter. Some keyword parameter constants are described in “Keyword Parameter Constants.” See AEKeyword.
typeCode: A pointer to a descriptor type. On return, specifies the descriptor type of the Apple event parameter. For a list of AppleScript’s predefined descriptor types, see “Descriptor Type Constants.” See DescType.
dataSize: A pointer to a size variable. On return, the length, in bytes, of the data in the Apple event parameter.

Return Value

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

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

AEStreamClose

Closes and deallocates an AEStreamRef.

OSStatus AEStreamClose (
   AEStreamRef ref,
   AEDesc *desc
);

Parameters

ref: An AEStreamRefcontaining the stream data.
desc: A pointer to a descriptor for receiving a the stream data, or NULL if you want to discard the data. See AEDesc.

Return Value

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

Discussion

Use this function to dispose of an AEStreamRef you created using AEStreamCreateEvent, AEStreamOpen, or AEStreamOpenEvent. To retrieve the resulting descriptor from the stream prior to disposal, pass in a pointer to an AEDesc structure in the desc parameter. If this parameter exists, AEStreamClose fills in the descriptor with the stream data. If the stream contains invalid information, possibly due to improperly balanced calls to “AEStream” functions, the returned descriptor type is set to typeNull.

Regardless of any errors returned by this function, it is always safe to call AEDisposeDesc on the returned descriptor.

Specifying NULL for the desc parameter causes AEStreamClose to discard the stream data and dispose of the AEStreamRef. When you call AEStreamClose in this way, you do not need to worry about balancing nested calls to “AEStream” functions. This technique is particularly useful during error-handling situations where you need to dispose of a stream but do not know its exact state.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamCloseDesc

Marks the end of a descriptor in an AEStreamRef.

OSStatus AEStreamCloseDesc (
   AEStreamRef ref
);

Parameters

ref: An AEStreamRefcontaining the stream data.

Return Value

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

Discussion

Call this function to balance a preceding call to AEStreamOpenDesc or AEStreamOpenKeyDesc. This function completes the definition of the AEDesc.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamCloseList

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

OSStatus AEStreamCloseList (
   AEStreamRef ref
);

Parameters

ref: An AEStreamRefcontaining the stream data.

Return Value

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

Discussion

Call this function to balance a preceding call to AEStreamOpenList. This function completes the definition of the AEDescList.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamCloseRecord

Marks the end of a record in an AEStreamRef.

OSStatus AEStreamCloseRecord (
   AEStreamRef ref
);

Parameters

ref: An AEStreamRefcontaining the stream data.

Return Value

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

Discussion

Call this function to balance a preceding call to AEStreamOpenRecord. This function completes the definition of the Apple event record.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamCreateEvent

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

AEStreamRef AEStreamCreateEvent (
   AEEventClass clazz,
   AEEventID id,
   DescType targetType,
   const void *targetData,
   Size targetLength,
   SInt16 returnID,
   SInt32 transactionID
);

Parameters

clazz: The event class of the Apple event. See AEEventClass.
id: The event ID of the Apple event. See AEEventID.
targetType: The address type for the addressing information in the next two parameters. Usually contains one of the following values: typeApplSignature. typeKernelProcessID, or typeProcessSerialNumber. See DescType.
targetData: A pointer to the address information. The data in this pointer must match the data associated with the specified targetType.
targetLength: The number of bytes pointed to by the targetData 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. The return ID constant is described in “ID Constants for the AECreateAppleEvent Function.” See AEReturnID.
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. This transaction ID constant is described in “ID Constants for the AECreateAppleEvent Function.” See AETransactionID.

Return Value

An AEStreamRef associated with the new event.

Discussion

This routine effectively combines a call to AECreateAppleEvent followed by a call to AEStreamOpenEvent to create a new Apple event in the stream. You can use the returned AEStreamRef to add parameters to the new Apple event.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOpen

Opens a new AEStreamRef for use in building a descriptor.

AEStreamRef AEStreamOpen (
   void
);

Return Value

A new AEStreamRef or NULL if the stream data structures cannot be allocated.

Discussion

This function creates a new stream for use in describing the contents of a descriptor, descriptor list, or Apple event record (AEDesc, AEDescList, or AERecord).

You can use the returned AEStreamRef with other “AEStream” routines to build the contents of a descriptor. When you are done building the descriptor, use AEStreamClose to close the stream.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOpenDesc

Marks the beginning of a descriptor in an AEStreamRef.

OSStatus AEStreamOpenDesc (
   AEStreamRef ref,
   DescType newType
);

Parameters

ref: An AEStreamRef containing the stream data.
newType: A type code for the new AEDesc being added to the stream. See DescType.

Return Value

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

Discussion

Use this routine to mark the beginning of a descriptor definition in an AEDesc. After calling this routine, you should call AEStreamWriteData one or more times to write the descriptor data to the stream. When you are done writing data, you must call AEStreamCloseDesc to complete the descriptor definition.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOpenEvent

Opens a stream for an existing Apple event.

AEStreamRef AEStreamOpenEvent (
   AppleEvent *event
);

Parameters

event: An existing Apple event. See AppleEvent.

Return Value

An AEStreamRef for the Apple event or NULL if the stream data structures could not be allocated.

Discussion

Use this function to open a stream and add parameters to an existing Apple event. This function copies any parameters already in the Apple event to the stream prior to returning the AEStreamRef. When you are done adding parameters, use AEStreamClose to save them to the Apple event and close the stream.

If there is not enough available storage to complete the operation, AEStreamOpenEvent returns NULL and leaves the Apple event unchanged.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOpenKeyDesc

Marks the beginning of a key descriptor in an AEStreamRef.

OSStatus AEStreamOpenKeyDesc (
   AEStreamRef ref,
   AEKeyword key,
   DescType newType
);

Parameters

ref: An AEStreamRef containing the stream data.
key: The AEKeyword associated with the new descriptor being added to the stream. See AEKeyword.
newType: A type code for the new AEDesc being added to the stream. See DescType.

Return Value

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

Discussion

Use this routine to mark the beginning of a keyword/descriptor definition in an Apple event record. After calling this routine, you should call AEStreamWriteData one or more times to write the record data to the stream. When you are done writing data, you must call AEStreamCloseDesc to complete the record definition.

This routine must be called only as part of an Apple event record definition. You cannot use this routine to write keyword/descriptor definitions to other descriptor types, such as an AEDesc or AEDescList, even if those types are nested inside an Apple event record. In situations where you need to create nested records, this routine opens a new keyword/descriptor definition in the Apple event record associated with the most recent call to AEStreamOpenRecord.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOpenList

Marks the beginning of a descriptor list in an AEStreamRef.

OSStatus AEStreamOpenList (
   AEStreamRef ref
);

Parameters

ref: An AEStreamRef containing the stream data.

Return Value

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

Discussion

This routine marks the beginning of a sequence of zero or more descriptor definitions that you use to build an AEDescList structure. After calling this routine, you can write any number of AEDesc, AEDescList, or AERecord structures to the stream as elements of the list. When you are done, you must call AEStreamCloseList to complete the AEDescList definition.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOpenRecord

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

OSStatus AEStreamOpenRecord (
   AEStreamRef ref,
   DescType newType
);

Parameters

ref: An AEStreamRef containing the stream data.
newType: A type code for the new record you are adding to the stream. This value can be typeAERecord or any other appropriate value. See DescType.

Return Value

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

Discussion

This routine marks the beginning of a sequence of zero or more keyword/descriptor definitions that you use to build an AERecord structure. You must balance each call to this method with a corresponding call to AEStreamCloseRecord.

For information on adding keyword/descriptor data to the record, see the AEStreamOpenKeyDesc, AEStreamWriteKey, and AEStreamWriteKeyDesc routines.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamOptionalParam

Designates a parameter in an Apple event as optional.

OSStatus AEStreamOptionalParam (
   AEStreamRef ref,
   AEKeyword key
);

Parameters

ref: An AEStreamRef containing the stream data.
key: The AEKeyword associated with any keyword/descriptor pair in an Apple event. See AEKeyword.

Return Value

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

Discussion

Calls to this routine must be preceded by a call to either AEStreamCreateEvent or AEStreamOpenEvent.

The descriptor associated with the specified key does not need to exist before you call this routine.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamSetRecordType

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

OSStatus AEStreamSetRecordType (
   AEStreamRef ref,
   DescType newType
);

Parameters

ref: An AEStreamRef containing the stream data.
newType: The new type code for the AERecord being added to the stream. See DescType.

Return Value

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

Discussion

Use this routine to change the type of a record after it has been opened. You must call this routine between calls to AEStreamOpenRecord and AEStreamCloseRecord. The type you specify in the newType parameter replaces the previous type specified by AEStreamOpenRecord.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamWriteAEDesc

Copies an existing descriptor into an AEStreamRef.

OSStatus AEStreamWriteAEDesc (
   AEStreamRef ref,
   const AEDesc *desc
);

Parameters

ref: An AEStreamRef containing the stream data.
desc: A pointer to the descriptor you want to copy into the stream. See AEDesc.

Return Value

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

Discussion

You can use this routine to incorporate an existing descriptor into the stream. For example, you could use this routine if you had a complex descriptor you wanted to add to multiple streams, but which would be costly to create each time.

Do not use AEStreamOpenDesc and AEStreamCloseDesc with this routine to open and close the descriptor.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamWriteData

Appends data to the current descriptor in an AEStreamRef.

OSStatus AEStreamWriteData (
   AEStreamRef ref,
   const void *data,
   Size length
);

Parameters

ref: An AEStreamRef containing the stream data.
data: A pointer to the block of memory containing the descriptor data. This routine copies the memory block immediately, so you do not need to retain it for the benefit of this routine.
length: The number of bytes pointed to by the data parameter.

Return Value

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

Discussion

You can call this routine any number of times to build up the data contents of the descriptor incrementally. You must precede calls to this routine by a call to either AEStreamOpenDesc or AEStreamOpenKeyDesc. When you are done adding data to the descriptor, call AEStreamCloseDesc to complete the descriptor definition.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamWriteDesc

Appends the data for a complete descriptor to an AEStreamRef.

OSStatus AEStreamWriteDesc (
   AEStreamRef ref,
   DescType newType,
   const void *data,
   Size length
);

Parameters

ref: An AEStreamRef containing the stream data.
newType: A type code for the new AEDesc being added to the stream. See DescType.
data: A pointer to the block of memory containing the descriptor data. This routine copies the memory block immediately, so you do not need to retain it for the benefit of this routine.
length: The number of bytes pointed to by the data parameter.

Return Value

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

Discussion

Use this routine to write the data for a descriptor to the stream. When using this routine, you must supply all of the descriptor data at once.

Do not use AEStreamOpenDesc and AEStreamCloseDesc with this routine to open and close the descriptor.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamWriteKey

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

OSStatus AEStreamWriteKey (
   AEStreamRef ref,
   AEKeyword key
);

Parameters

ref: An AEStreamRef containing the stream data.
key: The AEKeyword associated with the new descriptor being added to the stream. See AEKeyword.

Return Value

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

Discussion

You must follow this call with a sequence of “AEStream” calls to specify exactly one descriptor that goes with the keyword. The descriptor you create can be of type AEDesc, AEDescList, or AERecord.

If you are creating nested descriptors, this routine begins a new keyword/descriptor pair for the descriptor most recently opened by a call to AEStreamWriteKey or AEStreamOpenEvent. You cannot use this routine to write parameters to any other types of descriptors, even if they are nested inside of an AERecord.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AEStreamWriteKeyDesc

Writes a complete keyword/descriptor pair to an AEStreamRef.

OSStatus AEStreamWriteKeyDesc (
   AEStreamRef ref,
   AEKeyword key,
   DescType newType,
   const void *data,
   Size length
);

Parameters

ref: An AEStreamRef containing the stream data.
key: The AEKeyword associated with the new descriptor being added to the stream. See AEKeyword.
newType: A type code for the new AEDesc being added to the stream. See DescType.
data: A pointer to the block of memory containing the descriptor data. This routine copies the memory block immediately, so you do not need to retain it for the benefit of this routine.
length: The number of bytes pointed to by the data parameter.

Return Value

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

Discussion

Use this routine to add a descriptor to the currently open AERecord inside a stream. You cannot use this routine to write parameters to any other types of descriptors, even if they are nested inside of an AERecord. This routine can only be called in between calls to AEStreamOpenRecord and AEStreamCloseRecord.

This method is analogous to the Apple Event Manager routine AEPutParamPtr, except it is for use with streams.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

AESuspendTheCurrentEvent

Suspends the processing of the Apple event that is currently being handled.

OSErr AESuspendTheCurrentEvent (
   const AppleEvent *theAppleEvent
);

Parameters

theAppleEvent: A pointer to the Apple event to suspend handling for. If the pointed-to Apple event is not the current event, AESuspendTheCurrentEvent does nothing and returns noErr. See AppleEvent.

Return Value

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

Discussion

You typically call the AESuspendTheCurrentEvent function from an Apple event handler function, such as when your application needs to do some lengthy processing before responding to the event. After a successful call to this function, you are not required to return a result or a reply for the Apple event that was being handled. You can, however, return a result if you later call the AEResumeTheCurrentEvent function to resume event processing.

Whether you will resume the suspended Apple event or not, you do not need to dispose of the Apple event or the reply Apple event passed to your handler. However, if your handler will later resume the event, you must save a copy of the underlying data storage for the Apple event and the reply event. When resuming the event, you pass those copies to AEResumeTheCurrentEvent, which uses the information they contain to identify the original event and reply.

You cannot merely save the pointers that are passed to your handler because they do not persist after your handler returns (although the underlying Apple events do persist). Use a function such as AEDuplicateDesc to obtain copies of the Apple event and reply event. Later, after calling AEResumeTheCurrentEvent to resume the event, call AEDisposeDesc to dispose of the copies.

Special Considerations

This function is not thread-safe and, along with AEResumeTheCurrentEvent, should be called only on the main thread.

If your application suspends handling of an Apple event it sends to itself, the Apple Event Manager immediately returns from the AESend call with the error code errAETimeout, regardless of the parameters specified in the call to AESend. The function calling AESend should take the timeout error as confirmation that the event was sent.

As with other calls to AESend that return a timeout error, the handler continues to process the event nevertheless. The handler’s reply, if any, is provided in the reply event when the handling is completed. The Apple Event Manager provides no notification that the reply is ready. If no data has yet been placed in the reply event, the Apple Event Manager returns errAEReplyNotArrived when your application attempts to extract data from the reply.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

AEUnflattenDesc

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

OSStatus AEUnflattenDesc (
   const void *buffer,
   AEDesc *result
);

Parameters

buffer: A pointer to memory, allocated by the application, that contains flattened data produced by a previous call to AEFlattenDesc.
result: A null descriptor. On successful completion, points to a descriptor created from the flattened data. The caller is responsible for disposing of the descriptor.

Return Value

A result code. Returns paramErr if the flattened data in buffer is found to be invalid. See “Apple Event Manager Result Codes” for other possible values.

Discussion

This function assumes the passed buffer contains valid flattened data, produced by a previous call to AEFlattenDesc. See that function for a description of when you might want to flatten and unflatten descriptors, and of possible limitations.

Flattening and unflattening works across OS versions, including between Mac OS 9 and Mac OS X.

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

CreateCompDescriptor

Creates a comparison descriptor that specifies how to compare one or more Apple event objects with either another Apple event object or a descriptor.

OSErr CreateCompDescriptor (
   DescType comparisonOperator,
   AEDesc *operand1,
   AEDesc *operand2,
   Boolean disposeInputs,
   AEDesc *theDescriptor
);

Parameters

comparisonOperator

The comparison operator for comparing the descriptors in the operand1 and operand2 parameters. The standard comparison operators are defined in “Comparison Operator Constants.”

The actual comparison of the two operands is performed by the object comparison function provided by the client application. The way a comparison operator is interpreted is up to each application.

See DescType.

operand1

A pointer to an object specifier. See AEDesc.

operand2

A pointer to a descriptor (which can be an object specifier or any other descriptor) whose value is compared to the value of operand1. See AEDesc.

disposeInputs

A Boolean value. Pass TRUE if the function should automatically dispose of any descriptors you have provided in the operand1 and operand2 parameters to the function. Pass FALSE if your application will dispose of the descriptors itself. A value of FALSE may be more efficient for some applications because it allows them to reuse descriptors.

theDescriptor

A pointer to a descriptor. On successful return, the comparison descriptor created by CreateCompDescriptor. Your application must dispose of this descriptor after it has finished using it. See AEDesc.

Return Value

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEPackObject.h

CreateLogicalDescriptor

Creates a logical descriptor that specifies a logical operator and one or more logical terms for the Apple Event Manager to evaluate.

OSErr CreateLogicalDescriptor (
   AEDescList *theLogicalTerms,
   DescType theLogicOperator,
   Boolean disposeInputs,
   AEDesc *theDescriptor
);

Parameters

theLogicalTerms: A pointer to a list containing comparison descriptors (typeLogicalDescriptor), logical descriptors (typeCompDescriptor), or both. If the value of the parameter theLogicOperator is kAEAND or kAEOR, the list can contain any number of descriptors. If the value of the parameter theLogicOperator is kAENOT, logically this list should contain a single descriptor. However, the function will not return an error if the list contains more than one descriptor for a logical operator of kAENOT. See AEDescList.
theLogicOperator: A logical operator represented by one of the constants described in “Constants for Object Specifiers, Positions, and Logical and Comparison Operations.” What you pass for this parameter helps determine what you pass for the theLogicalTerms parameter. See DescType.
disposeInputs: A Boolean value. Pass TRUE if the function should automatically dispose of the descriptors you have provided in the theLogicalTerms parameter or (FALSE) if your application will. A value of FALSE may be more efficient for some applications because it allows them to reuse descriptors.
theDescriptor: A pointer to a descriptor. On successful return, the logical descriptor created by CreateLogicalDescriptor. Your application must dispose of this descriptor after it has finished using it. See AEDesc.

Return Value

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

Discussion

The CreateLogicalDescriptor function creates a logical descriptor, which specifies a logical operator and one or more logical terms for the Apple Event Manager to evaluate.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEPackObject.h

CreateObjSpecifier

Assembles an object specifier that identifies one or more Apple event objects, from other descriptors.

OSErr CreateObjSpecifier (
   DescType desiredClass,
   AEDesc *theContainer,
   DescType keyForm,
   AEDesc *keyData,
   Boolean disposeInputs,
   AEDesc *objSpecifier
);

Parameters

desiredClass: The object class of the desired Apple event objects. See DescType.
theContainer: A pointer to a descriptor that describes the container for the requested object, usually in the form of another object specifier. See AEDesc.
keyForm: The key form for the object specifier.
keyData: A pointer to a descriptor that supplies the key data for the object specifier.
disposeInputs: A Boolean value. Pass (TRUE) if the function should dispose of the descriptors for the theContainer and keyData parameters or (FALSE) if your application will. A value of FALSE may be more efficient for some applications because it allows them to reuse descriptors.
objSpecifier: On successful return, a pointer to the object specifier created by the CreateObjSpecifier function. If the function returns successfully, your application should call the AEDisposeDesc function to dispose of this descriptor after it has finished using it.

Return Value

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEPackObject.h

CreateOffsetDescriptor

Creates an offset descriptor that specifies the position of an element in relation to the beginning or end of its container.

OSErr CreateOffsetDescriptor (
   long theOffset,
   AEDesc *theDescriptor
);

Parameters

theOffset: A positive integer that specifies the offset from the beginning of the container (the first element has an offset of 1), or a negative integer that specifies the offset from the end (the last element has an offset of –1).
theDescriptor: A pointer to a descriptor. On successful return, the offset descriptor created by CreateOffsetDescriptor. On error, returns a null descriptor. Your application must dispose of the descriptor after it has finished using it. See AEDesc.

Return Value

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEPackObject.h

CreateRangeDescriptor

Creates a range descriptor that specifies a series of consecutive elements in the same container.

OSErr CreateRangeDescriptor (
   AEDesc *rangeStart,
   AEDesc *rangeStop,
   Boolean disposeInputs,
   AEDesc *theDescriptor
);

Parameters

rangeStart: A pointer to an object specifier that identifies the first Apple event object in the range. See AEDesc.
rangeStop: A pointer to an object specifier that identifies the last Apple event object in the range. See AEDesc.
disposeInputs: A Boolean value. Pass (TRUE) if the function should dispose of the descriptors for the rangeStart and rangeStop parameters and set them to the null descriptor or (FALSE) if your application will. A value of FALSE may be more efficient for some applications because it allows them to reuse descriptors.
theDescriptor: A pointer to a descriptor. On successful return, the range descriptor created by CreateRangeDescriptor. Your application must dispose of this descriptor after it has finished using it. See AEDesc.

Return Value

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

Discussion

Although the rangeStart and rangeStop parameters can be any object specifiers—including object specifiers that specify more than one Apple event object—most applications expect these parameters to specify single Apple event objects.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEPackObject.h

DisposeAECoerceDescUPP

Disposes of a universal procedure pointer to a function that coerces data stored in a descriptor.

void DisposeAECoerceDescUPP (
   AECoerceDescUPP userUPP
);

Discussion

See the AECoerceDescProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

DisposeAECoercePtrUPP

Disposes of a universal procedure pointer to a function that coerces data stored in a buffer.

void DisposeAECoercePtrUPP (
   AECoercePtrUPP userUPP
);

Discussion

See the AECoercePtrProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

DisposeAEDisposeExternalUPP

Disposes of a universal procedure pointer to a function that disposes of data supplied to the AECreateDescFromExternalPtr function.

void DisposeAEDisposeExternalUPP (
   AEDisposeExternalUPP userUPP
);

Parameters

userUPP: The universal procedure pointer to be disposed of. See AEDisposeExternalUPP.

Discussion

See the AECreateDescFromExternalPtr function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AEDataModel.h

DisposeAEEventHandlerUPP

Disposes of a universal procedure pointer to an event handler function.

void DisposeAEEventHandlerUPP (
   AEEventHandlerUPP userUPP
);

Discussion

See the AEEventHandlerProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

DisposeAEFilterUPP

Disposes of a universal procedure pointer to an Apple event filter function.

void DisposeAEFilterUPP (
   AEFilterUPP userUPP
);

Discussion

See the AEFilterProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

DisposeAEIdleUPP

Disposes of a universal procedure pointer to an Apple event idle function.

void DisposeAEIdleUPP (
   AEIdleUPP userUPP
);

Discussion

See the AEIdleProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

DisposeOSLAccessorUPP

Disposes of a universal procedure pointer to an object accessor function.

void DisposeOSLAccessorUPP (
   OSLAccessorUPP userUPP
);

Discussion

See the OSLAccessorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLAdjustMarksUPP

Disposes of a universal procedure pointer to an object callback adjust marks function.

void DisposeOSLAdjustMarksUPP (
   OSLAdjustMarksUPP userUPP
);

Discussion

See the OSLAdjustMarksProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLCompareUPP

Disposes of a universal procedure pointer to an object callback comparison function.

void DisposeOSLCompareUPP (
   OSLCompareUPP userUPP
);

Discussion

See the OSLCompareProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLCountUPP

Disposes of a universal procedure pointer to an object callback count function.

void DisposeOSLCountUPP (
   OSLCountUPP userUPP
);

Discussion

See the OSLCountProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLDisposeTokenUPP

Disposes of a universal procedure pointer to an object callback dispose token function.

void DisposeOSLDisposeTokenUPP (
   OSLDisposeTokenUPP userUPP
);

Discussion

See the OSLDisposeTokenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLGetErrDescUPP

Disposes of a universal procedure pointer to an object callback get error descriptor function.

void DisposeOSLGetErrDescUPP (
   OSLGetErrDescUPP userUPP
);

Discussion

See the OSLGetErrDescProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLGetMarkTokenUPP

Disposes of a universal procedure pointer to an object callback get mark function.

void DisposeOSLGetMarkTokenUPP (
   OSLGetMarkTokenUPP userUPP
);

Discussion

See the OSLGetMarkTokenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

DisposeOSLMarkUPP

Disposes of a universal procedure pointer to an object callback mark function.

void DisposeOSLMarkUPP (
   OSLMarkUPP userUPP
);

Discussion

See the OSLMarkProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeAECoerceDescUPP

Calls a universal procedure pointer to a function that coerces data stored in a descriptor.

OSErr InvokeAECoerceDescUPP (
   const AEDesc *fromDesc,
   DescType toType,
   SRefCon handlerRefcon,
   AEDesc *toDesc,
   AECoerceDescUPP userUPP
);

Return Value

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

Discussion

See the AECoerceDescProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

InvokeAECoercePtrUPP

Calls a universal procedure pointer to a function that coerces data stored in a buffer.

OSErr InvokeAECoercePtrUPP (
   DescType typeCode,
   const void *dataPtr,
   Size dataSize,
   DescType toType,
   SRefCon handlerRefcon,
   AEDesc *result,
   AECoercePtrUPP userUPP
);

Return Value

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

Discussion

See the AECoercePtrProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

InvokeAEDisposeExternalUPP

Calls a dispose external universal procedure pointer.

void InvokeAEDisposeExternalUPP (
   const void *dataPtr,
   Size dataLength,
   SRefCon refcon,
   AEDisposeExternalUPP userUPP
);

Parameters

dataPtr: A pointer to the data to be disposed of. The data must be immutable and must not be freed until this UPP is called.
dataLength: The length, in bytes, of the data to be disposed of.
refcon: A reference constant, supplied by your application, that you can use in your dispose function.

Discussion

See the AEDisposeExternalProcPtr function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AEDataModel.h

InvokeAEEventHandlerUPP

Calls an event handler universal procedure pointer.

OSErr InvokeAEEventHandlerUPP (
   const AppleEvent *theAppleEvent,
   AppleEvent *reply,
   SRefCon handlerRefcon,
   AEEventHandlerUPP userUPP
);

Return Value

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

Discussion

See the AEEventHandlerProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

InvokeAEFilterUPP

Calls an Apple event filter universal procedure pointer.

Boolean InvokeAEFilterUPP (
   EventRecord *theEvent,
   SInt32 returnID,
   AETransactionID transactionID,
   const AEAddressDesc *sender,
   AEFilterUPP userUPP
);

Return Value

The return value of the callback function. The filter routine returns TRUE to accept the Apple event or FALSE to filter it out.

Discussion

See the AEFilterProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

InvokeAEIdleUPP

Calls an Apple event idle universal procedure pointer.

Boolean InvokeAEIdleUPP (
   EventRecord *theEvent,
   SInt32 *sleepTime,
   RgnHandle *mouseRgn,
   AEIdleUPP userUPP
);

Return Value

The return value of the callback function. The filter routine returns TRUE if your application is no longer willing to wait for a reply from the server or for the user to bring the application to the front. It returns FALSE if your application is still willing to wait.

Discussion

See the AEIdleProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

InvokeOSLAccessorUPP

Calls an object accessor universal procedure pointer.

OSErr InvokeOSLAccessorUPP (
   DescType desiredClass,
   const AEDesc *container,
   DescType containerClass,
   DescType form,
   const AEDesc *selectionData,
   AEDesc *value,
   SRefCon accessorRefcon,
   OSLAccessorUPP userUPP
);

Return Value

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

Discussion

See the OSLAccessorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLAdjustMarksUPP

Calls an object callback adjust marks universal procedure pointer.

OSErr InvokeOSLAdjustMarksUPP (
   long newStart,
   long newStop,
   const AEDesc *markToken,
   OSLAdjustMarksUPP userUPP
);

Return Value

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

Discussion

See the OSLAdjustMarksProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLCompareUPP

Calls an object callback comparison universal procedure pointer.

OSErr InvokeOSLCompareUPP (
   DescType oper,
   const AEDesc *obj1,
   const AEDesc *obj2,
   Boolean *result,
   OSLCompareUPP userUPP
);

Return Value

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

Discussion

See the OSLCompareProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLCountUPP

Calls an object callback count universal procedure pointer.

OSErr InvokeOSLCountUPP (
   DescType desiredType,
   DescType containerClass,
   const AEDesc *container,
   long *result,
   OSLCountUPP userUPP
);

Return Value

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

Discussion

See the OSLCountProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLDisposeTokenUPP

Calls an object callback dispose token universal procedure pointer.

OSErr InvokeOSLDisposeTokenUPP (
   AEDesc *unneededToken,
   OSLDisposeTokenUPP userUPP
);

Return Value

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

Discussion

See the OSLDisposeTokenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLGetErrDescUPP

Calls an object callback get error descriptor universal procedure pointer.

OSErr InvokeOSLGetErrDescUPP (
   AEDesc **appDescPtr,
   OSLGetErrDescUPP userUPP
);

Return Value

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

Discussion

See the OSLGetErrDescProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLGetMarkTokenUPP

Calls an object callback get mark universal procedure pointer.

OSErr InvokeOSLGetMarkTokenUPP (
   const AEDesc *dContainerToken,
   DescType containerClass,
   AEDesc *result,
   OSLGetMarkTokenUPP userUPP
);

Return Value

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

Discussion

See the OSLGetMarkTokenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

InvokeOSLMarkUPP

Calls an object callback mark universal procedure pointer.

OSErr InvokeOSLMarkUPP (
   const AEDesc *dToken,
   const AEDesc *markToken,
   long index,
   OSLMarkUPP userUPP
);

Return Value

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

Discussion

See the OSLMarkProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewAECoerceDescUPP

Creates a new universal procedure pointer to a function that coerces data stored in a descriptor.

AECoerceDescUPP NewAECoerceDescUPP (
   AECoerceDescProcPtr userRoutine
);

Return Value

See AECoerceDescUPP.

Discussion

See the AECoerceDescProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

NewAECoercePtrUPP

Creates a new universal procedure pointer to a function that coerces data stored in a buffer.

AECoercePtrUPP NewAECoercePtrUPP (
   AECoercePtrProcPtr userRoutine
);

Return Value

See AECoercePtrUPP.

Discussion

See the AECoercePtrProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

NewAEDisposeExternalUPP

Creates a new universal procedure pointer to a function that disposes of data stored in a buffer.

AEDisposeExternalUPP NewAEDisposeExternalUPP (
   AEDisposeExternalProcPtr userRoutine
);

Return Value

See AEDisposeExternalUPP.

Discussion

See the AEDisposeExternalProcPtr callback function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AEDataModel.h

NewAEEventHandlerUPP

Creates a new universal procedure pointer to an event handler function.

AEEventHandlerUPP NewAEEventHandlerUPP (
   AEEventHandlerProcPtr userRoutine
);

Return Value

See AEEventHandlerUPP.

Discussion

See the AEEventHandlerProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEDataModel.h

NewAEFilterUPP

Creates a new universal procedure pointer to an Apple event filter function.

AEFilterUPP NewAEFilterUPP (
   AEFilterProcPtr userRoutine
);

Return Value

See AEFilterUPP.

Discussion

See the AEFilterProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

NewAEIdleUPP

Creates a new universal procedure pointer to an Apple event idle function.

AEIdleUPP NewAEIdleUPP (
   AEIdleProcPtr userRoutine
);

Return Value

See AEIdleUPP.

Discussion

See the AEIdleProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEInteraction.h

NewOSLAccessorUPP

Creates a new universal procedure pointer to an object accessor function.

OSLAccessorUPP NewOSLAccessorUPP (
   OSLAccessorProcPtr userRoutine
);

Return Value

See OSLAccessorUPP.

Discussion

See the OSLAccessorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLAdjustMarksUPP

Creates a new universal procedure pointer to an object callback adjust marks function.

OSLAdjustMarksUPP NewOSLAdjustMarksUPP (
   OSLAdjustMarksProcPtr userRoutine
);

Return Value

See OSLAdjustMarksUPP.

Discussion

See the OSLAdjustMarksProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLCompareUPP

Creates a new universal procedure pointer to an object callback comparison function.

OSLCompareUPP NewOSLCompareUPP (
   OSLCompareProcPtr userRoutine
);

Return Value

See OSLCompareUPP.

Discussion

See the OSLCompareProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLCountUPP

Creates a new universal procedure pointer to an object callback count function.

OSLCountUPP NewOSLCountUPP (
   OSLCountProcPtr userRoutine
);

Return Value

See OSLCountUPP.

Discussion

See the OSLCountProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLDisposeTokenUPP

Creates a new universal procedure pointer to an object callback dispose token function.

OSLDisposeTokenUPP NewOSLDisposeTokenUPP (
   OSLDisposeTokenProcPtr userRoutine
);

Return Value

See OSLDisposeTokenUPP.

Discussion

See the OSLDisposeTokenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLGetErrDescUPP

Creates a new universal procedure pointer to an object callback get error descriptor function.

OSLGetErrDescUPP NewOSLGetErrDescUPP (
   OSLGetErrDescProcPtr userRoutine
);

Return Value

See OSLGetErrDescUPP.

Discussion

See the OSLGetErrDescProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLGetMarkTokenUPP

Creates a new universal procedure pointer to an object callback get mark function.

OSLGetMarkTokenUPP NewOSLGetMarkTokenUPP (
   OSLGetMarkTokenProcPtr userRoutine
);

Return Value

See OSLGetMarkTokenUPP.

Discussion

See the OSLGetMarkTokenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

NewOSLMarkUPP

Creates a new universal procedure pointer to an object callback mark function.

OSLMarkUPP NewOSLMarkUPP (
   OSLMarkProcPtr userRoutine
);

Return Value

See OSLMarkUPP.

Discussion

See the OSLMarkProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEObjects.h

vAEBuildAppleEvent

Allows you to encapsulate calls to AEBuildAppleEvent in a wrapper routine.

OSStatus vAEBuildAppleEvent (
   AEEventClass theClass,
   AEEventID theID,
   DescType addressType,
   const void *addressData,
   Size addressLength,
   SInt16 returnID,
   SInt32 transactionID,
   AppleEvent *resultEvt,
   AEBuildError *error,
   const char *paramsFmt,
   va_list args
);

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 “AEBuild Error Codes” for the syntax error codes that can be returned in this structure.
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.
args: A variable array of arguments to be substituted into the paramsFmt format string. See the ANSI C Interfaces documentation for a description of the va_list data type.

Return Value

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

Discussion

Passing an argument list to vAEBuildAppleEvent corresponds to passing a series of individual parameters to the AEBuildAppleEvent function.

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 vAEBuildAppleEvent 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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

vAEBuildDesc

Allows you to encapsulate calls to AEBuildDesc in your own wrapper routines.

OSStatus vAEBuildDesc (
   AEDesc *dst,
   AEBuildError *error,
   const char *src,
   va_list args
);

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.
args: A reference to a previously defined, variable argument parameter list to use with the descriptor-string. The file <stdarg.h> defines macros for declaring and using the va_list data type.

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

Passing an argument list to vAEBuildDesc corresponds to passing a series of individual parameters to the AEBuildDesc function.

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 vAEBuildDesc 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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

AEHelpers.h

vAEBuildParameters

Allows you to encapsulate calls to AEBuildParameters in your own stdarg-style wrapper routines, using techniques similar to those allowed by vsprintf.

OSStatus vAEBuildParameters (
   AppleEvent *event,
   AEBuildError *error,
   const char *format,
   va_list args
);

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 AEDesc