Annotation of protozilla/ipc/public/nsIPipeTransport.idl, revision 1.11

1.1       saravn      1: /*
                      2:  * The contents of this file are subject to the Mozilla Public
                      3:  * License Version 1.1 (the "MPL"); you may not use this file
                      4:  * except in compliance with the MPL. You may obtain a copy of
                      5:  * the MPL at http://www.mozilla.org/MPL/
                      6:  * 
                      7:  * Software distributed under the MPL is distributed on an "AS
                      8:  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
                      9:  * implied. See the MPL for the specific language governing
                     10:  * rights and limitations under the MPL.
                     11:  * 
                     12:  * The Original Code is protoZilla.
                     13:  * 
                     14:  * The Initial Developer of the Original Code is Ramalingam Saravanan.
                     15:  * Portions created by Ramalingam Saravanan <svn@xmlterm.org> are
                     16:  * Copyright (C) 2000 Ramalingam Saravanan. All Rights Reserved.
                     17:  * 
                     18:  * Contributor(s):
                     19:  * 
                     20:  * Alternatively, the contents of this file may be used under the
                     21:  * terms of the GNU General Public License (the "GPL"), in which case
                     22:  * the provisions of the GPL are applicable instead of
                     23:  * those above. If you wish to allow use of your version of this
                     24:  * file only under the terms of the GPL and not to allow
                     25:  * others to use your version of this file under the MPL, indicate
                     26:  * your decision by deleting the provisions above and replace them
                     27:  * with the notice and other provisions required by the GPL.
                     28:  * If you do not delete the provisions above, a recipient
                     29:  * may use your version of this file under either the MPL or the
                     30:  * GPL.
                     31:  */
                     32: 
                     33: #include "nsISupports.idl"
                     34: #include "nsIPipe.idl"
                     35: #include "nsITransport.idl"
1.9       saravn     36: #include "nsIPipeListener.idl"
1.1       saravn     37: 
                     38: interface nsITransport;
                     39: interface nsIFile;
                     40: interface nsIInputStream;
                     41: interface nsIOutputStream;
                     42: interface nsIStreamListener;
                     43: interface nsIPipeTransportHeaders;
                     44: interface nsIPipeTransportListener;
                     45: 
                     46: %{C++
                     47: 
1.4       saravn     48: #include "IPCProcess.h"
                     49: 
1.1       saravn     50: #define NS_PIPETRANSPORT_CLASSNAME "Pipe Transport"
                     51: #define NS_PIPETRANSPORT_CONTRACTID "@mozilla.org/process/pipe-transport;1"
                     52:      
                     53: #define NS_PIPETRANSPORT_CID                     \
                     54: { /* 8431e101-7ab1-11d4-8f02-006008948af5 */     \
                     55:    0x8431e101, 0x7ab1, 0x11d4,                   \
                     56: {0x8f, 0x02, 0x00, 0x60, 0x08, 0x94, 0x8a, 0xf5} }
                     57: 
                     58: %}
                     59: 
                     60: /**
                     61:  * The nsIPipeTransport interface executes a file in a new process and
                     62:  * communicates with the process using pipes.
                     63:  *
                     64:  * OWNERSHIP AND THREADING MODEL for nsPipeTransport:
                     65:  *
                     66:  * nsPipeTransport can be created in any thread with an event queue.
                     67:  *
                     68:  * nsPipeTransport lives only in the thread that it was created in.
                     69:  *
                     70:  * nsPipeTransport creates a helper thread object, nsStdoutPoller and retains
                     71:  * an owning reference to it. nsStdoutPoller also holds a strong reference
                     72:  * to a proxy interface (nsIPipeTransportListener) implemented by
                     73:  * nsPipeTransport, which is released when the polling thread terminates.
                     74:  *
                     75:  * The polling thread terminates when it is "interrupted" by nsPipeTransport or
                     76:  * when EOF/error is encountered in reading data from the process STDOUT.
                     77:  *
                     78:  * The "terminate" method should *always* be called to release the process
                     79:  * resources when done.
                     80:  *
                     81:  * For asynchronous reading, when nsStdoutPoller terminates of its own accord,
                     82:  * any stream listener is informed by invoking OnStopRequest.
                     83:  * Usually this listener will be the same as the owner of nsPipeTransport.
                     84:  * (If the owner initiates the request shutdown by first calling "cancel",
                     85:  *  then the OnStopRequest method is *not* invoked, because it is assumed
                     86:  *  that the listener/owner is already aware of the shutdown.)
                     87:  *
                     88:  */
                     89: [scriptable, uuid(8431e100-7ab1-11d4-8f02-006008948af5)]
                     90: interface nsIPipeTransport : nsITransport
                     91: {
                     92:     /**
                     93:      * Initializes PipeTransport by executing the specified file using the
                     94:      * supplied argument list and environment variables.
                     95:      * It is expected that nsIPipeTransport will be embedded in a
                     96:      * full-featured channel, which will also act as an async stream
                     97:      * observer/listener and forward calls to the actual observer/listener.
                     98:      *
                     99:      * @param executable  path of executable file
                    100:      * @param args        arguments string array
                    101:      *                    (excluding the executable path itself)
                    102:      * @param env         environment (variable=value) string array
                    103:      * @param timeoutMS   timeout (in milliseconds) after which the process
                    104:      *                    at the other end of the pipe can be assumed to be
                    105:      *                    dead
                    106:      *                    (if == 0, a default value, usually an hour, is used)
                    107:      * @param killString  string to be transmitted to process before it is
                    108:      *                    killed (specify null string, if none)
1.8       saravn    109:      * @param noProxy     do not use proxy for async callback
                    110:      *                    (must use join to terminate process, in this case)
1.1       saravn    111:      * @param mergeStderr merge STDERR with STDOUT
1.9       saravn    112:      * @param console     nsIPipeListener object to capture STDERR
1.1       saravn    113:      */
                    114: 
                    115:     void init(in string executable,
                    116:               [array, size_is(argCount)] in string args,
                    117:               in unsigned long argCount,
                    118:               [array, size_is(envCount)] in string env,
                    119:               in unsigned long envCount,
                    120:               in unsigned long timeoutMS,
                    121:               in string killString,
1.8       saravn    122:               in boolean noProxy,
1.1       saravn    123:               in boolean mergeStderr,
1.9       saravn    124:               in nsIPipeListener console);
1.1       saravn    125: 
                    126:     /**
                    127:      * Initializes PipeTransport by executing the specified command line,
                    128:      * using the supplied environment variables.
                    129:      *
                    130:      * @param command  command line string (executable + arguments)
1.2       saravn    131:      *                 (Remember to escape any backslashes etc. in arguments)
1.1       saravn    132:      * @param env         environment (variable=value) string array
                    133:      * @param timeoutMS   timeout (in milliseconds) after which the process
                    134:      *                    at the other end of the pipe can be assumed to be
                    135:      *                    dead
                    136:      *                    (if == 0, a default value, usually an hour, is used)
                    137:      * @param killString  string to be transmitted to process before it is
                    138:      *                    killed (specify null string, if none)
1.8       saravn    139:      * @param noProxy     do not use proxy for async callback
                    140:      *                    (must use join to terminate process, in this case)
1.1       saravn    141:      * @param mergeStderr merge STDERR with STDOUT
1.9       saravn    142:      * @param console     nsIPipeListener object to capture STDERR
1.1       saravn    143:      */
                    144:     void initCommand(in string command,
                    145:               [array, size_is(envCount)] in string env,
                    146:               in unsigned long envCount,
                    147:               in unsigned long timeoutMS,
                    148:               in string killString,
1.8       saravn    149:               in boolean noProxy,
1.1       saravn    150:               in boolean mergeStderr,
1.9       saravn    151:               in nsIPipeListener console);
1.1       saravn    152: 
                    153:     /**
                    154:      * Returns console object used to capture STDERR by default
                    155:      */
1.9       saravn    156:     readonly attribute nsIPipeListener console;
                    157: 
                    158:     /**
                    159:      * Returns listener object to feed data to STDIN
                    160:      * (call to OnStopRequest closes STDIN)
                    161:      */
                    162:     readonly attribute nsIStreamListener listener;
1.1       saravn    163: 
                    164:     /**
                    165:      * Specifies interface to handle MIME headers read from STDOUT
                    166:      */
                    167:     attribute nsIPipeTransportHeaders headerProcessor;
                    168: 
                    169:     /**
                    170:      * Controls console logging of STDOUT from process
                    171:      */
                    172:     attribute boolean loggingEnabled;
                    173: 
                    174:     /**
                    175:      * Checks if process is still actively piping I/O
                    176:      */
1.6       saravn    177:     boolean isAttached();
1.1       saravn    178: 
                    179:     /**
1.9       saravn    180:      * Joins STDOUT handling thread (blocking until STDOUT is closed),
1.8       saravn    181:      * (Necessary and only works if noProxy is true)
1.9       saravn    182:      * The process still needs to be terminated to free resources.
1.8       saravn    183:      */
                    184:     void join();
                    185: 
                    186:     /**
1.1       saravn    187:      * Terminates process, if active.
                    188:      */
                    189:     void terminate();
                    190: 
                    191:     /**
                    192:      * Returns exit code of process which has exited;
                    193:      *  fails with an exception if process is still attached.
                    194:      */
                    195:     long exitCode();
                    196: 
                    197:     /**
1.7       saravn    198:      * Writes string to process STDIN (synchronously)
1.11    ! saravn    199:      * (Note: child process may exit for valid reasons even before
        !           200:      *  the first call to writeSync, causing an an exception to be
        !           201:      *  thrown because STDIN has been closed by the child.)
1.7       saravn    202:      */
1.9       saravn    203:     void writeSync(in string inputData, in unsigned long inputLength);
1.7       saravn    204: 
                    205:     /**
1.10      saravn    206:      * closes process STDIN (required even if no data is being transmitted)
                    207:      */
                    208:     void closeStdin();
                    209: 
                    210:     /**
1.8       saravn    211:      * Writes stream data to process STDIN (asynchronously),
                    212:      * and close inputStream and STDIN after writing, if requested
1.4       saravn    213:      */
1.9       saravn    214:     void writeAsync(in nsIInputStream aFromStream,
                    215:                     in unsigned long aCount,
                    216:                     in boolean closeAfterWrite);
1.4       saravn    217: 
                    218:     /**
1.1       saravn    219:      * Transmits command string to process, blocks for output and returns the
                    220:      * STDOUT response as a string upto maxChars (=-1 for unlimited) long,
                    221:      * delimited by an optional prompt.
                    222:      * If prompt begins with newline, that newline character is returned,
                    223:      * but the rest of the prompt string is not returned.
                    224:      * If clear is true, any prior data in STDOUT is cleared.
                    225:      */
                    226: 
                    227:     string execPrompt(in string command, in string prompt,
                    228:                       in long maxOutputLen, in boolean clearPrev);
                    229: 
                    230:     attribute unsigned long bufferSegmentSize;
                    231:     attribute unsigned long bufferMaxSize;
                    232:     attribute unsigned long headersMaxSize;
                    233: 
                    234: };
                    235: 
                    236: 
                    237: [scriptable, uuid(8431e110-7ab1-11d4-8f02-006008948af5)]
                    238: interface nsIPipeTransportHeaders : nsISupports
                    239: {
                    240:   /**
                    241:    * Calls channel to parse MIME headers, returning content length
                    242:    * or -1 for unknown content length.
                    243:    * If invalid MIME headers or no channel set, returns error.
                    244:    */
                    245:   long parseMimeHeaders(in string mimeHeaders, in unsigned long count);
                    246: };
                    247: 
                    248: 
                    249: [scriptable, uuid(8431e120-7ab1-11d4-8f02-006008948af5)]
                    250: interface nsIPipeTransportListener : nsIPipeTransportHeaders
                    251: {
                    252:   /**
                    253:    * Starts listener, and invokes OnStartRequest on listener, if any.
                    254:    * NOTE: Should not be called if blocked for synchronous read.
                    255:    */
                    256:   void startRequest();
                    257: 
                    258:   /**
                    259:    * Stops listener
                    260:    */
                    261:   void stopRequest(in nsresult status);
                    262: };
                    263: 
                    264: 
                    265: [noscript, uuid(8431e130-7ab1-11d4-8f02-006008948af5)]
                    266: interface nsIPipeTransportPoller : nsISupports
                    267: {
                    268:   /**
                    269:    * Starts polling of STDOUT
                    270:    */
                    271:   void asyncStart(in nsIOutputStream aOutputStream,
                    272:                   in nsIPipeTransportListener aProxyPipeObserver,
1.8       saravn    273:                   in boolean joinable,
1.1       saravn    274:                   in unsigned long aMimeHeadersMaxSize);
                    275: 
                    276:   /**
                    277:    * Interrupts polling thread.
                    278:    */
                    279:   boolean interrupt();
                    280: 
                    281:   /**
                    282:    * Returns true if polling thread has been interrupted/
                    283:    */
                    284:   boolean isInterrupted();
                    285: 
                    286:   /**
1.8       saravn    287:    * Joins polling thread, if joinable (blocking until it terminates)
                    288:    */
                    289:   void join();
                    290: 
                    291:   /**
1.1       saravn    292:    * Controls console logging of STDOUT from process
                    293:    */
                    294:   attribute boolean loggingEnabled;
1.4       saravn    295: };
                    296: 
                    297: 
                    298: [noscript, uuid(8431e190-7ab1-11d4-8f02-006008948af5)]
                    299: interface nsIPipeTransportWriter : nsISupports
                    300: {
                    301:   /**
1.8       saravn    302:    * writes count bytes from input stream to STDIN pipe (asynchronously) and
                    303:    * then closes the STDIN pipe
1.4       saravn    304:    */
1.8       saravn    305:   void writeFromStream(in nsIInputStream aFromStream,
                    306:                        in unsigned long aCount,
                    307:                        in IPCFileDescStar pipe,
                    308:                        in boolean closeAfterWrite);
1.1       saravn    309: };
                    310: 
                    311: 
                    312: ///////////////////////////////////////////////////////////////////////////////

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>