Important: The information in this document is obsolete and should not be used for new development.
AESend
You can use theAESend
function to send an Apple event.
FUNCTION AESend (theAppleEvent: AppleEvent; VAR reply: AppleEvent; sendMode: AESendMode; sendPriority: AESendPriority; timeOutInTicks: LongInt; idleProc: IdleProcPtr; filterProc: EventFilterProcPtr): OSErr;
theAppleEvent
The Apple event to be sent.reply
- The reply Apple event returned by the
AESend
function if you specify thekAEWaitReply
flag in thesendMode
parameter. (If you specify thekAEQueueReply
flag in thesendMode
parameter, you receive the reply Apple event in your event queue.) If you specifykAENoReply
flag, the reply Apple event returned by this function is a null descriptor record. If you specifykAEWaitReply
in thesendMode
parameter, your application is responsible for using theAEDisposeDesc
function to dispose of the descriptor record returned in thereply
parameter.sendMode
- Specifies the following: the reply mode for the Apple event (set with one of the constants
kAENoReply
,kAEQueueReply
, orkAEWaitReply
); the interaction level (set with one of the constantskAENeverInteract
,kAECanInteract
, orkAEAlwaysInteract
, which represent flags in thekeyInteractLevelAttr
attribute); the application switch mode (set with thekAECanSwitchLayer
constant); the reconnection mode (set with thekAEDontReconnect
constant); and the return receipt mode (set with thekAEWantReceipt
constant). You obtain the value for this parameter by adding the appropriate constants. (The description that follows provides more details about thesendMode
flags.)sendPriority
An integer of data typeAESendPriority
that specifies whether the Apple event is put at the back of the event queue (indicated by thekAENormalPriority
flag) or at the front of the queue (indicated by thekAEHighPriority
flag).timeOutInTicks
If the reply mode specified in thesendMode
parameter iskAEWaitReply
, 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 thekAEDefaultTimeout
constant, which tells the Apple Event Manager to provide an appropriate timeout duration. If the value of this parameter iskNoTimeOut
, the Apple event never times out.idleProc
- A 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 application can also perform other tasks (such as displaying a wristwatch or spinning beachball cursor) while waiting for a reply or a return receipt. Your application must provide an idle function if it specifies the
kAEWaitReply
flag in thesendMode
parameter.filterProc
- A pointer to a function that accepts certain incoming Apple events that are received while the handler waits for a reply or a return receipt and filters out the rest.
DESCRIPTION
You can use one of the following flags in thesendMode
parameter to specify the reply mode for an Apple event. Only one of these flags may be set.
Flag Description kAENoReply Your application does not want a reply Apple event; the server processes your Apple event as soon as it has the opportunity. 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 kAEWaitReply
, you should provide an idle function.You can communicate your user interaction preferences to the server application by specifying one of the following flags in the
sendMode
parameter. Only one of these flags may be set.The flags in the following list specify the application switch mode, the reconnection mode, and the return receipt mode. Any of these flags may be set.
Flag Description kAECanSwitchLayer If both the client and server allow interaction, and if the client application is the active application on the local computer and is waiting for a reply (that is, it has set the kAEWaitReply
flag),AEInteractWithUser
brings the server directly to the foreground. Otherwise,AEInteractWithUser
uses the Notification Manager to request that the user bring the server application to the foreground.kAEDontReconnect The Apple Event Manager must not automatically try to reconnect if it receives a sessClosedErr
result code from the PPC Toolbox.kAEWantReceipt The sender wants to receive a return receipt for this Apple event from the Event Manager. (A return receipt means only that the receiving application accepted the Apple event; the Apple event may or may not be handled successfully after it is accepted.) If the receiving application does not send a return receipt before the request times out, AESend
returnserrAETimeout
as its function result.If the Apple Event Manager cannot find a handler for an Apple event in either the application or system Apple event dispatch table, it returns the result code
errAEEventNotHandled
to the server application (as the result of theAEProcessAppleEvent
function). If the client application is waiting for a reply, the Apple Event Manager also returns this result code to the client.The
AESend
function returnsnoErr
as its function result if the Apple event was successfully sent by the Event Manager. AnoErr
result fromAESend
does not indicate that the Apple event was handled successfully; it indicates only that the Apple event was successfully sent by the Event Manager. If the handler returns a result code other thannoErr
, and if the client is waiting for a reply, it is returned in thekeyErrorNumber
parameter of the reply Apple event.If your application is sending an event to itself, you can set one of these flags to prevent the event from being recorded or to ask the Apple Event Manager to record the event without your application actually receiving it. Only one of these flags may be set.
RESULT CODES
SEE ALSO
For more information on sending Apple events, see "Sending an Apple Event," which begins on page 5-13.For information on writing an idle function, see "Writing an Idle Function," which begins on page 5-22.
For information on writing a reply filter function, see "Writing a Reply Filter Function," which begins on page 5-24.
For information on when to use the
kAEDontExecute
flag, see the chapter "Recording Apple Events" in this book.