GWKB2036 : Internal and External Scripts

Product: Window-Eyes
Author: Aaron Smith
Date Added: 08/16/2013
Last Modified: 08/16/2013

General

Window-Eyes defines a script as any procedure, document, or process that is launched by Window-Eyes. It is possible to create other programs that interact with the Window-Eyes object model and behave similarly to scripts; see the Other COM Clients section of this document for more on those.

Window-Eyes supports two different types of scripts, internal and external. Internal scripts are scripts that are associated with an ActiveScript engine, and include those written in languages like VBScript, JavaScript, or PerlScript. Internal scripts are executed within the Window-Eyes process, and they get some additional support from Window-Eyes for common tasks.

External scripts are all other scripts. They might be standalone executables created in a compiled language like Visual Basic or C++, or they might be scripts that require a non-ActiveScript engine in order to run, such as a PHP script or a Windows Script Host file.

Differences between Script Types

Predefined Objects

Internal scripts are started with three predefined objects named Application, Speech, and Script. (These names may contain additional punctuation or markup as required by your script language.) In addition, all top-level properties of those three objects are also predefined, so - for example - there is a predefined value called Version which is merely a simpler way to refer to the Version property of the predefined Application object.

The Script Object

The Script object is predefined in internal scripts (see above) but not in external scripts. External scripts, in fact, have no way to create or access a Script object, as the Script object only contains information that would be useful to an internal script. External environments will already have a way to do anything the Script object can do; see the documentation for your preferred environment.

Windows Vista and In-Process COM Servers

When you instantiate an in-process COM server from an internal script on Windows Vista, the object that is created is not actually instantiated in the same process your script is running in, for reasons of security and interoperability. Instead, it is instantiated in a separate process that is started automatically for the purpose of hosting such objects. This should normally not affect the operation of your script, but it may be useful to know about it for debugging and profiling purposes.

Responsibilities of External Scripts

Create a WindowEyes.Application Object

An external script is responsible for connecting to the Window-Eyes object model on its own. This is usually done through the CoCreateInstance API or through related methods in higher-level languages such as CreateObject or GetObject. At the very least, an external script should create a WindowEyes.Application object.

Register With the Window-Eyes Script Identification Mechanism

Once an external script has created a WindowEyes.Application object, it should call the ClientIdentify method of that object in order to identify itself to Window-Eyes as the script that Window-Eyes just launched. It is recommended that you pass the process ID of your script process to ClientIdentify, if it is available. If it is not, you may also pass the full path to the running script or, if that is also not available, the filename without a path.

Watch For OnShutdown

Calling ClientIdentify will cause the ClientInformation property of the Application object to become defined. An external script should always monitor the OnShutdown event of that ClientInformation object, and it should shut down when that event is received. This allows Window-Eyes to notify the external script when the application with which it was associated has been closed or when Window-Eyes itself is shutting down and the script is no longer needed.

Terminate When Requested

Window-Eyes will automatically terminate any external script that does not shut itself down in response to the OnShutdown event in a timely manner. However, relying on this behavior is not recommended as it has the potential to leave hardware, database, or other resources in an undefined or unexpected state. This automatic termination also applies to external scripts that have not called ClientIdentify.

Other COM Clients

Non-script COM clients also connect to the Window-Eyes object model by creating a WindowEyes.Application object. However, they should not call ClientIdentify, because since they were not launched by Window-Eyes, Window-Eyes has no prior knowledge of their existence or of why they were launched and cannot create a meaningful ClientInformation object for them.

Non-script clients should monitor the OnQuit event of the WindowEyes.Application object and should behave appropriately when it is received. Unlike most COM servers, the Window-Eyes application will not remain loaded when the user or another COM client causes it to exit. Attempting to use the Window-Eyes object model after the OnQuit event has been signaled will likely result in errors.