Differences

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

@@ 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 [[en:code:core:processhandle|ProcessHandle]] linked to all running processes.
+=== Syntax ===
+<code javascript>
+Process.list();
+</code>
+=== Returns ===
+  * (array) an array of [[en:code:core:processhandle|ProcessHandle]] linked to all running processes
+==== thisProcess ====
+Returns a [[en:code:core:processhandle|ProcessHandle]] linked to the Actionaz process.
+=== Syntax ===
+<code javascript>
+Process.thisProcess();
+</code>
+=== Returns ===
+  * (array) a [[en:code:core:processhandle|ProcessHandle]] linked to the Actionaz process
+==== startDetached ====
+Starts a process in detached mode and returns a [[en: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 [[en:code:core:processhandle|ProcessHandle]] linked to the started process
+=== Exceptions ===
+  * (FilenameError) invalid filename
+  * (StartProcessError) unable to start the process
+===== Methods =====
+==== handle ====
+Returns a [[en:code:core:processhandle|ProcessHandle]] linked to the started process
+=== Syntax ===
+<code javascript>
+myObject.handle();
+</code>
+=== Returns ===
+  * ([[en:code:core:processhandle|ProcessHandle]]) a [[en: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 [[en:code:core:rawdata|RawData]].
+=== Syntax ===
+<code javascript>
+myObject.readError();
+</code>
+=== Returns ===
+  * ([[en:code:core:rawdata|RawData]]) the content of the standard error output as a [[en:code:core:rawdata|RawData]]
+==== read ====
+Returns the content of the standard output as a [[en:code:core:rawdata|RawData]].
+=== Syntax ===
+<code javascript>
+myObject.read();
+</code>
+=== Returns ===
+  * ([[en:code:core:rawdata|RawData]]) the content of the standard output as a [[en: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 - ([[en: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 - ([[en: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 - ([[en: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