Sending an Apple Event and Handling the Reply
After you add all the attributes and parameters required for the Apple event, use theAESend
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 thekeyErrorNumber
parameter of the reply Apple event. The server can return an error string in thekeyErrorString
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 theAESend
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 theAESend
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 theAESend
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 theAESend
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 theAECreateDesc
function to create a descriptor record that you wish to add to an Apple event. When you use theAEPutParamDesc
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 callAEDisposeDesc
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 ifAESend
returns an error result.If you specify the
kAEWaitReply
flag, the reply Apple event is returned in a parameter you pass to theAESend
function. If you specify thekAEQueueReply
flag to theAESend
function, the reply Apple event is returned in the event queue. In this case, the reply is identified by the event classkCoreEventClass
and the event IDkAEAnswer
. 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 thekeyErrorString
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 thekeyErrorString
parameter. A client application should therefore check for both thekeyErrorNumber
andkeyErrorString
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 callAEDisposeDesc
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.