Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Scripting Components Reference

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

OSAExecuteEvent

You can use the OSAExecuteEvent function to handle an Apple event with the aid of a script context and obtain a script ID for the resulting script value.

FUNCTION OSAExecuteEvent(scriptingComponent: ComponentInstance;
                         theAppleEvent: AppleEvent;
                         contextID: OSAID;
                         modeFlags: LongInt;
                         VAR resultingScriptValueID: OSAID)
                         : 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.

resultingScriptValueID

A script ID for the resulting script value.

DESCRIPTION

The OSAExecuteEvent function 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 AppleScript doesn't include statements that handle the event), OSAExecuteEvent immediately returns errAEEventNotHandled rather than errOSAScriptError.

If the scripting component determines that the script context can handle the event, OSAExecuteEvent executes the script context's handler and returns the resulting script ID. If execution of the script context's handler for the event generates an error, OSAExecuteEvent returns errOSAScriptError, and you can get more detailed error information by calling the OSAScriptError function.

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 identified by the contextID parameter specifies that the Apple event should be passed to the application's default handler for that event (for example, with an AppleScript continue statement), OSAExecuteEvent 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 OSAExecuteEvent again). If the contextID parameter is kOSANullScript, the OSAExecuteEvent function passes the event directly to the resume dispatch function. If a 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

The OSAExecuteEvent function 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, OSAExecuteEvent 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, OSAExecuteEvent returns errOSAScriptError and a call to OSAScriptError with kOSAErrorNumber in the selector parameter returns errAEEventNotHandled as the resulting error description.

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
errOSAScriptError	-1753	Error occurred during execution or because of an attempt to pass event to a NIL resume dispatch function
badComponentInstance	$80008001	Invalid component instance