====== 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