Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Using Scripting Component Routines

Supplying a Resume Dispatch Function

Every scripting component calls a resume dispatch function during script execution if the script contains the equivalent of an AppleScript continue statement within an event handler. (See Figure 7-7 on page 7-22 for an example.) The resume dispatch function dispatches the event specified by the script directly to the application's standard handler for that event.

Thus, if the script context passed to OSADoEvent in Listing 10-7 specifies that the event passed in the event parameter should be continued--that is, handled by the application's standard Apple event handler for that event--the scripting component passes the event to the resume dispatch function currently set for that instance of the scripting component. The resume dispatch function attempts to redispatch the event to the handler installed in the application's Apple event dispatch table for that event. If the call to the resume dispatch function is successful, execution of the script proceeds from the point at which the resume dispatch function was called. If the call to the resume dispatch function is not successful, OSADoEvent returns errAEEventNotHandled in the keyErrorNumber parameter of the reply event. (Other routines that execute scripts, such as OSAExecute or OSAExecuteEvent, return errOSAScriptError in this situation, and a subsequent call to OSAScriptError with kOSAErrorNumber in the selector parameter returns errAEEventNotHandled.)

Some scripting components may provide routines that allow your application to set or get the pointer to the resume dispatch function used by a specified instance of a scripting component.

TYPE AEHandlerProcPtr = EventHandlerProcPtr;

A resume dispatch function takes the same parameters as an Apple event handler.

FUNCTION MyResumeDispatch (theAppleEvent: AppleEvent; 
                           reply: AppleEvent; refCon: LongInt)
                           :OSErr;

To set the resume dispatch function for a scripting component, call OSASetResumeDispatchProc; to get the current dispatch function for a scripting component, call OSAGetResumeDispatchProc. If you do not set a resume dispatch function for a scripting component, it uses standard Apple event dispatching to dispatch the event, starting with the special handler dispatch table.

You can install a resume dispatch function using the OSASetResumeDispatchProc function. However, if you are using a general handler similar to that in Listing 10-7 on page 10-21 and you can rely on standard Apple event dispatching to dispatch the event correctly, you don't need to provide a resume dispatch function. Instead, you can specify kOSAUseStandardDispatch as the resume dispatch function and the constant kOSADontUsePhac as the reference constant when you call OSASetResumeDispatchProc.

myErr := OSASetResumeDispatchProc(gScriptingComponent, 
               kOSAUseStandardDispatch, kOSADontUsePhac);

This causes the Apple Event Manager to redispatch events that would otherwise be passed to a resume dispatch function using standard Apple event dispatching--except that the Apple Event Manager bypasses your application's special handler dispatch table and thus won't call your general Apple event handler recursively.

When a scripting component calls your resume dispatch function, the A5 register is set up for your application, and your application is the current process.