1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/b2g/simulator/packages/subprocess/README.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,124 @@
1.4 +<h2>What's that?</h2>
1.5 +Simply package enigmail hard work on providing IPC feature in mozilla platform.
1.6 +So we are able to launch child proccesses from javascript,
1.7 +and in our case, from addon-sdk libraries :)
1.8 +
1.9 +<h2>Sample of code:</h2>
1.10 + This object allows to start a process, and read/write data to/from it
1.11 + using stdin/stdout/stderr streams.
1.12 + Usage example:
1.13 +
1.14 + const subprocess = require("subprocess");
1.15 + var p = subprocess.call({
1.16 + command: '/bin/foo',
1.17 + arguments: ['-v', 'foo'],
1.18 + environment: [ "XYZ=abc", "MYVAR=def" ],
1.19 + charset: 'UTF-8',
1.20 + workdir: '/home/foo',
1.21 + //stdin: "some value to write to stdin\nfoobar",
1.22 + stdin: function(stdin) {
1.23 + stdin.write("some value to write to stdin\nfoobar");
1.24 + stdin.close();
1.25 + },
1.26 + stdout: function(data) {
1.27 + dump("got data on stdout:" + data + "\n");
1.28 + },
1.29 + stderr: function(data) {
1.30 + dump("got data on stderr:" + data + "\n");
1.31 + },
1.32 + done: function(result) {
1.33 + dump("process terminated with " + result.exitCode + "\n");
1.34 + },
1.35 + mergeStderr: false
1.36 + });
1.37 + p.wait(); // wait for the subprocess to terminate
1.38 + // this will block the main thread,
1.39 + // only do if you can wait that long
1.40 +
1.41 +
1.42 + Description of parameters:
1.43 + --------------------------
1.44 + Apart from <command>, all arguments are optional.
1.45 +
1.46 + command: either a |nsIFile| object pointing to an executable file or a
1.47 + String containing the platform-dependent path to an executable
1.48 + file.
1.49 +
1.50 + arguments: optional string array containing the arguments to the command.
1.51 +
1.52 + environment: optional string array containing environment variables to pass
1.53 + to the command. The array elements must have the form
1.54 + "VAR=data". Please note that if environment is defined, it
1.55 + replaces any existing environment variables for the subprocess.
1.56 +
1.57 + charset: Output is decoded with given charset and a string is returned.
1.58 + If charset is undefined, "UTF-8" is used as default.
1.59 + To get binary data, set this to null and the returned string
1.60 + is not decoded in any way.
1.61 +
1.62 + workdir: optional; String containing the platform-dependent path to a
1.63 + directory to become the current working directory of the subprocess.
1.64 +
1.65 + stdin: optional input data for the process to be passed on standard
1.66 + input. stdin can either be a string or a function.
1.67 + A |string| gets written to stdin and stdin gets closed;
1.68 + A |function| gets passed an object with write and close function.
1.69 + Please note that the write() function will return almost immediately;
1.70 + data is always written asynchronously on a separate thread.
1.71 +
1.72 + stdout: an optional function that can receive output data from the
1.73 + process. The stdout-function is called asynchronously; it can be
1.74 + called mutliple times during the execution of a process.
1.75 + At a minimum at each occurance of \n or \r.
1.76 + Please note that null-characters might need to be escaped
1.77 + with something like 'data.replace(/\0/g, "\\0");'.
1.78 +
1.79 + stderr: an optional function that can receive stderr data from the
1.80 + process. The stderr-function is called asynchronously; it can be
1.81 + called mutliple times during the execution of a process. Please
1.82 + note that null-characters might need to be escaped with
1.83 + something like 'data.replace(/\0/g, "\\0");'.
1.84 + (on windows it only gets called once right now)
1.85 +
1.86 + done: optional function that is called when the process has terminated.
1.87 + The exit code from the process available via result.exitCode. If
1.88 + stdout is not defined, then the output from stdout is available
1.89 + via result.stdout. stderr data is in result.stderr
1.90 +
1.91 + mergeStderr: optional boolean value. If true, stderr is merged with stdout;
1.92 + no data will be provided to stderr.
1.93 +
1.94 +
1.95 + Description of object returned by subprocess.call(...)
1.96 + ------------------------------------------------------
1.97 + The object returned by subprocess.call offers a few methods that can be
1.98 + executed:
1.99 +
1.100 + wait(): waits for the subprocess to terminate. It is not required to use
1.101 + wait; done will be called in any case when the subprocess terminated.
1.102 +
1.103 + kill(hardKill): kill the subprocess. Any open pipes will be closed and
1.104 + done will be called.
1.105 + hardKill [ignored on Windows]:
1.106 + - false: signal the process terminate (SIGTERM)
1.107 + - true: kill the process (SIGKILL)
1.108 +
1.109 +
1.110 + Other methods in subprocess
1.111 + ---------------------------
1.112 +
1.113 + registerDebugHandler(functionRef): register a handler that is called to get
1.114 + debugging information
1.115 + registerLogHandler(functionRef): register a handler that is called to get error
1.116 + messages
1.117 +
1.118 + example:
1.119 + subprocess.registerLogHandler( function(s) { dump(s); } );
1.120 +
1.121 +
1.122 +<h2>Credits:</h2>
1.123 +All enigmail team working on IPC component.
1.124 + The Initial Developer of this code is Jan Gerber.
1.125 + Portions created by Jan Gerber <j@mailb.org>,
1.126 + Patrick Brunschwig (author of almost all code) <patrick@mozilla-enigmail.org>,
1.127 + Ramalingam Saravanan (from enigmail team) <svn@xmlterm.org>
