131 lines
5.7 KiB
Plaintext
131 lines
5.7 KiB
Plaintext
|
|
********************** RunLocalCommand ***********************
|
|
|
|
RunLocalCommand usage:
|
|
|
|
If RunLocalCommand is called with fWait=true, the call will not return
|
|
until the process has exited. The return value will be an identifier for
|
|
the dead process that can be used in a call to GetProcessOutput() and
|
|
GetProcessExitCode(). If the return value is zero,
|
|
an error occurred and GetLastRunLocalError() can be called to get the
|
|
error code. OnProcessEvent events will be fired for this process. The
|
|
returned process ID is only valid until the next call to RunLocalCommand
|
|
on that thread.
|
|
|
|
If RunLocalCommand is called with fWait=false, the call returns
|
|
immediately and the return code is the process identifier. If the ID is 0
|
|
an error occurred which can be retrieved by calling
|
|
GetLastRunLocalError(). The OnProcessEvent event will be fired to indicate
|
|
events regarding the process, such as termination. See below for details.
|
|
|
|
GetProcessExitCode() can be called for any process which has exited.
|
|
Calling GetProcessExitCode() if the process is still running is an error.
|
|
|
|
GetProcessOutput() can be called for any process which had
|
|
fGetOutput=true. If fWait was true, then GetProcessOutput() will return
|
|
all information written to STDOUT and STDERR while the process was
|
|
running. If fWait was false, then if the process has terminated the
|
|
return value is the same as if fWait was true. If the process is still
|
|
running, all text sent to STDOUT & STDERR up to the current time will be
|
|
returned.
|
|
|
|
For a process which has connected via the IScriptedProcess interface (an
|
|
OnProcessEvent event is fired when this happens) the script can call
|
|
SendToProcess() to send information to that process. If the process is not
|
|
connected a call to SendToProcess will be ignored and the return value is
|
|
zero.
|
|
|
|
OnProcessEvent events:
|
|
|
|
When OnProcessEvent is fired, the first parameter (lProcessID) contains
|
|
the ProcessID associated with the event, the second parameter (bstrEvent)
|
|
is a string identifying the event, and the third parameter (vData) is data
|
|
associated with the particular event.
|
|
|
|
bstrEvent='exited': the process has exited and vData is the process exit
|
|
code.
|
|
|
|
bstrEvent='terminated': The process was terminated as a result of a call
|
|
to TerminateProcess(). vData will have no data.
|
|
|
|
bstrEvent='crash': The process or one of its children had an unhandled
|
|
exception and was terminated. vData will have no data. (Win2000 only)
|
|
|
|
bstrEvent='connected': Fired when the process connects to the script
|
|
host through the IScriptedProcess interface.
|
|
|
|
bstrEvent can also be any value set by the running process through the
|
|
IScriptedProcess interface. By connecting to this interface, processes
|
|
that are aware of the scripting engine can communicate to the script. In
|
|
this case, bstrEvent will be an identifier string given by the process,
|
|
and vData will contain a parameter string given by the process. The return
|
|
value from the OnProcessEvent function is passed to the calling process.
|
|
It must be an integer value.
|
|
|
|
|
|
Implementation Notes:
|
|
* Return 1 for the processId if fWait=true.
|
|
* Return code and output info must be stored per-thread for PID=1.
|
|
* Use Win2K's Job APIs to better manage terminating a process.
|
|
* Pass an environment variable with a unique ID when creating a process.
|
|
Processes should use this ID when calling IScriptedProcess::SetProcessID.
|
|
(On win2K only this can be accomplished using the job APIs)
|
|
|
|
|
|
|
|
********************** Script Engine Interfaces ***********************
|
|
|
|
The interface used for the global interface of the script engines is
|
|
IGlobalMTScript. The script engines should use the PublicData and
|
|
PrivateData properties on the global object to store data that must be
|
|
shared between script engines. The PublicData property is made visible to
|
|
an external COM object which can be created remotely. The intent of this
|
|
is for the creation of a UI which can manipulate the scripts. The
|
|
PrivateData property is for the storage of other global data which should
|
|
not be made visible outside the script engine.
|
|
|
|
|
|
********************** MTScript Service ***********************
|
|
|
|
The MTScript service is an EXE which runs as a service. When running, it
|
|
registers the RemoteMTScript class as a remotable COM object. Any number
|
|
of these objects can be created at a time and it allows a remote client
|
|
to talk to the MTScript engine. The script engine runs even if no clients
|
|
are connected.
|
|
|
|
Issues:
|
|
* Need a way to reset the script engine
|
|
* Need a way to download scripts
|
|
* Should support both JScript and VBScript
|
|
|
|
|
|
********************** UI Operation ***********************
|
|
|
|
A UI to the MTScript engine is created by creating a web page which
|
|
instantiates the RemoteMTScript class. This gives it access to the
|
|
public data published by the script engine, which can be used to display
|
|
status information and impact the build. There is also an Exec method on
|
|
the COM object which fires an event on the primary script in the script
|
|
engine. The script engine can then take appropriate action depending on
|
|
the command.
|
|
|
|
The RemoteMTScript class also has an event interface which is used to send
|
|
notifications back to the web page.
|
|
|
|
Issue: How does the returning event interface get hooked up? Can you hook
|
|
up to events dynamically on an object created via script code?
|
|
|
|
|
|
********************** Controlling Remote Machines *******************
|
|
|
|
A script can control remote machines by instantiating the RemoteMTScript
|
|
COM object using the standard script mechanism ("new ActiveXObject(...)"
|
|
in JScript). The remote machine becomes a slave to the machine which can
|
|
then control it.
|
|
|
|
Hooking up the events on the RemoteMTScript object is done using the
|
|
standard JScript event hooking mechanism. If no such mechanism is
|
|
available (is there?) then the IGlobalMTScript interface will provide a
|
|
mechanism to register and unregister for events on the object.
|
|
|