Differences

This shows you the differences between two versions of the page.

--- code:system:process [2011/01/30 21:01] – created jmgr
+++ code:system:process [2011/04/20 20:28] (current) – removed jmgr
@@ Line 1: / Line 1: @@
-====== Process ======
-This object allows you to start and manage a process. (program)
-===== Functions =====
-==== Process ====
-Constructor function.
-=== Syntax ===
-<code javascript>
-var myObject = new Process();
-</code>
-<code javascript>
-var myObject = new Process(parameters);
-</code>
-=== Arguments ===
-  - parameters - (object) the parameters
-    * workingDirectory - (string) the working directory
-    * processChannelMode - ([[#processchannelmode|ProcessChannelMode]]) the process's channel mode
-    * readChannel - ([[#processchannel|ProcessChannel]]) the process's read channel
-    * onError - ([[#onError|onError]]) called when an error has occured
-    * onFinished - ([[#onFinished|onFinished]]) called when the process has finished
-    * onReadyReadStandardError - ([[#onReadyReadStandardError|onReadyReadStandardError]]) called when the process has data on the standard error channel
-    * onReadyReadStandardOutput - ([[#onReadyReadStandardOutput|onReadyReadStandardOutput]]) called when the process has data on the standard output channel
-    * onStarted - ([[#onStarted|onStarted]]) called when the process has started
-    * onStateChanged - ([[#onStateChanged|onStateChanged]]) called when the process's state has changed
-=== Example ===
-<code javascript>
-var myObject = new Process();
-</code>
-<code javascript>
-var myObject = new Process({
-	workingDirectory: "/home/user",
-	onStarted: function()
-	{
-		Console.print("Started!");
-	},
-	onFinished: function()
-	{
-		Console.print("Finished!");
-	}
-});
-</code>
-==== list ====
-Returns an array of [[code:core:processhandle|ProcessHandle]] linked to all running processes.
-=== Syntax ===
-<code javascript>
-Process.list();
-</code>
-=== Returns ===
-  * (array) an array of [[code:core:processhandle|ProcessHandle]] linked to all running processes
-==== thisProcess ====
-Returns a [[code:core:processhandle|ProcessHandle]] linked to the Actionaz process.
-=== Syntax ===
-<code javascript>
-Process.thisProcess();
-</code>
-=== Returns ===
-  * (array) a [[code:core:processhandle|ProcessHandle]] linked to the Actionaz process
-==== startDetached ====
-Starts a process in detached mode and returns a [[code:core:processhandle|ProcessHandle]] linked to it.
-You will have lesser control on the process than in attached mode, but it will be independent of the current execution.
-=== Syntax ===
-<code javascript>
-Process.startDetached(filename);
-</code>
-<code javascript>
-Process.startDetached(filename, parameters);
-</code>
-<code javascript>
-Process.startDetached(filename, parameters, workingDirectory);
-</code>
-=== Arguments ===
-  - filename - (string) the filename/command of the process to start
-  - parameters - (array) an array of parameters
-  - workingDirectory - (string) the working directory
-=== Returns ===
-  * (array) a [[code:core:processhandle|ProcessHandle]] linked to the started process
-=== Exceptions ===
-  * (FilenameError) invalid filename
-  * (StartProcessError) unable to start the process
-===== Methods =====
-==== handle ====
-Returns a [[code:core:processhandle|ProcessHandle]] linked to the started process
-=== Syntax ===
-<code javascript>
-myObject.handle();
-</code>
-=== Returns ===
-  * ([[code:core:processhandle|ProcessHandle]]) a [[code:core:processhandle|ProcessHandle]] linked to the started process
-==== id ====
-Returns the process id of the started process.
-=== Syntax ===
-<code javascript>
-myObject.id();
-</code>
-=== Returns ===
-  * (integer) the process id of the started process
-==== start ====
-Starts the process.
-=== Syntax ===
-<code javascript>
-myObject.start(filename);
-</code>
-<code javascript>
-myObject.start(filename, parameters);
-</code>
-<code javascript>
-myObject.start(filename, parameters, openMode);
-</code>
-=== Arguments ===
-  - filename - (string) the filename/command of the process to start
-  - parameters - (array) an array of parameters
-  - openMode - ([[#openmode|OpenMode]]) the open mode to use (default: read and write)
-=== Returns ===
-  * (Process) this Process
-=== Exceptions ===
-  * (FilenameError) invalid filename
-==== state ====
-Returns the state of the started process.
-=== Syntax ===
-<code javascript>
-myObject.state();
-</code>
-=== Returns ===
-  * ([[#processstate|ProcessState]]) the state of the started process
-==== error ====
-Returns the error state of the started process.
-=== Syntax ===
-<code javascript>
-myObject.error();
-</code>
-=== Returns ===
-  * ([[#processerror|ProcessError]]) the error state of the started process
-==== exitCode ====
-Returns the process's exit code.
-=== Syntax ===
-<code javascript>
-myObject.exitCode();
-</code>
-=== Returns ===
-  * (integer) the process's exit code
-==== exitStatus ====
-Returns the process's exit status.
-=== Syntax ===
-<code javascript>
-myObject.exitStatus();
-</code>
-=== Returns ===
-  * ([[#exitstatus|ExitStatus]]) the process's exit status
-==== readError ====
-Returns the content of the standard error output as a [[code:core:rawdata|RawData]].
-=== Syntax ===
-<code javascript>
-myObject.readError();
-</code>
-=== Returns ===
-  * ([[code:core:rawdata|RawData]]) the content of the standard error output as a [[code:core:rawdata|RawData]]
-==== read ====
-Returns the content of the standard output as a [[code:core:rawdata|RawData]].
-=== Syntax ===
-<code javascript>
-myObject.read();
-</code>
-=== Returns ===
-  * ([[code:core:rawdata|RawData]]) the content of the standard output as a [[code:core:rawdata|RawData]]
-==== readErrorText ====
-Returns the content of the standard error output as text.
-=== Syntax ===
-<code javascript>
-myObject.readErrorText();
-</code>
-<code javascript>
-myObject.readErrorText(encoding);
-</code>
-=== Arguments ===
-  - encoding - ([[code:core:global#encoding|Encoding]]) the encoding to use
-=== Returns ===
-  * (string) the content of the standard error output as text
-==== readText ====
-Returns the content of the standard output as text.
-=== Syntax ===
-<code javascript>
-myObject.readText();
-</code>
-<code javascript>
-myObject.readText(encoding);
-</code>
-=== Arguments ===
-  - encoding - ([[code:core:global#encoding|Encoding]]) the encoding to use
-=== Returns ===
-  * (string) the content of the standard output as text
-==== atEnd ====
-Returns true if the process is not running and if no data can be read.
-=== Syntax ===
-<code javascript>
-myObject.atEnd();
-</code>
-=== Returns ===
-  * (boolean) true if the process is not running and if no data can be read
-==== bytesAvailable ====
-Returns the number of bytes that can be read.
-=== Syntax ===
-<code javascript>
-myObject.bytesAvailable();
-</code>
-=== Returns ===
-  * (integer) the number of bytes that can be read
-==== bytesToWrite ====
-Returns the number of bytes that are still to be written.
-=== Syntax ===
-<code javascript>
-myObject.bytesToWrite();
-</code>
-=== Returns ===
-  * (integer) the number of bytes that are still to be written
-==== canReadLine ====
-Returns true if a line can be read.
-=== Syntax ===
-<code javascript>
-myObject.canReadLine();
-</code>
-=== Returns ===
-  * (boolean) true if a line can be read
-==== write ====
-Writes some data to the process.
-=== Syntax ===
-<code javascript>
-myObject.write(data);
-</code>
-=== Arguments ===
-  - data - (mixed) the data to write
-=== Returns ===
-  * (Process) this Process
-==== writeText ====
-Writes text to the process.
-=== Syntax ===
-<code javascript>
-myObject.writeText(text, encoding);
-</code>
-=== Arguments ===
-  - text - (string) the text to write
-  - encoding - ([[code:core:global#encoding|Encoding]]) the encoding to use
-=== Returns ===
-  * (Process) this Process
-==== setWorkingDirectory ====
-Sets the working directory. This only works when the process is not already started.
-=== Syntax ===
-<code javascript>
-myObject.setWorkingDirectory(workingDirectory);
-</code>
-=== Arguments ===
-  - workingDirectory - (string) the text to write
-=== Returns ===
-  * (Process) this Process
-==== setProcessChannelMode ====
-Sets process's channel mode. This only works when the process is not already started.
-=== Syntax ===
-<code javascript>
-myObject.setProcessChannelMode(channelMode);
-</code>
-=== Arguments ===
-  - channelMode - ([[#processchannelmode|ProcessChannelMode]]) the process's channel mode
-=== Returns ===
-  * (Process) this Process
-==== setEnvironment ====
-Sets the process's environment variables. This only works when the process is not already started.
-=== Syntax ===
-<code javascript>
-myObject.setEnvironment(environment);
-</code>
-=== Arguments ===
-  - environment - (object) the process's environment variable
-=== Returns ===
-  * (Process) this Process
-=== Example ===
-<code javascript>
-myObject.setEnvironment({
-	PATH: "c:\\;c:\\path",
-	MYVAR: "hello"
-});
-</code>
-==== updateEnvironment ====
-Updates the process's environment variables. This only works when the process is not already started.
-=== Syntax ===
-<code javascript>
-myObject.updateEnvironment(environment);
-</code>
-=== Arguments ===
-  - environment - (object) the process's environment variable
-=== Returns ===
-  * (Process) this Process
-=== Example ===
-<code javascript>
-myObject.updateEnvironment({
-	PATH: "c:\\;c:\\path",
-	MYVAR: "hello"
-});
-</code>
-==== setReadChannel ====
-Sets process's read channel.
-=== Syntax ===
-<code javascript>
-myObject.setReadChannel(channel);
-</code>
-=== Arguments ===
-  - channel - ([[#processchannel|ProcessChannel]]) the process's read channel
-=== Returns ===
-  * (Process) this Process
-==== setStandardErrorFile ====
-Sets the standard error file.
-=== Syntax ===
-<code javascript>
-myObject.setStandardErrorFile(fileName);
-</code>
-<code javascript>
-myObject.setStandardErrorFile(fileName, openMode);
-</code>
-=== Arguments ===
-  - fileName - (string) the filename
-  - channel - ([[#openmode|OpenMode]]) the file's open mode (default: Truncate)
-=== Returns ===
-  * (Process) this Process
-==== setStandardInputFile ====
-Sets the standard input file.
-=== Syntax ===
-<code javascript>
-myObject.setStandardInputFile(fileName);
-</code>
-=== Arguments ===
-  - fileName - (string) the filename
-=== Returns ===
-  * (Process) this Process
-==== setStandardOutputFile ====
-Sets the standard output file.
-=== Syntax ===
-<code javascript>
-myObject.setStandardOutputFile(fileName);
-</code>
-<code javascript>
-myObject.setStandardOutputFile(fileName, openMode);
-</code>
-=== Arguments ===
-  - fileName - (string) the filename
-  - channel - ([[#openmode|OpenMode]]) the file's open mode (default: Truncate)
-=== Returns ===
-  * (Process) this Process
-==== setStandardOutputProcess ====
-Sets the standard output process.
-=== Syntax ===
-<code javascript>
-myObject.setStandardOutputFile(process);
-</code>
-=== Arguments ===
-  - process - (Process) the output process
-=== Returns ===
-  * (Process) this Process
-=== Exceptions ===
-  * (InvalidProcessError) invalid process
-==== waitForFinished ====
-Freezes the execution until the process has finished.
-=== Syntax ===
-<code javascript>
-myObject.waitForFinished(waitTime);
-</code>
-<code javascript>
-myObject.waitForFinished();
-</code>
-=== Arguments ===
-  - waitTime - (integer) the time to wait (milliseconds, default: 30000)
-=== Returns ===
-  * (Process) this Process
-=== Exceptions ===
-  * (WaitForFinishedError) wait for finished failed
-==== waitForStarted ====
-Freezes the execution until the process has started.
-=== Syntax ===
-<code javascript>
-myObject.waitForStarted(waitTime);
-</code>
-<code javascript>
-myObject.waitForStarted();
-</code>
-=== Arguments ===
-  - waitTime - (integer) the time to wait (milliseconds, default: 30000)
-=== Returns ===
-  * (Process) this Process
-=== Exceptions ===
-  * (WaitForStartedError) wait for started failed
-==== waitForBytesWritten ====
-Freezes the execution until the data has been written.
-=== Syntax ===
-<code javascript>
-myObject.waitForBytesWritten(waitTime);
-</code>
-<code javascript>
-myObject.waitForBytesWritten();
-</code>
-=== Arguments ===
-  - waitTime - (integer) the time to wait (milliseconds, default: 30000)
-=== Returns ===
-  * (Process) this Process
-=== Exceptions ===
-  * (WaitForBytesWrittenError) wait for bytes written failed
-==== waitForReadyRead ====
-Freezes the execution until data is available.
-=== Syntax ===
-<code javascript>
-myObject.waitForReadyRead(waitTime);
-</code>
-<code javascript>
-myObject.waitForReadyRead();
-</code>
-=== Arguments ===
-  - waitTime - (integer) the time to wait (milliseconds, default: 30000)
-=== Returns ===
-  * (Process) this Process
-=== Exceptions ===
-  * (WaitForReadyReadError) wait for ready read failed
-==== close ====
-Tries to close the process gracefully.
-=== Syntax ===
-<code javascript>
-myObject.close();
-</code>
-=== Returns ===
-  * (Process) this Process
-==== kill ====
-Kills the process.
-=== Syntax ===
-<code javascript>
-myObject.kill();
-</code>
-=== Returns ===
-  * (Process) this Process
-==== terminate ====
-Terminates the process.
-=== Syntax ===
-<code javascript>
-myObject.terminate();
-</code>
-=== Returns ===
-  * (Process) this Process
-===== Events =====
-==== onError ====
-Called when an error occured.
-=== Syntax ===
-<code javascript>
-myObject.onError = function(processError) {};
-</code>
-=== Arguments ===
-  - processError - ([[#processerror|ProcessError]]) the process error that has occured
-=== Example ===
-<code javascript>
-myObject.onError = function(processError)
-{
-	//Event action
-};
-</code>
-==== onFinished ====
-Called when the process has finished.
-=== Syntax ===
-<code javascript>
-myObject.onFinished = function(exitCode, exitStatus) {};
-</code>
-=== Arguments ===
-  - exitCode - (integer) the process's exit code
-  - exitStatus - ([[#exitstatus|ExitStatus]]) the process's exit status
-=== Example ===
-<code javascript>
-myObject.onFinished = function(exitCode, exitStatus)
-{
-	//Event action
-};
-</code>
-==== onReadyReadStandardError ====
-Called when there is data available on the standard error output.
-=== Syntax ===
-<code javascript>
-myObject.onReadyReadStandardError = function() {};
-</code>
-=== Example ===
-<code javascript>
-myObject.onReadyReadStandardError = function()
-{
-	//Event action
-};
-</code>
-==== onReadyReadStandardOutput ====
-Called when there is data available on the standard output.
-=== Syntax ===
-<code javascript>
-myObject.onReadyReadStandardOutput = function() {};
-</code>
-=== Example ===
-<code javascript>
-myObject.onReadyReadStandardOutput = function()
-{
-	//Event action
-};
-</code>
-==== onStarted ====
-Called when the process has started executing.
-=== Syntax ===
-<code javascript>
-myObject.onStarted = function() {};
-</code>
-=== Example ===
-<code javascript>
-myObject.onStarted = function()
-{
-	//Event action
-};
-</code>
-==== onStateChanged ====
-Called when the process's state has changed.
-=== Syntax ===
-<code javascript>
-myObject.onStateChanged = function(newState) {};
-</code>
-=== Arguments ===
-  - newState - ([[#processstate|ProcessState]]) the process's state
-=== Example ===
-<code javascript>
-myObject.onStateChanged = function(newState)
-{
-	//Event action
-};
-</code>
-===== Enumerations =====
-==== ProcessError ====
-A process error.
-=== Values ===
-  - FailedToStart: the file cannot be found or insufficient permissions
-  - Crashed: the process has crashed after having started successfully
-  - Timedout: the last waitFor... method failed
-  - WriteError: the process is not running or it may have closed it's input channel
-  - ReadError: the process is not running
-  - UnknownError: an unknown error has occured
-==== ExitStatus ====
-The process's exit status.
-=== Values ===
-  - NormalExit: the process finished normally
-  - CrashExit: the process crashed
-==== ProcessState ====
-The process's status.
-=== Values ===
-  - NotRunning: the process is not running
-  - Starting: the process is starting
-  - Running: the process is running
-==== ProcessChannel ====
-A process's channel.
-=== Values ===
-  - StandardOutput: the standard output channel
-  - StandardError: the standard error output channel
-==== ProcessChannelMode ====
-A process's channel mode.
-=== Values ===
-  - SeparateChannels: the standard error and output channels are separated
-  - MergedChannels: the standard error channel is redirected to the the standard output channel
-  - ForwardedChannels: the output of both channels is redirected to the parent process
-==== OpenMode ====
-A process's channel open mode.
-=== Values ===
-  - ReadOnly: process channel opened for reading only
-  - WriteOnly: process channel opened for writing only
-  - ReadWrite: process channel opened for reading and writing
-  - Truncate: process channel opened for writing, erases any previous content
-  - Text: process channel opened in text mode
-  - Unbuffered: process channel opened in unbuffered mode