Back to index

enigmail  1.4.3
Public Member Functions | Public Attributes
nsIPipeTransport Interface Reference

The nsIPipeTransport interface executes a file in a new process and communicates with the process using pipes. More...

import "nsIPipeTransport.idl";

Collaboration diagram for nsIPipeTransport:
Collaboration graph
[legend]

List of all members.

Public Member Functions

void initWithWorkDir (in nsIFile executable, in nsIFile cwd, in unsigned long startupFlags)
 Initializes PipeTransport by executing the specified file using the supplied argument list and environment variables.
void openPipe ([array, size_is(argCount)] in wstring args, in unsigned long argCount,[array, size_is(envCount)] in wstring env, in unsigned long envCount, in unsigned long timeoutMS, in string killString, in boolean mergeStderr, in nsIPipeListener stderrConsole)
 Opens a PipeTransport by executing the specified file using the supplied argument list and environment variables.
nsIOutputStream openOutputStream (in unsigned long offset, in unsigned long count, in unsigned long flags)
 Open an output stream on this transport.
nsIRequest readInputStream (in nsIPipeReader reader)
nsIRequest asyncRead (in nsIStreamListener listener, in nsISupports ctxt, in unsigned long offset, in unsigned long count, in unsigned long flags)
 Asynchronously read data from the transport.
void join ()
 Joins STDOUT handling thread (blocking until STDOUT is closed), the process still needs to be terminated to free resources.
void terminate ()
 Terminates process, if active, by closing stdin/stdout/stderr.
void writeSync (in string inputData, in unsigned long inputLength)
 Writes string to process STDIN and flush internal buffers.
void write (in string inputData, in unsigned long inputLength)
 Writes string to process STDIN, allowing to buffer the data internally.
void closeStdin ()
 closes process STDIN (required even if no data is being transmitted)
void writeAsync (in nsIInputStream aFromStream, in unsigned long aCount, in boolean closeAfterWrite)
 Writes stream data to process STDIN (asynchronously), and close inputStream and STDIN after writing, if requested.

Public Attributes

const long PROCESS_DETACHED = 0x01
 detach process after start
const long INHERIT_PROC_ATTRIBS = 0x02
readonly attribute nsIPipeListener stderrConsole
 Returns stderrConsole object used to capture STDERR by default.
readonly attribute
nsIStreamListener 
listener
 Returns listener object to feed data to STDIN (call to OnStopRequest closes STDIN)
attribute unsigned long bufferSegmentSize
attribute unsigned long bufferMaxSize
attribute unsigned long headersMaxSize

Detailed Description

The nsIPipeTransport interface executes a file in a new process and communicates with the process using pipes.

OWNERSHIP AND THREADING MODEL for nsPipeTransport:

nsPipeTransport can be created in any thread with an event queue.

nsPipeTransport lives only in the thread that it was created in.

nsPipeTransport creates a helper thread object, nsStdoutPoller and retains an owning reference to it. nsStdoutPoller also holds a strong reference to a proxy interface (nsIPipeTransportListener) implemented by nsPipeTransport, which is released when the polling thread terminates.

The polling thread terminates when it is "interrupted" by nsPipeTransport or when EOF/error is encountered in reading data from the process STDOUT.

The "terminate" method should always be called to release the process resources when done.

For asynchronous reading, when nsStdoutPoller terminates of its own accord, any stream listener is informed by invoking OnStopRequest. Usually this listener will be the same as the owner of nsPipeTransport. (If the owner initiates the request shutdown by first calling "cancel", then the OnStopRequest method is not invoked, because it is assumed that the listener/owner is already aware of the shutdown.)

Definition at line 92 of file nsIPipeTransport.idl.


Member Function Documentation

nsIRequest nsIPipeTransport::asyncRead ( in nsIStreamListener  listener,
in nsISupports  ctxt,
in unsigned long  offset,
in unsigned long  count,
in unsigned long  flags 
)

Asynchronously read data from the transport.

Parameters:
listener- notify this listener when data is available
ctxt- opaque parameter passed to listener methods
offset- read starting at this offset
count- read this many bytes (pass PRUint32(-1) if unlimited)
flags- optional transport specific flags

closes process STDIN (required even if no data is being transmitted)

void nsIPipeTransport::initWithWorkDir ( in nsIFile  executable,
in nsIFile  cwd,
in unsigned long  startupFlags 
)

Initializes PipeTransport by executing the specified file using the supplied argument list and environment variables.

It is expected that nsIPipeTransport will be embedded in a full-featured channel, which will also act as an async stream observer/listener and forward calls to the actual observer/listener.

Parameters:
executableexecutable file
cwdworking directory for the excutable
startupFlagsflags defining how the process should be created

Joins STDOUT handling thread (blocking until STDOUT is closed), the process still needs to be terminated to free resources.

nsIOutputStream nsIPipeTransport::openOutputStream ( in unsigned long  offset,
in unsigned long  count,
in unsigned long  flags 
)

Open an output stream on this transport.

Parameters:
offset- write starting at this offset
count- write no more than this many bytes (pass PRUint32(-1) if unlimited)
flags- optional transport specific flags
void nsIPipeTransport::openPipe ( [array, size_is(argCount)] in wstring  args,
in unsigned long  argCount,
[array, size_is(envCount)] in wstring  env,
in unsigned long  envCount,
in unsigned long  timeoutMS,
in string  killString,
in boolean  mergeStderr,
in nsIPipeListener  stderrConsole 
)

Opens a PipeTransport by executing the specified file using the supplied argument list and environment variables.

It is expected that nsIPipeTransport will be embedded in a full-featured channel, which will also act as an async stream observer/listener and forward calls to the actual observer/listener.

Parameters:
argsarguments string array (excluding the executable path itself)
envenvironment (variable=value) string array
timeoutMStimeout (in milliseconds) after which the process at the other end of the pipe can be assumed to be dead (if == 0, a default value, usually an hour, is used)
killStringstring to be transmitted to process before it is killed (specify null string, if none)
mergeStderrmerge STDERR with STDOUT
stderrConsolensIPipeListener object to capture STDERR (required if mergeStderr is false)

Terminates process, if active, by closing stdin/stdout/stderr.

void nsIPipeTransport::write ( in string  inputData,
in unsigned long  inputLength 
)

Writes string to process STDIN, allowing to buffer the data internally.

I.e. it is not guaranteed that writing is performed immediately. (Note: child process may exit for valid reasons even before the first call to writeSync, causing an an exception to be thrown because STDIN has been closed by the child.)

void nsIPipeTransport::writeAsync ( in nsIInputStream  aFromStream,
in unsigned long  aCount,
in boolean  closeAfterWrite 
)

Writes stream data to process STDIN (asynchronously), and close inputStream and STDIN after writing, if requested.

void nsIPipeTransport::writeSync ( in string  inputData,
in unsigned long  inputLength 
)

Writes string to process STDIN and flush internal buffers.

(Note: child process may exit for valid reasons even before the first call to writeSync, causing an an exception to be thrown because STDIN has been closed by the child.)


Member Data Documentation

attribute unsigned long nsIPipeTransport::bufferMaxSize

Definition at line 228 of file nsIPipeTransport.idl.

attribute unsigned long nsIPipeTransport::bufferSegmentSize

Definition at line 227 of file nsIPipeTransport.idl.

attribute unsigned long nsIPipeTransport::headersMaxSize

Definition at line 229 of file nsIPipeTransport.idl.

Definition at line 144 of file nsIPipeTransport.idl.

readonly attribute nsIStreamListener nsIPipeTransport::listener

Returns listener object to feed data to STDIN (call to OnStopRequest closes STDIN)

Definition at line 155 of file nsIPipeTransport.idl.

detach process after start

Definition at line 143 of file nsIPipeTransport.idl.

Returns stderrConsole object used to capture STDERR by default.

Definition at line 149 of file nsIPipeTransport.idl.


The documentation for this interface was generated from the following file: