Apple Events Programming Guide: Creating an Apple Event

< Previous PageNext Page >

Hide TOC

Creating an Apple Event

This section provides examples of how to create an Apple event with AECreateAppleEvent and with AEBuildAppleEvent. These functions are introduced in “Two Approaches to Creating an Apple Event.”

In this section:

Creating an Apple Event With AEBuildAppleEvent
Creating an Apple Event With AECreateAppleEvent
Disposing of Apple Events You Create

Creating an Apple Event With AEBuildAppleEvent

The AEBuildAppleEvent function provides a mechanism for converting a specially formatted string into a complete Apple event. This function is similar to AECreateAppleEvent, but contains additional parameters it uses in creating the Apple event and constructing parameters for it.

The AEBuildAppleEvent function is similar to the printf family of routines in the standard C library. The syntax for the format string defines an Apple event as a sequence of name-value pairs, with optional parameters preceded with a tilde (~) character. For details, see Technical Note TN2106, AEBuild*, AEPrint*, and Friends.

The next two code listings show how you might use AEBuildAppleEvent to create an Apple event that tells the Finder to reveal the startup disk (make it visible on the desktop).

Listing 6-3 Constants used in creating a reveal Apple event for the Finder

const CFStringRef startupDiskPath = CFSTR("/");// 1

const OSType finderSignature = 'MACS';// 2

Here’s a description of these constants, which are defined in AERegistry.h and used by the Finder in its Apple event support:

Defines a string reference for the POSIX-style path of the startup disk.
Defines the application signature for the Mac OS Finder application.
Because the Finder is always running in Mac OS X, it is generally safe to send it an Apple event without first making sure it has been launched.

Listing 6-4 shows a function that creates an Apple event to reveal the startup disk in the Finder.

Listing 6-4 Creating a reveal Apple event with AEBuildAppleEvent

OSErr BuildRevealStartupDiskAE (AppleEvent * revealEvent)// 1

    FSRef startupDiskFSRef;

    AliasHandle startupDiskAlias;

    OSErr err = noErr;

    CFURLRef startupURLRef =

        CFURLCreateWithFileSystemPath(kCFAllocatorDefault,

            startupDiskPath, kCFURLPOSIXPathStyle, true);// 2

    if (CFURLGetFSRef(startupURLRef, &startupDiskFSRef))// 3

        err = FSNewAlias(NULL, &startupDiskFSRef, &startupDiskAlias);// 4

        if (err == noErr)

            err = AEBuildAppleEvent(// 5

                    kAEMiscStandards,// 6

                    kAEMakeObjectsVisible,// 7

                    typeApplSignature,// 8

                    &finderSignature,// 9

                    sizeof(finderSignature),// 10

                    kAutoGenerateReturnID, // 11

                    kAnyTransactionID,// 12

                    revealEvent,// 13

                    NULL,// 14

                    "'----':[alis(@@)]",// 15

                    startupDiskAlias);// 16

    else

        err = memFullErr;// 17

    return err;// 18

Here’s a description of how the BuildRevealStartupDiskAE function works:

It is passed a pointer to an Apple event data structure for the event to be created.
It calls CFURLCreateWithFileSystemPath to create a CFURLRef for the path to the startup disk, passing the constant startupDiskPath declared in Listing 6-3.
It calls CFURLGetFSRef to get an FSRef file reference to the startup disk from the CFURLRef.
It calls FSNewAlias to convert the FSRef to an alias handle for the startup disk, to use in creating the Apple event.
It calls AEBuildAppleEvent to create the Apple event. The next several items describe the parameters you pass to that function.
Specifies kAEMiscStandards, a constant defined in AERegistry.h, for the event class.
Specifies kAEMakeObjectsVisible, also defined in AERegistry.h, for the event ID.
Passes typeApplSignature to specify a target address type.
Passes finderSignature, defined in Listing 6-3, to specify the application signature for the Finder.
Passes the size of the application signature.
Passes the Apple Event Manager constant kAutoGenerateReturnID, indicating the Apple Event Manager should set a return ID for the event. Your application can specify its own return ID, if needed.
Passes the Apple Event Manager constant kAnyTransactionID, indicating the event is not part of a series of interdependent transactions.
Passes a pointer to the Apple event to be built.
Passes a value of NULL, indicating no error information is required.
See Technical Note TN2106, AEBuild*, AEPrint*, and Friends for information on working with error information when using AEBuildAppleEvent.
Passes a format string containing information for any attributes and parameters to add to the Apple event. In this case, there is just one parameter, an alias ('----').
The identifier for the direct parameter in an Apple event is specified by the constant keyDirectObject ('----'). The minus sign has special meaning in AEBuild strings, so it should always be enclosed in single quotes when it is used to identify the direct parameter for an Apple event.
Passes the previously created alias handle as the data corresponding to the entry in the format string.
In the case where the function could not create an FSRef, it sets a return error value.
It returns a value indicating whether an error occurred.

To see how the BuildRevealStartupDiskAE function is called, and how you can send the resulting Apple event, see Listing 6-7.

Creating an Apple Event With AECreateAppleEvent

To create an Apple event with AECreateAppleEvent, you perform these steps:

Prepare a target address descriptor, as described in “Creating a Target Address Descriptor.”
Call AECreateAppleEvent to create the Apple event, passing the event class, event ID, and other information.
If necessary, call other Apple Event Manager functions to add additional information to the event, until it contains all the information required for the task you want to perform.

For example, suppose your application wants to send a quit Apple event to another application. It might do this to terminate an application it launched previously, or perhaps to make sure an application is not running so it can perform an update. Listing 6-5 shows how to create a quit application Apple event.

Listing 6-5 Creating a quit Apple event with AECreateAppleEvent

AppleEvent someAE;

err = AECreateAppleEvent(// 1

        kCoreEventClass,// 2

        kAEQuitApplication,// 3

        &theTarget,// 4

        kAutoGenerateReturnID,// 5

        kAnyTransactionID,// 6

        &someAE);// 7

Here’s how the code in Listing 6-5 works:

It calls AECreateAppleEvent to create the Apple event. The following items describe the parameters you pass to that function.
Specifies kCoreEventClass, a constant defined in AppleEvents.h, for the event class.
Specifies kAEQuitApplication, also defined in AppleEvents.h, for the event ID.
Passes the address of the previously constructed target address descriptor, which identifies the application to send the quit event to.
Passes the Apple Event Manager constant kAutoGenerateReturnID, indicating the Apple Event Manager should set a return ID for the event. Your application can specify its own return ID, if needed.
Passes the Apple Event Manager constant kAnyTransactionID, indicating the event is not part of a series of interdependent transactions.
It passes the address of an Apple event data structure for the event to be created.

That’s all you need to do to create a quit Apple event. However, to create a more complicated Apple event, you typically need to add attributes or parameters to the event. For example, your application might receive a get data Apple event for which it returns some specified text as the direct parameter of the reply Apple event. Listing 6-6 shows how to add such a direct parameter, using a previously defined function.

Listing 6-6 Adding a direct parameter to an Apple event

OSErr anErr = AEPutParamString(// 1

                    reply,// 2

                    keyDirectObject,// 3

                    textStringRef);// 4

Here’s how the code in Listing 6-6 works:

It calls the application-defined function AEPutParamString, shown in Listing 5-3. The following items describe the parameters you pass to add a direct parameter to the Apple event.
A pointer to the Apple event to add the parameter to.
An Apple Event Manager keyword constant specifying that the parameter is to be added as the direct parameter of the Apple event.
A CFStringRef, obtained prior to the call, that specifies the text for the direct parameter.

You can also use the AEBuildParameters function, introduced in “Two Approaches to Creating an Apple Event,” to add more complicated attributes or parameters to an existing Apple event.

Disposing of Apple Events You Create

Regardless of how you create an Apple event, your application is responsible for disposing of it with the AEDisposeDesc function when you are finished with it. Your application must also dispose of all the descriptor records it creates when adding parameters and attributes to an Apple event—remember, many Apple Event Manager functions make copies of descriptors and of their associated data, as noted in “Disposing of Apple Event Data Structures.”

You normally dispose of your Apple event and its reply, if any, after you send the event and receive a result (either from AESend or AESendMessage). You should dispose of the data structures you created even if the sending function returns an error. If you are sending the event asynchronously, you need not wait for the reply Apple event before disposing of the sent Apple event.

< Previous PageNext Page >

Hide TOC

Last updated: 2007-10-31

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice