Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Using Scripting Component Routines

Supplying Alternative Create and Send Functions

Every scripting component calls a create function whenever it creates an Apple event during script execution, and a send function whenever it sends an Apple event. Scripting components that use Apple events during script compilation, including AppleScript, also call create and send functions during compilation.

Some scripting components may provide routines that allow your application to set or get the pointers to the create and send functions used by that scripting component. If your application does not set alternative send and create functions, the scripting component uses the standard Apple Event Manager functions AESend and AECreateAppleEvent, which it calls with its own default parameters.

A scripting component that supports the routines you can use to set or get alternative create and send functions has the kOSASupportsAESending bit set in its component description record. For more information about using the Component Manager to find a scripting component that supports specific routines, see "Connecting to a Scripting Component," which begins on page 10-3.

When a scripting component calls your alternative send or create function, the A5 register is set up for your application, and your application is the current process.

Alternative Create Functions

A scripting component that allows your application to set or get its create function uses a pointer to identify the current create function.

TYPE AECreateAppleEventProcPtr = ProcPtr;

A pointer of type AECreateAppleEventProcPtr points to a MyAECreateProc function that takes the same parameters as the AECreate function plus a reference constant.

FUNCTION MyAECreateProc (theAEEventClass: AEEventClass; 
                         theAEEventID: AEEventID; 
                         target: AEAddressDesc; 
                         returnID: Integer; 
                         transactionID: LongInt; 
                         VAR result: AppleEvent;
                         refCon: LongInt): OSErr; 

Your application can use an alternative create function to gain control over the creation and addressing of Apple events. This can be useful, for example, if your application needs to add its own transaction code to the event.

To set an alternative create function, call OSASetCreateProc; to get the current create function, call OSAGetCreateProc. If you do not set an alternative create function for a scripting component, it uses the standard Apple Event Manager function AECreateAppleEvent, which it calls with its own default parameters.

Your alternative create function can in turn call the scripting component's default create function. To do this, your application can call OSAGetCreateProc before calling OSASetCreateProc to set the alternative create function, then call the default create function directly when necessary.

Alternative Send Functions

A scripting component that allows your application to set or get its send function uses a pointer to identify the current send function.

TYPE AESendProcPtr = ProcPtr;

A pointer of type AESendProcPtr points to a MyAESendProc function that takes the same parameters as the AECreate function plus a reference constant.

FUNCTION MyAESendProc (theAppleEvent: AppleEvent; 
                       VAR reply: AppleEvent; 
                       sendMode: AESendMode; 
                       sendPriority: AESendPriority; 
                       timeOutInTicks: LongInt; 
                       idleProc: IdleProcPtr; 
                       filterProc: EventFilterProcPtr;
                       refCon: LongInt): OSErr; 

Your application can use an alternative send function to perform almost any action instead of or in addition to sending Apple events. For example, it can modify Apple events before sending them, save copies of Apple events before sending them, or substitute some other specialized mechanism for sending Apple events.

To set an alternative send function, call OSASetSendProc; to get the current send function, call OSAGetSendProc. If you do not set an alternative send function for a scripting component, it uses the standard Apple Event Manager function AESend, which it calls with its own default parameters.

Your alternative send function can in turn call the scripting component's default send function. To do this, your application can call OSAGetSendProc before calling OSASetSendProc to set the alternative send function, then call the default send function directly when necessary.

After a scripting component successfully calls a send function, the scripting component proceeds with script execution. If a call to a send function is not successful, the scripting component returns errOSAScriptError, and a subsequent call to OSAScriptError with kOSAErrorNumber in the selector parameter returns errAEEventNotHandled.

Multithreaded applications need to allow other threads to execute while one thread is waiting for the response to an Apple event. You can accomplish this by supplying an idle function for your alternative send function that allows threads to be switched and by setting the kAEQueueReply flag in the sendMode parameter of the send function. However, if the call to the send function specifies the kAENoReply flag, be careful not to override it, because the user may have explicitly requested that no reply be returned or the 'aete' resource may indicate that the application cannot reply to that event.

Note

The Apple Event Manager calls an idle function only after an Apple event has been sent, whereas a scripting component calls an active function at regular intervals throughout script compilation and execution. Thus, to give time to multiple threads, you may want to provide an alternative active function in addition to an alternative send function and an idle function.

Some scripting components (including the current version of AppleScript) can execute only one script at a time per component instance. For this reason, a multithreaded application must provide a separate component instance for each script that it compiles or executes while it is also compiling or executing other scripts.

You should follow the rules for setting sendMode flags described in the chapter "Creating and Sending Apple Events" in this book when you set flags for the sendMode parameter of an alternative send function. Keep these additional guidelines in mind:

• If the target application is on the local computer, you can set the kAECanInteract and kAECanSwitchLayer flags.
• If the target application is on the local computer and the user has requested no reply, set the kAENoReply, kAECanInteract, and kAECanSwitchLayer flags.
• If the target application is on a remote computer, set the kAENeverInteract flag and do not set the kAECanSwitchLayer flag.