File:  [mozdev] / protozilla / ipc / public / nsIPipeTransport.idl
Revision 1.12: download - view: text, annotated - select for diffs - revision graph
Mon Feb 17 00:01:31 2003 UTC (17 years ago) by saravn
Branches: MAIN
CVS tags: ipc-1-0-3, ipc-1-0-2, HEAD
Fixes for Moz13b: nsIPipeTransport is no longer derived from nsITransport; the relevant nsITransport methods are now directly defined in nsIPipeTransport

    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 "nsIRequest.idl"
   36: #include "nsIPipeListener.idl"
   37: 
   38: interface nsIRequest;
   39: interface nsIFile;
   40: interface nsIInputStream;
   41: interface nsIOutputStream;
   42: interface nsIStreamListener;
   43: interface nsIPipeTransportHeaders;
   44: interface nsIPipeTransportListener;
   45: 
   46: %{C++
   47: 
   48: #include "IPCProcess.h"
   49: 
   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 : nsIRequest
   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)
  109:      * @param noProxy     do not use proxy for async callback
  110:      *                    (must use join to terminate process, in this case)
  111:      * @param mergeStderr merge STDERR with STDOUT
  112:      * @param console     nsIPipeListener object to capture STDERR
  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,
  122:               in boolean noProxy,
  123:               in boolean mergeStderr,
  124:               in nsIPipeListener console);
  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)
  131:      *                 (Remember to escape any backslashes etc. in arguments)
  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)
  139:      * @param noProxy     do not use proxy for async callback
  140:      *                    (must use join to terminate process, in this case)
  141:      * @param mergeStderr merge STDERR with STDOUT
  142:      * @param console     nsIPipeListener object to capture STDERR
  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,
  149:               in boolean noProxy,
  150:               in boolean mergeStderr,
  151:               in nsIPipeListener console);
  152: 
  153:     /**
  154:      * Returns console object used to capture STDERR by default
  155:      */
  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;
  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:      * Open an input stream on this transport.
  176:      *
  177:      * @param offset - read starting at this offset
  178:      * @param count  - read this many bytes (pass PRUint32(-1) if unlimited)
  179:      * @param flags  - optional transport specific flags
  180:      */
  181:     nsIInputStream openInputStream(in unsigned long offset,
  182:                                    in unsigned long count,
  183:                                    in unsigned long flags);
  184: 
  185:     /**
  186:      * Open an output stream on this transport.
  187:      *
  188:      * @param offset - write starting at this offset
  189:      * @param count  - write no more than this many bytes (pass PRUint32(-1) if unlimited)
  190:      * @param flags  - optional transport specific flags
  191:      */
  192:     nsIOutputStream openOutputStream(in unsigned long offset,
  193:                                      in unsigned long count,
  194:                                      in unsigned long flags);
  195: 
  196:     /**
  197:      * Asynchronously read data from the transport.
  198:      *
  199:      * @param listener - notify this listener when data is available
  200:      * @param ctxt     - opaque parameter passed to listener methods
  201:      * @param offset   - read starting at this offset
  202:      * @param count    - read this many bytes (pass PRUint32(-1) if unlimited)
  203:      * @param flags    - optional transport specific flags
  204:      */
  205:     nsIRequest asyncRead(in nsIStreamListener listener,
  206:                          in nsISupports ctxt, 
  207:                          in unsigned long offset,
  208:                          in unsigned long count,
  209:                          in unsigned long flags);
  210: 
  211:     /**
  212:      * Checks if process is still actively piping I/O
  213:      */
  214:     boolean isAttached();
  215: 
  216:     /**
  217:      * Joins STDOUT handling thread (blocking until STDOUT is closed),
  218:      * (Necessary and only works if noProxy is true)
  219:      * The process still needs to be terminated to free resources.
  220:      */
  221:     void join();
  222: 
  223:     /**
  224:      * Terminates process, if active.
  225:      */
  226:     void terminate();
  227: 
  228:     /**
  229:      * Returns exit code of process which has exited;
  230:      *  fails with an exception if process is still attached.
  231:      */
  232:     long exitCode();
  233: 
  234:     /**
  235:      * Writes string to process STDIN (synchronously)
  236:      * (Note: child process may exit for valid reasons even before
  237:      *  the first call to writeSync, causing an an exception to be
  238:      *  thrown because STDIN has been closed by the child.)
  239:      */
  240:     void writeSync(in string inputData, in unsigned long inputLength);
  241: 
  242:     /**
  243:      * closes process STDIN (required even if no data is being transmitted)
  244:      */
  245:     void closeStdin();
  246: 
  247:     /**
  248:      * Writes stream data to process STDIN (asynchronously),
  249:      * and close inputStream and STDIN after writing, if requested
  250:      */
  251:     void writeAsync(in nsIInputStream aFromStream,
  252:                     in unsigned long aCount,
  253:                     in boolean closeAfterWrite);
  254: 
  255:     /**
  256:      * Transmits command string to process, blocks for output and returns the
  257:      * STDOUT response as a string upto maxChars (=-1 for unlimited) long,
  258:      * delimited by an optional prompt.
  259:      * If prompt begins with newline, that newline character is returned,
  260:      * but the rest of the prompt string is not returned.
  261:      * If clear is true, any prior data in STDOUT is cleared.
  262:      */
  263: 
  264:     string execPrompt(in string command, in string prompt,
  265:                       in long maxOutputLen, in boolean clearPrev);
  266: 
  267:     attribute unsigned long bufferSegmentSize;
  268:     attribute unsigned long bufferMaxSize;
  269:     attribute unsigned long headersMaxSize;
  270: 
  271: };
  272: 
  273: 
  274: [scriptable, uuid(8431e110-7ab1-11d4-8f02-006008948af5)]
  275: interface nsIPipeTransportHeaders : nsISupports
  276: {
  277:   /**
  278:    * Calls channel to parse MIME headers, returning content length
  279:    * or -1 for unknown content length.
  280:    * If invalid MIME headers or no channel set, returns error.
  281:    */
  282:   long parseMimeHeaders(in string mimeHeaders, in unsigned long count);
  283: };
  284: 
  285: 
  286: [scriptable, uuid(8431e120-7ab1-11d4-8f02-006008948af5)]
  287: interface nsIPipeTransportListener : nsIPipeTransportHeaders
  288: {
  289:   /**
  290:    * Starts listener, and invokes OnStartRequest on listener, if any.
  291:    * NOTE: Should not be called if blocked for synchronous read.
  292:    */
  293:   void startRequest();
  294: 
  295:   /**
  296:    * Stops listener
  297:    */
  298:   void stopRequest(in nsresult status);
  299: };
  300: 
  301: 
  302: [noscript, uuid(8431e130-7ab1-11d4-8f02-006008948af5)]
  303: interface nsIPipeTransportPoller : nsISupports
  304: {
  305:   /**
  306:    * Starts polling of STDOUT
  307:    */
  308:   void asyncStart(in nsIOutputStream aOutputStream,
  309:                   in nsIPipeTransportListener aProxyPipeObserver,
  310:                   in boolean joinable,
  311:                   in unsigned long aMimeHeadersMaxSize);
  312: 
  313:   /**
  314:    * Interrupts polling thread.
  315:    */
  316:   boolean interrupt();
  317: 
  318:   /**
  319:    * Returns true if polling thread has been interrupted/
  320:    */
  321:   boolean isInterrupted();
  322: 
  323:   /**
  324:    * Joins polling thread, if joinable (blocking until it terminates)
  325:    */
  326:   void join();
  327: 
  328:   /**
  329:    * Controls console logging of STDOUT from process
  330:    */
  331:   attribute boolean loggingEnabled;
  332: };
  333: 
  334: 
  335: [noscript, uuid(8431e190-7ab1-11d4-8f02-006008948af5)]
  336: interface nsIPipeTransportWriter : nsISupports
  337: {
  338:   /**
  339:    * writes count bytes from input stream to STDIN pipe (asynchronously) and
  340:    * then closes the STDIN pipe
  341:    */
  342:   void writeFromStream(in nsIInputStream aFromStream,
  343:                        in unsigned long aCount,
  344:                        in IPCFileDescStar pipe,
  345:                        in boolean closeAfterWrite);
  346: };
  347: 
  348: 
  349: ///////////////////////////////////////////////////////////////////////////////

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