nsIProcess

This interface represents an executable process.
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Implemented by: @mozilla.org/process/util;1. To create an instance, use:

var process = Components.classes["@mozilla.org/process/util;1"]
              .createInstance(Components.interfaces.nsIProcess);

Method overview

void init(in nsIFile executable);
void initWithPid(in unsigned long pid); Obsolete since Gecko 1.9.2
void kill();
void run(in boolean blocking, [array, size_is(count)] in string args, in unsigned long count);
void runAsync([array, size_is(count)] in string args, in unsigned long count, [optional] in nsIObserver observer, [optional] in boolean holdWeak);
void runw(in boolean blocking, [array, size_is(count)] in wstring args, in unsigned long count);
void runwAsync([array, size_is(count)] in wstring args, in unsigned long count, [optional] in nsIObserver observer, [optional] in boolean holdWeak);

Attributes

Attribute Type Description
exitValue long The value returned by the process upon exit. This is only valid after the process has exited. Read only.
isRunning boolean true if the process is running, otherwise false. Only accurate if the process was run with blocking disabled. Read only.
location nsIFile

The location of the executable file on disk. Read only.

Gecko 1.9.1 note
This attribute is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.
pid unsigned long The process ID of the process. This value is only available after the process has started; in addition, some platforms may not offer this value at all. Read only.
processName string

The name of the process. Read only.

Gecko 1.9.1 note
This attribute is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.
processSignature unsigned long

The process signature. Read only.

Gecko 1.9.1 note
This attribute is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.

Methods

init()

Initializes the nsIProcess with the specified executable file. Once initialized, you can start the process executing by calling run().

Note: This function does not work with application bundles on Mac OS X, see bug 307463 for details.

void init(
  in nsIFile executable
);
Parameters
executable
The nsIFile executable file to be represented by the nsIProcess object.

initWithPid()

Obsolete since Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

Initializes the nsIProcess to represent an existing process, given that process's ID.

Gecko 1.9.1 note
This method is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.

void initWithPid(
  in unsigned long pid
);
Parameters
pid
The process ID to begin to represent.

kill()

Immediately terminates the process represented by the nsIProcess object. This only works if the process was run without blocking enabled.

Gecko 1.9.1 note
Prior to Gecko 1.9.1 (Firefox 3.5), this method did not work on Windows or Mac OS X. Now it does.

void kill();
Parameters

None.

run()

Starts executing the process.

Gecko 1.9.1 note
Prior to Gecko 1.9.1 (Firefox 3.5), this method returned the process ID of the newly executing process. It no longer returns a value.

void run(
  in boolean blocking,
  [array, size_is(count)] in string args,
  in unsigned long count
);
Parameters
blocking
If true, this method will block until the process terminates; if false, the method returns immediately.
args
An array of count arguments, using the native character set, to be passed to the executable on its command line.
count
The number of arguments in the args array.

runAsync()

Asynchronously runs the process with which the object was initialized, optionally calling an observer when the process finishes running.

void runAsync(
  [array, size_is(count)] in string args,
  in unsigned long count,
  in nsIObserver observer, Optional
  in boolean holdWeak Optional
);
Parameters
args
An array of arguments to pass into the process, using the native character set. This array must have count entries.
count
The number of arguments passed in the args array.
observer Optional
An observer that will be notified when the process exits. The observer will receive this nsIProcess instance as the subject and "process-finished" or "process-failed" as the topic. The observer will be notified on the main thread.
holdWeak Optional
If true, a weak reference is used to hold the observer.

runw()

Executes the file this object was initialized with.

void runw(
  in boolean blocking,
  [array, size_is(count)] in wstring args,
  in unsigned long count
);
Parameters
blocking
If true, this method will block until the process terminates; if false, the method returns immediately.
args
An array of count arguments, using UTF-16, to be passed to the executable on its command line.
count
The number of arguments in the args array.

runwAsync()

Asynchronously runs the process with which the object was initialized, optionally calling an observer when the process finishes running.

void runwAsync(
  [array, size_is(count)] in wstring args,
  in unsigned long count,
  in nsIObserver observer, Optional
  in boolean holdWeak Optional
);
Parameters
args
An array of arguments to pass into the process, using UTF-16. This array must have count entries.
count
The number of arguments passed in the args array.
observer Optional
An observer that will be notified when the process exits. The observer will receive this nsIProcess instance as the subject and "process-finished" or "process-failed" as the topic. The observer will be notified on the main thread.
holdWeak Optional
If true, a weak reference is used to hold the observer.

Example

// create an nsIFile for the executable
var file = Components.classes["@mozilla.org/file/local;1"]
                     .createInstance(Components.interfaces.nsIFile);
file.initWithPath("c:\\myapp.exe");

// create an nsIProcess
var process = Components.classes["@mozilla.org/process/util;1"]
                        .createInstance(Components.interfaces.nsIProcess);
process.init(file);

// Run the process.
// If first param is true, calling thread will be blocked until
// called process terminates.
// Second and third params are used to pass command-line arguments
// to the process.
var args = ["argument1", "argument2"];
process.run(false, args, args.length);

See also