File:  [mozdev] / protozilla / ipc / public / nsIPipeTransport.idl
Revision 1.11: download - view: text, annotated - select for diffs - revision graph
Sun Aug 25 13:27:11 2002 UTC (17 years, 6 months ago) by saravn
Branches: MAIN
CVS tags: ipc-1-0-1, HEAD
Improved comment

    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"
   36: #include "nsIPipeListener.idl"
   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: 
   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 : 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)
  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:      * Checks if process is still actively piping I/O
  176:      */
  177:     boolean isAttached();
  178: 
  179:     /**
  180:      * Joins STDOUT handling thread (blocking until STDOUT is closed),
  181:      * (Necessary and only works if noProxy is true)
  182:      * The process still needs to be terminated to free resources.
  183:      */
  184:     void join();
  185: 
  186:     /**
  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:     /**
  198:      * Writes string to process STDIN (synchronously)
  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.)
  202:      */
  203:     void writeSync(in string inputData, in unsigned long inputLength);
  204: 
  205:     /**
  206:      * closes process STDIN (required even if no data is being transmitted)
  207:      */
  208:     void closeStdin();
  209: 
  210:     /**
  211:      * Writes stream data to process STDIN (asynchronously),
  212:      * and close inputStream and STDIN after writing, if requested
  213:      */
  214:     void writeAsync(in nsIInputStream aFromStream,
  215:                     in unsigned long aCount,
  216:                     in boolean closeAfterWrite);
  217: 
  218:     /**
  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,
  273:                   in boolean joinable,
  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:   /**
  287:    * Joins polling thread, if joinable (blocking until it terminates)
  288:    */
  289:   void join();
  290: 
  291:   /**
  292:    * Controls console logging of STDOUT from process
  293:    */
  294:   attribute boolean loggingEnabled;
  295: };
  296: 
  297: 
  298: [noscript, uuid(8431e190-7ab1-11d4-8f02-006008948af5)]
  299: interface nsIPipeTransportWriter : nsISupports
  300: {
  301:   /**
  302:    * writes count bytes from input stream to STDIN pipe (asynchronously) and
  303:    * then closes the STDIN pipe
  304:    */
  305:   void writeFromStream(in nsIInputStream aFromStream,
  306:                        in unsigned long aCount,
  307:                        in IPCFileDescStar pipe,
  308:                        in boolean closeAfterWrite);
  309: };
  310: 
  311: 
  312: ///////////////////////////////////////////////////////////////////////////////

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