Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 5 - Creating and Sending Apple Events / Reference to Creating and Sending Apple Events

Routines for Creating and Sending Apple Events / Sending Apple Events

AESend

You can use the AESend 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 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 returned by this function is a null descriptor record. If you specify kAEWaitReply in the sendMode parameter, your application is responsible for using the AEDisposeDesc function to dispose of the descriptor record returned in the reply parameter.

sendMode

Specifies the following: the reply mode for the Apple event (set with one of the constants kAENoReply, kAEQueueReply, or kAEWaitReply); the interaction level (set with one of the constants kAENeverInteract, kAECanInteract, or kAEAlwaysInteract, which represent flags in the keyInteractLevelAttr attribute); the application switch mode (set with the kAECanSwitchLayer constant); the reconnection mode (set with the kAEDontReconnect constant); and the return receipt mode (set with the kAEWantReceipt constant). You obtain the value for this parameter by adding the appropriate constants. (The description that follows provides more details about the sendMode flags.)

sendPriority

An integer of data type AESendPriority that specifies whether the Apple event is put at the back of the event queue (indicated by the kAENormalPriority flag) or at the front of the queue (indicated by the kAEHighPriority flag).

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.

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 the sendMode 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 the sendMode 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.

Flag	Description
kAENeverInteract	The server application should never interact with the user in response to the Apple event. If this flag is set, AEInteractWithUser returns the errAENoUserInteraction result code. This flag is the default when an Apple event is sent to a remote application.
kAECanInteract	The server application can interact with the user in response to the Apple event--by convention, if the user needs to supply information to the server. If this flag is set and the server allows interaction, AEInteractWithUser either brings the server application to the foreground or posts a notification request. This flag is the default when an Apple event is sent to a local application.
kAEAlwaysInteract	The server application can interact with the user in response to the Apple event--by convention, whenever the server application normally asks a user to confirm a decision or interact in any other way, even if no additional information is needed from the user. If this flag is set and the server allows interaction, AEInteractWithUser either brings the server application to the foreground or posts a notification request.

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 returns errAETimeout 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 the AEProcessAppleEvent 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 returns noErr as its function result if the Apple event was successfully sent by the Event Manager. A noErr result from AESend 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 than noErr, and if the client is waiting for a reply, it is returned in the keyErrorNumber 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.

Flag	Description
kAEDontRecord	Your application is sending an event to itself but does not want the event recorded. When Apple event recording is on, the Apple Event Manager records a copy of every event your application sends to itself except for those events for which this flag is set.
kAEDontExecute	Your application is sending an Apple event to itself for recording purposes only--that is, you want the Apple Event Manager to send a copy of the event to the recording process but you do not want your application actually to receive the event.

RESULT CODES

noErr	0	No error
eLenErr	-92	Buffer too big to send
memFullErr	-108	Not enough room in heap zone
userCanceledErr	-128	User canceled an operation
procNotFound	-600	No eligible process with specified process serial number
connectionInvalid	-609	Nonexistent signature or session ID
noUserInteractionAllowed	-610	Background application sends event requiring authentication
noPortErr	-903	Client hasn't set 'SIZE' resource to indicate awareness of high-level events
destPortErr	-906	Server hasn't set 'SIZE' resource to indicate awareness of high-level events, or else is not present
sessClosedErr	-917	The kAEDontReconnect flag in the sendMode parameter was set and the server quit, then restarted
errAEEventNotHandled	-1708	Event wasn't handled by an Apple event handler
errAEUnknownSendMode	-1710	Invalid sending mode was passed
errAEWaitCanceled	-1711	User canceled out of wait loop for reply or receipt
errAETimeout	-1712	Apple event timed out
errAEUnknownAddressType	-1716	Unknown Apple event address type

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.