ShellServiceFunctions modified by

Tue, 16 Jul 2013 01:50:44 -0000

Shell, Process and Service functions

wbc.launchAppEx

Description: Launch a new application, command line utility, etc. in a new process.
Threading: foreground/immediate, with background timeout listener.
Function: wbc.launchAppEx(fileSpec, arguments, callback, isHidden, timeout)
Arguments:
- fileSpec: String. Full path and file name of executable to be launched.
- arguments: String. Command line arguments to pass to the executable being launched.
- callback: Optional. Bound JS function to be called on timeout, when the process terminates, or when wbc.closeThread() is called on the listening thread.
- isHidden: Optional. If true, the process will be launched hidden.
- timeout: Optional. Number of milliseconds to wait for process termination. If specified the callback will be called after this amount of time, even if the process is still running.
Returns:
- OK/INVALID (bad arguments)/ERROR (invalid path, unable to create process. etc).
- If a callback was specified, the thread ID of the listening thread.
Notes:
- A simpler version of this function is available: launchApp(fileSpec, arguments).
- Optional arguments must be set to 'null' if not required.
- If the callback parameter is set, the callback will return an evt object with the following properties.
  - string func: internal function name ('uisdk_LaunchApp')
  - int threadId: the thread ID of the listening thread.
  - string status: the thread status (can be either 'OK' - the thread was finished successfully, and 'ERROR' - the thread was terminated by the uisdk_CloseThread function)
- string appPath: the full path to the executable
- string parameters: the command line arguments of the new process, if any
- int timeout: the timeout value
- bool isTimedOut: 'true' if the callback was called as a result of timeout elapsed, and 'false' - otherwise
- int processId: the process ID of the target process
- int exitCode: the exit code of the target process. In case the process is still running, the exit code is equal to 259 - a special exit code meaning that the process is not finished yet.

wbc.launchConsoleApp

Description: Launch a command line application in 'interactive mode'
Threading: Foreground/immediate with background listener.
Function: wbc.launchConsoleApp(fileSpec, args, callback)
Arguments:
- fileSpec: The path to the process to be launched.
- args: Command line arguments with which to launch the process.
- callback: Bound JS function receiving an evt object. This object has the following properties:
- string func - equal to 'uisdk_LaunchConsoleApp'
- integer threadId - the WBC thread ID
- string appPath - the full path to the executable (the one that was passed to the original uisdk_LaunchApp function)
- string parameters - the parameters that was passed to the original uisdk_LaunchApp
- string status - the thread status. Can be one of the following:
  * 'OK' - the thread was finished successfully (i.e. - console process finished)
  - 'ERROR' - the thread was terminated by the uisdk_CloseThread, or an internal error occured while processing the STDOUT outputs from the process (the 'errorDesc' field of the callback object may contain the details about the error
  - 'BUSY' - the process is working, and the 'stdOut' field of the callback object contains the textual data printed by the console application to STDOUT or STDERR.
- string errorDesc - the error description (in case the status 'ERROR)
- int processId - the process ID of the target process
- int exitCode - the exit code of the target process. In case the process is still running, the exit code is equal to 259 - a special exit code meaning that the process is not finished yet.
- string stdOut - the next portion of the data that was printed by the console to STDOUT or STDERR streams (current only if status remains'BUSY')
Returns:
- ERROR/INVALID
- Thread ID of monitoring thread.
Notes:
- In conjunction with writeStdIn, this function can be used to control and interact with many command line programs.
- For example, an FTP shell, some terminal programs, ping, traceroute, etc..
- This includes programs that prompt (deterministically) for user input, by writing the response to STDIN via writeStdIn

wbc.writeStdIn

Description: Companion function to launchConsoleApp that writes to STDIN for the specified process.
Threading: Foreground/immediate.
Function: wbc.writeStdIn(threadId, inputText)
Arguments:
- threadId: The thread id returned by launchConsoleApp when the process was launched.
- inputText: Text to send to the console input (for example to send Y+ENTER, pass 'Y\r\n');
Returns:
- OK/ERROR/INVALID
Notes: None

wbc.listServices

Description: Retrieves a list of services currently detected on the system.
Threading: foreground/blocking
Function: wbc.listServices()
Arguments: None
Returns:
- ERROR/NOPLUGIN
- If successful, returns an array of objects, each representing a service and having the following properties:
- string serviceName: internal service name
- string displayName: the display name of the service.
- int processId: service PID
- string state: the current state of the service. This can be one of the following string values:
  - "STOPPED": the service is not running
  - "START_PENDING": the service is starting
  - "STOP_PENDING": the service is stopping
  - "RUNNING": the service is running
  - "CONTINUE_PENDING": the service continue is pending
  - "PAUSE_PENDING": the service pause is pending
  - "PAUSED": the service is paused
Notes
- The ServiceManager.dll plugin must be loaded in order for this function to work.

wbc.queryServiceConfig

Description: Query the configuration of a specific service.
Threading: foreground/blocking
Function: wbc.queryServiceConfig(serviceName)
Arguments:
- serviceName: The internal name of the service.
Returns:
- NOPLUGIN: ServiceManager.dll plugin was not loaded.
- INVALID/ERROR_ACCESS_DENIED/ERROR
- If successful, returns an object with the following properties:
  - string displayName: the display name of the service
- string startType: specifies when to start the service. This parameter can be one of the following string values:
  - "AUTO_START": a service started automatically by the service control manager during system startup
  - "DEMAND_START": a service started by the service control manager when a process calls the uisdk_ServiceStart function
  - "DISABLED": a service that cannot be started. Attempts to start the service result in the error returned
- string binaryPathName: the fully qualified path to the service binary file
- string errorControl: the severity and startup behavior of a service failure. Can be one of the following string values:
  - "IGNORE": the startup program logs the error but continues the startup operation
  - NORMAL": the startup program logs the error and puts up a message box pop-up but continues the startup operation
  - "SEVERE": the startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration
  - "CRITICAL": the startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration
Notes:
- The ServiceManager.dll plugin must be loaded in order for this function to work.

wbc.queryServiceStatus

Description: Queries the current operational status of the specified service.
Threading: foreground/blocking.
Function: wbc.queryServiceStatus(serviceName)
Arguments:
- serviceName: internal name of the service.
Returns:
- NOPLUGIN/ERROR/ERROR_ACCESS_DENIED/INVALID
- If successful, returns the status string, which can be one of the following:
- "STOPPED": the service is not running
- "START_PENDING": the service is starting
- "STOP_PENDING": the service is stopping
- "RUNNING": the service is running
- "CONTINUE_PENDING": the service continue is pending
- "PAUSE_PENDING": the service pause is pending
- "PAUSED": the service is paused
Notes:
- The ServiceManager.dll plugin must be loaded in order for this function to work.

wbc.startService

Description: Starts a specific service
Threading: Background threaded
Function: wbc.startService(serviceName, callback, timeout)
Arguments:
- serviceName: Internal name of the service to be started.
- timeout: wait timeout in millseconds. Callback will be invoked if the service is started or the timeout duration has elapsed without it starting.
- callback: bound JS function, receiving an object that will have the following properties:
  - string func: internal function name ('uisdk_ServiceStart')
  - string status: the status of the start operation. Can be one of the following string values:
    - "STOPPED": the service is not running
    - "RUNNING": the service is running
    - "PAUSED": the service is paused
    - "TIMEOUT": service start was not completed within the specified timeout value
Returns:
- ERROR/INVALID/NOPLUGIN/ERROR_ACCESS_DENIED
- OK.
Notes:
- If the service is already running, OK is returned, and the callback never completes.
- If the service is not already running, OK is also returned, and the callback will fire on timeout or service startup completion.
- Because of the above ambiguity, care should be taken to query the service status with queryServiceStatus before calling this function.
- This function requires the ServiceManager.dll plugin loaded in order to work.

wbc.stopService

Description: Stops a specific service
Threading: Background threaded with callback
Function: wbc.stopService(serviceName, callback, timeout)
Arguments:
- serviceName: Internal name of the service to be started.
- timeout: wait timeout in millseconds. Callback will be invoked if the service is started or the timeout duration has elapsed without it starting.
- callback: bound JS function, receiving an object that will have the following properties:
  - string func: internal function name ('uisdk_ServiceStop')
  - string status: the status of the start operation. Can be one of the following string values:
    - "STOPPED": the service is not running
  - "RUNNING": the service is running
  - "PAUSED": the service is paused
  - "TIMEOUT": service start was not completed within the specified timeout value
Returns:
- ERROR/INVALID/NOPLUGIN/ERROR_ACCESS_DENIED
- OK.
Notes:
- If the service is already stopped, OK is returned, and the callback never completes.
- If the service is not already stopped , OK is also returned, and the callback will fire on timeout or service stop completion.
- Because of the above ambiguity, care should be taken to query the service status with queryServiceStatus before calling this function.
- This function requires the ServiceManager.dll plugin loaded in order to work.

Recent changes to ShellServiceFunctions

ShellServiceFunctions modified by

Shell, Process and Service functions