Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 3 - Introduction to Apple Events / Creating and Sending Apple Events

Sending an Apple Event and Handling the Reply

After you add all the attributes and parameters required for the Apple event, use the AESend function to send the Apple event. The Apple Event Manager uses the Event Manager to transmit the Apple event to the server application.

The AESend function requires that you specify whether your application should wait for a reply from the server. If you specify that you want a reply, the Apple Event Manager prepares a reply Apple event for your application by passing a default reply Apple event to the server. The Apple Event Manager returns any nonzero result code from the server's handler in the keyErrorNumber parameter of the reply Apple event. The server can return an error string in the keyErrorString parameter of the reply Apple event. The server can also use the reply Apple event to return any data you requested--for example, the results of a numeric calculation or a list of misspelled words.

You specify how your application should wait for a reply by using one of these flags in the sendMode parameter of the AESend function:

Flag	Description
kAENoReply	Your application does not want a reply Apple event.
kAEQueueReply	Your application wants a reply Apple event; the reply appears in your event queue as soon as the server has the opportunity to process and respond to your Apple event.
kAEWaitReply	Your application wants a reply Apple event and is willing to give up the processor while waiting for the reply; for example, if the server application is on the same computer as your application, your application yields the processor to allow the server to respond to your Apple event.

If you specify the kAEWaitReply flag, you should provide an idle function. This function should process any non-high-level events that occur while your application is waiting for a reply. You supply a pointer to your idle function as a parameter to the AESend function. So that your application can process other Apple events while it is waiting for a reply, you can also specify an optional filter function to the AESend function.

If you specify the kAENoReply flag, the reply Apple event prepared by the Apple Event Manager for the server application consists of a null descriptor record.

If your Apple event may require the user to interact with the server application (for example, to specify print or file options), you can communicate your user interaction preferences to the server by specifying additional flags in the sendMode parameter of the AESend function. These flags specify the conditions, if any, under which the server application can interact with the user and, if interaction is allowed, whether the server should come directly to the foreground or post a notification request.

The server application specifies its own preferences for user interaction by specifying flags to the AESetInteractionAllowed function, as described in the previous section. The interaction of the client and server applications' preferences is explained in detail in "Interacting With the User," which begins on page 4-45.

After you send an Apple event, your application is responsible for disposing of the Apple event record--and thereby deallocating the memory its data uses--by calling the AEDisposeDesc function. If you create one descriptor record and add it to another, the Apple Event Manager adds a copy of the newly created one to the existing one and also makes a copy of the associated data. For example, you might use the AECreateDesc function to create a descriptor record that you wish to add to an Apple event. When you use the AEPutParamDesc function, it adds a copy of your newly created descriptor record, including its data, as a parameter to an existing Apple event. When you no longer need the original descriptor record, you should call AEDisposeDesc to dispose of it.

Your application should dispose of all the descriptor records that are created for the purposes of adding parameters and attributes to an Apple event. You normally dispose of your Apple event and its reply after you receive a result from the AESend function. You should dispose of these even if AESend returns an error result.

If you specify the kAEWaitReply flag, the reply Apple event is returned in a parameter you pass to the AESend function. If you specify the kAEQueueReply flag to the AESend function, the reply Apple event is returned in the event queue. In this case, the reply is identified by the event class kCoreEventClass and the event ID kAEAnswer. Your application processes reply events in its event queue in the same way that server applications process Apple events.

Your application should check for the existence of the keyErrorNumber parameter of the reply Apple event to ensure that the server performed the requested action. The server can also return, in the keyErrorString parameter, any error messages you need to display to the user.

Whenever a server application provides an error string, it should also provide an error number. However, you can't count on all server applications to do so. The absence of the keyErrorNumber parameter doesn't necessarily mean that there won't an error string provided in the keyErrorString parameter. A client application should therefore check for both the keyErrorNumber and keyErrorString parameters before assuming that no error has occurred. If a string has been provided without an error number, an error has occurred.

After extracting the information it needs from the reply event, your handler should dispose of the reply by calling the AEDisposeDesc function. Similarly, when your handler no longer needs descriptor records it has extracted from the reply, it should call AEDisposeDesc to dispose of them.

The next section provides an overview of the way a source application identifies Apple event objects supported by a target application. If you are starting by supporting only the Required suite and the Apple events sent by the Edition Manager, you can skip the next section and go directly to "About the Apple Event Manager," which begins on page 3-40.