Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Scripting Components Reference

Optional Scripting Component Routines / Using Script Contexts to Handle Apple Events

OSADoEvent

You can use the OSADoEvent function to handle an Apple event with the aid of a script context and obtain a reply event.

FUNCTION OSADoEvent(scriptingComponent: ComponentInstance;
                    theAppleEvent: AppleEvent;
                    contextID: OSAID;
                    modeFlags: LongInt;
                    VAR reply: AppleEvent): OSAError;

scriptingComponent

A component instance created by a prior call to the Component Manager function OpenDefaultComponent or OpenComponent (see page 10-4).

theAppleEvent

The Apple event to be handled.

contextID

The script ID for the script context to be used to handle the Apple event.

modeFlags

Information used by individual scripting components. To avoid setting any mode flags, specify kOSAModeNull. Other possible mode flags are listed in the description that follows.

reply

The reply Apple event.

DESCRIPTION

The OSADoEvent function resembles both OSADoScript and OSAExecuteEvent. However, unlike OSADoScript, the script OSADoEvent executes must be in the form of a script context, and execution is initiated by an Apple event. Unlike OSAExecuteEvent, OSADoEvent returns a reply Apple event rather than the script ID of the resulting script value.

The OSADoEvent function, like OSAExecuteEvent, attempts to use the script context specified by the contextID parameter to handle the Apple event specified by the theAppleEvent parameter. If the scripting component determines that the script context can't handle the event (for example, if a script written in an AppleScript dialect doesn't include statements that handle the event), OSADoEvent immediately returns errAEEventNotHandled rather than errOSAScriptError.

If the scripting component determines that the script context can handle the event, OSADoEvent executes the script context's handler for the event and returns the resulting script ID.

The OSADoEvent function returns a reply event that contains either the resulting script value or, if an error occurred during script execution, information about the error. If the error errOSAScriptError occurs during script execution, OSADoEvent calls OSAScriptError and returns the appropriate error information in the reply. The OSADoEvent function never returns errOSAScriptError.

You can control the way in which the scripting component executes a script context by adding any of these flags to the modeFlags parameter:

Flag	Description
kOSAModeNeverInteract	Adds kAENeverInteract to sendMode parameter of AESend for events sent when script is executed.
kOSAModeCanInteract	Adds kAECanInteract to sendMode parameter of AESend for events sent when script is executed.
kOSAModeAlwaysInteract	Adds kAEAlwaysInteract to sendMode parameter of AESend for events sent when script is executed.
kOSAModeCantSwitchLayer	Prevents use of kAECanSwitchLayer in sendMode parameter of AESend for events sent when script is executed (the opposite of the Apple Event Manager's interpretation of the same bit).
kOSAModeDontReconnect	Adds kAEDontReconnect to sendMode parameter of AESend for events sent when script is executed.
kOSAModeDoRecord	Prevents use of kAEDontRecord in sendMode parameter of AESend for events sent when script is executed (the opposite of the Apple Event Manager's interpretation of the same bit).

If the script context specifies that the Apple event should be passed to the application's standard handler for that event (for example, with an AppleScript continue statement), OSADoEvent passes the event to the resume dispatch function currently being used by the scripting component. The resume dispatch function dispatches the event directly to the application's standard handler for that event (that is, without calling OSADoEvent again). If the contextID parameter is kOSANullScript, the OSADoEvent function passes the event directly to the resume dispatch function. If the call to the resume dispatch function is successful, execution of the script context proceeds from the point at which the resume dispatch function was called.

IMPORTANT

Like OSAExecuteEvent, OSADoEvent can generate the result code errAEEventNotHandled in at least two ways. If the scripting component determines that a script context doesn't declare a handler for a particular event, OSADoEvent immediately returns errAEEventNotHandled. If a scripting component calls its resume dispatch function during script execution and the application's standard handler for the event fails to handle it, OSADoEvent returns errAEEventNotHandled in the reply Apple event.

RESULT CODES

noErr	0	No error
errAEEventNotHandled	-1708	Script context doesn't contain handler for event
errOSASystemError	-1750	General scripting system error
errOSAInvalidID	-1751	Invalid script ID
badComponentInstance	$80008001	Invalid component instance

SEE ALSO

For an example of the use of OSADoEvent, see Listing 10-7 on page 10-21.