en:code:system:process
Differences
This shows you the differences between two versions of the page.
Previous revision | |||
— | en:code:system:process [2021/02/13 11:23] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
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 javascript> | ||
+ | var myObject = new Process(parameters); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - parameters - (object) the parameters | ||
+ | * workingDirectory - (string) the working directory | ||
+ | * processChannelMode - ([[# | ||
+ | * readChannel - ([[# | ||
+ | * onError - ([[# | ||
+ | * onFinished - ([[# | ||
+ | * onReadyReadStandardError - ([[# | ||
+ | * onReadyReadStandardOutput - ([[# | ||
+ | * onStarted - ([[# | ||
+ | * onStateChanged - ([[# | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | var myObject = new Process(); | ||
+ | </ | ||
+ | <code javascript> | ||
+ | var myObject = new Process({ | ||
+ | workingDirectory: | ||
+ | onStarted: function() | ||
+ | { | ||
+ | Console.print(" | ||
+ | }, | ||
+ | onFinished: | ||
+ | { | ||
+ | Console.print(" | ||
+ | } | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | ==== list ==== | ||
+ | Returns an array of [[en: | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | Process.list(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (array) an array of [[en: | ||
+ | |||
+ | ==== thisProcess ==== | ||
+ | Returns a [[en: | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | Process.thisProcess(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (array) a [[en: | ||
+ | |||
+ | ==== startDetached ==== | ||
+ | Starts a process in detached mode and returns a [[en: | ||
+ | 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 javascript> | ||
+ | Process.startDetached(filename, | ||
+ | </ | ||
+ | <code javascript> | ||
+ | Process.startDetached(filename, | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - filename - (string) the filename/ | ||
+ | - parameters - (array) an array of parameters | ||
+ | - workingDirectory - (string) the working directory | ||
+ | |||
+ | === Returns === | ||
+ | * (array) a [[en: | ||
+ | |||
+ | === Exceptions === | ||
+ | * (FilenameError) invalid filename | ||
+ | * (StartProcessError) unable to start the process | ||
+ | |||
+ | ===== Methods ===== | ||
+ | |||
+ | ==== handle ==== | ||
+ | Returns a [[en: | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.handle(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * ([[en: | ||
+ | |||
+ | ==== id ==== | ||
+ | Returns the process id of the started process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.id(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (integer) the process id of the started process | ||
+ | |||
+ | ==== start ==== | ||
+ | Starts the process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.start(filename); | ||
+ | </ | ||
+ | <code javascript> | ||
+ | myObject.start(filename, | ||
+ | </ | ||
+ | <code javascript> | ||
+ | myObject.start(filename, | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - filename - (string) the filename/ | ||
+ | - parameters - (array) an array of parameters | ||
+ | - openMode - ([[# | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | === Exceptions === | ||
+ | * (FilenameError) invalid filename | ||
+ | |||
+ | ==== state ==== | ||
+ | Returns the state of the started process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.state(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * ([[# | ||
+ | |||
+ | ==== error ==== | ||
+ | Returns the error state of the started process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.error(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * ([[# | ||
+ | |||
+ | ==== exitCode ==== | ||
+ | Returns the process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.exitCode(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (integer) the process' | ||
+ | |||
+ | ==== exitStatus ==== | ||
+ | Returns the process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.exitStatus(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * ([[# | ||
+ | |||
+ | ==== readError ==== | ||
+ | Returns the content of the standard error output as a [[en: | ||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.readError(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * ([[en: | ||
+ | |||
+ | ==== read ==== | ||
+ | Returns the content of the standard output as a [[en: | ||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.read(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * ([[en: | ||
+ | |||
+ | ==== readErrorText ==== | ||
+ | Returns the content of the standard error output as text. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.readErrorText(); | ||
+ | </ | ||
+ | <code javascript> | ||
+ | myObject.readErrorText(encoding); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - encoding - ([[en: | ||
+ | |||
+ | === 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 javascript> | ||
+ | myObject.readText(encoding); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - encoding - ([[en: | ||
+ | |||
+ | === 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(); | ||
+ | </ | ||
+ | |||
+ | === 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(); | ||
+ | </ | ||
+ | |||
+ | === 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(); | ||
+ | </ | ||
+ | |||
+ | === 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(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (boolean) true if a line can be read | ||
+ | |||
+ | ==== write ==== | ||
+ | Writes some data to the process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.write(data); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - data - (mixed) the data to write | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== writeText ==== | ||
+ | Writes text to the process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.writeText(text, | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - text - (string) the text to write | ||
+ | - encoding - ([[en: | ||
+ | |||
+ | === 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); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - workingDirectory - (string) the text to write | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== setProcessChannelMode ==== | ||
+ | Sets process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setProcessChannelMode(channelMode); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - channelMode - ([[# | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== setEnvironment ==== | ||
+ | Sets the process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setEnvironment(environment); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - environment - (object) the process' | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.setEnvironment({ | ||
+ | PATH: " | ||
+ | MYVAR: " | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | ==== updateEnvironment ==== | ||
+ | Updates the process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.updateEnvironment(environment); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - environment - (object) the process' | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.updateEnvironment({ | ||
+ | PATH: " | ||
+ | MYVAR: " | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | ==== setReadChannel ==== | ||
+ | Sets process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setReadChannel(channel); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - channel - ([[# | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== setStandardErrorFile ==== | ||
+ | Sets the standard error file. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setStandardErrorFile(fileName); | ||
+ | </ | ||
+ | <code javascript> | ||
+ | myObject.setStandardErrorFile(fileName, | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - fileName - (string) the filename | ||
+ | - channel - ([[# | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== setStandardInputFile ==== | ||
+ | Sets the standard input file. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setStandardInputFile(fileName); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - fileName - (string) the filename | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== setStandardOutputFile ==== | ||
+ | Sets the standard output file. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setStandardOutputFile(fileName); | ||
+ | </ | ||
+ | <code javascript> | ||
+ | myObject.setStandardOutputFile(fileName, | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - fileName - (string) the filename | ||
+ | - channel - ([[# | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== setStandardOutputProcess ==== | ||
+ | Sets the standard output process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.setStandardOutputFile(process); | ||
+ | </ | ||
+ | |||
+ | === 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 javascript> | ||
+ | myObject.waitForFinished(); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - waitTime - (integer) the time to wait (milliseconds, | ||
+ | |||
+ | === 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 javascript> | ||
+ | myObject.waitForStarted(); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - waitTime - (integer) the time to wait (milliseconds, | ||
+ | |||
+ | === 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 javascript> | ||
+ | myObject.waitForBytesWritten(); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - waitTime - (integer) the time to wait (milliseconds, | ||
+ | |||
+ | === 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 javascript> | ||
+ | myObject.waitForReadyRead(); | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - waitTime - (integer) the time to wait (milliseconds, | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | === Exceptions === | ||
+ | * (WaitForReadyReadError) wait for ready read failed | ||
+ | |||
+ | ==== close ==== | ||
+ | Tries to close the process gracefully. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.close(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== kill ==== | ||
+ | Kills the process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.kill(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | ==== terminate ==== | ||
+ | Terminates the process. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.terminate(); | ||
+ | </ | ||
+ | |||
+ | === Returns === | ||
+ | * (Process) this Process | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Events ===== | ||
+ | |||
+ | ==== onError ==== | ||
+ | Called when an error occured. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.onError = function(processError) {}; | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - processError - ([[# | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.onError = function(processError) | ||
+ | { | ||
+ | //Event action | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | ==== onFinished ==== | ||
+ | Called when the process has finished. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.onFinished = function(exitCode, | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - exitCode - (integer) the process' | ||
+ | - exitStatus - ([[# | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.onFinished = function(exitCode, | ||
+ | { | ||
+ | //Event action | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | ==== onReadyReadStandardError ==== | ||
+ | Called when there is data available on the standard error output. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.onReadyReadStandardError = function() {}; | ||
+ | </ | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.onReadyReadStandardError = function() | ||
+ | { | ||
+ | //Event action | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | ==== onReadyReadStandardOutput ==== | ||
+ | Called when there is data available on the standard output. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.onReadyReadStandardOutput = function() {}; | ||
+ | </ | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.onReadyReadStandardOutput = function() | ||
+ | { | ||
+ | //Event action | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | ==== onStarted ==== | ||
+ | Called when the process has started executing. | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.onStarted = function() {}; | ||
+ | </ | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.onStarted = function() | ||
+ | { | ||
+ | //Event action | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | ==== onStateChanged ==== | ||
+ | Called when the process' | ||
+ | |||
+ | === Syntax === | ||
+ | <code javascript> | ||
+ | myObject.onStateChanged = function(newState) {}; | ||
+ | </ | ||
+ | |||
+ | === Arguments === | ||
+ | - newState - ([[# | ||
+ | |||
+ | === Example === | ||
+ | <code javascript> | ||
+ | myObject.onStateChanged = function(newState) | ||
+ | { | ||
+ | //Event action | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | ===== Enumerations ===== | ||
+ | |||
+ | ==== ProcessError ==== | ||
+ | A process error. | ||
+ | |||
+ | === Values === | ||
+ | - FailedToStart: | ||
+ | - 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: | ||
+ | |||
+ | ==== ExitStatus ==== | ||
+ | The process' | ||
+ | |||
+ | === Values === | ||
+ | - NormalExit: the process finished normally | ||
+ | - CrashExit: the process crashed | ||
+ | |||
+ | ==== ProcessState ==== | ||
+ | The process' | ||
+ | |||
+ | === Values === | ||
+ | - NotRunning: the process is not running | ||
+ | - Starting: the process is starting | ||
+ | - Running: the process is running | ||
+ | |||
+ | ==== ProcessChannel ==== | ||
+ | A process' | ||
+ | |||
+ | === Values === | ||
+ | - StandardOutput: | ||
+ | - StandardError: | ||
+ | |||
+ | ==== ProcessChannelMode ==== | ||
+ | A process' | ||
+ | |||
+ | === Values === | ||
+ | - SeparateChannels: | ||
+ | - MergedChannels: | ||
+ | - ForwardedChannels: | ||
+ | |||
+ | ==== OpenMode ==== | ||
+ | A process' | ||
+ | |||
+ | === 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 |