mozilla
Your Search Results

    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.

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

    initWithPid()

    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.

    Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

    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.
     

    Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

    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.

    Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

    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