File:  [mozdev] / protozilla / ipc / public / nsIPipeTransport.idl
Revision 1.3: download - view: text, annotated - select for diffs - revision graph
Thu Nov 8 21:15:33 2001 UTC (18 years, 3 months ago) by saravn
Branches: MAIN
CVS tags: HEAD
Version 0.95.0: moved shell handling from PipeTransport to IPCService

    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: 
   37: interface nsITransport;
   38: interface nsIFile;
   39: interface nsIInputStream;
   40: interface nsIOutputStream;
   41: interface nsIStreamListener;
   42: interface nsIPipeTransportHeaders;
   43: interface nsIPipeTransportListener;
   44: interface nsIPipeConsole;
   45: 
   46: %{C++
   47: 
   48: #define NS_PIPETRANSPORT_CLASSNAME "Pipe Transport"
   49: #define NS_PIPETRANSPORT_CONTRACTID "@mozilla.org/process/pipe-transport;1"
   50:      
   51: #define NS_PIPETRANSPORT_CID                     \
   52: { /* 8431e101-7ab1-11d4-8f02-006008948af5 */     \
   53:    0x8431e101, 0x7ab1, 0x11d4,                   \
   54: {0x8f, 0x02, 0x00, 0x60, 0x08, 0x94, 0x8a, 0xf5} }
   55: 
   56: %}
   57: 
   58: /**
   59:  * The nsIPipeTransport interface executes a file in a new process and
   60:  * communicates with the process using pipes.
   61:  *
   62:  * OWNERSHIP AND THREADING MODEL for nsPipeTransport:
   63:  *
   64:  * nsPipeTransport can be created in any thread with an event queue.
   65:  *
   66:  * nsPipeTransport lives only in the thread that it was created in.
   67:  *
   68:  * nsPipeTransport creates a helper thread object, nsStdoutPoller and retains
   69:  * an owning reference to it. nsStdoutPoller also holds a strong reference
   70:  * to a proxy interface (nsIPipeTransportListener) implemented by
   71:  * nsPipeTransport, which is released when the polling thread terminates.
   72:  *
   73:  * The polling thread terminates when it is "interrupted" by nsPipeTransport or
   74:  * when EOF/error is encountered in reading data from the process STDOUT.
   75:  *
   76:  * The "terminate" method should *always* be called to release the process
   77:  * resources when done.
   78:  *
   79:  * For asynchronous reading, when nsStdoutPoller terminates of its own accord,
   80:  * any stream listener is informed by invoking OnStopRequest.
   81:  * Usually this listener will be the same as the owner of nsPipeTransport.
   82:  * (If the owner initiates the request shutdown by first calling "cancel",
   83:  *  then the OnStopRequest method is *not* invoked, because it is assumed
   84:  *  that the listener/owner is already aware of the shutdown.)
   85:  *
   86:  */
   87: [scriptable, uuid(8431e100-7ab1-11d4-8f02-006008948af5)]
   88: interface nsIPipeTransport : nsITransport
   89: {
   90:     /**
   91:      * Initializes PipeTransport by executing the specified file using the
   92:      * supplied argument list and environment variables.
   93:      * It is expected that nsIPipeTransport will be embedded in a
   94:      * full-featured channel, which will also act as an async stream
   95:      * observer/listener and forward calls to the actual observer/listener.
   96:      *
   97:      * @param executable  path of executable file
   98:      * @param args        arguments string array
   99:      *                    (excluding the executable path itself)
  100:      * @param env         environment (variable=value) string array
  101:      * @param timeoutMS   timeout (in milliseconds) after which the process
  102:      *                    at the other end of the pipe can be assumed to be
  103:      *                    dead
  104:      *                    (if == 0, a default value, usually an hour, is used)
  105:      * @param killString  string to be transmitted to process before it is
  106:      *                    killed (specify null string, if none)
  107:      * @param usePolling  use PR_Poll to poll pipes (doesn't work on Win32)
  108:      * @param mergeStderr merge STDERR with STDOUT
  109:      * @param console     nsIPipeConsole object to capture STDERR
  110:      */
  111: 
  112:     void init(in string executable,
  113:               [array, size_is(argCount)] in string args,
  114:               in unsigned long argCount,
  115:               [array, size_is(envCount)] in string env,
  116:               in unsigned long envCount,
  117:               in unsigned long timeoutMS,
  118:               in string killString,
  119:               in boolean usePolling,
  120:               in boolean mergeStderr,
  121:               in nsIPipeConsole console);
  122: 
  123:     /**
  124:      * Initializes PipeTransport by executing the specified command line,
  125:      * using the supplied environment variables.
  126:      *
  127:      * @param command  command line string (executable + arguments)
  128:      *                 (Remember to escape any backslashes etc. in arguments)
  129:      * @param env         environment (variable=value) string array
  130:      * @param timeoutMS   timeout (in milliseconds) after which the process
  131:      *                    at the other end of the pipe can be assumed to be
  132:      *                    dead
  133:      *                    (if == 0, a default value, usually an hour, is used)
  134:      * @param killString  string to be transmitted to process before it is
  135:      *                    killed (specify null string, if none)
  136:      * @param usePolling  use PR_Poll to poll pipes (doesn't work on Win32)
  137:      * @param mergeStderr merge STDERR with STDOUT
  138:      * @param console     nsIPipeConsole object to capture STDERR
  139:      */
  140:     void initCommand(in string command,
  141:               [array, size_is(envCount)] in string env,
  142:               in unsigned long envCount,
  143:               in unsigned long timeoutMS,
  144:               in string killString,
  145:               in boolean usePolling,
  146:               in boolean mergeStderr,
  147:               in nsIPipeConsole console);
  148: 
  149:     /**
  150:      * Returns console object used to capture STDERR by default
  151:      */
  152:     readonly attribute nsIPipeConsole console;
  153: 
  154:     /**
  155:      * Specifies interface to handle MIME headers read from STDOUT
  156:      */
  157:     attribute nsIPipeTransportHeaders headerProcessor;
  158: 
  159:     /**
  160:      * Controls console logging of STDOUT from process
  161:      */
  162:     attribute boolean loggingEnabled;
  163: 
  164:     /**
  165:      * Checks if process is still actively piping I/O
  166:      */
  167:     readonly attribute boolean isAttached;
  168: 
  169:     /**
  170:      * Terminates process, if active.
  171:      */
  172:     void terminate();
  173: 
  174:     /**
  175:      * Returns exit code of process which has exited;
  176:      *  fails with an exception if process is still attached.
  177:      */
  178:     long exitCode();
  179: 
  180:     /**
  181:      * Transmits command string to process, blocks for output and returns the
  182:      * STDOUT response as a string upto maxChars (=-1 for unlimited) long,
  183:      * delimited by an optional prompt.
  184:      * If prompt begins with newline, that newline character is returned,
  185:      * but the rest of the prompt string is not returned.
  186:      * If clear is true, any prior data in STDOUT is cleared.
  187:      */
  188: 
  189:     string execPrompt(in string command, in string prompt,
  190:                       in long maxOutputLen, in boolean clearPrev);
  191: 
  192:     attribute unsigned long bufferSegmentSize;
  193:     attribute unsigned long bufferMaxSize;
  194:     attribute unsigned long headersMaxSize;
  195: 
  196: };
  197: 
  198: 
  199: [scriptable, uuid(8431e110-7ab1-11d4-8f02-006008948af5)]
  200: interface nsIPipeTransportHeaders : nsISupports
  201: {
  202:   /**
  203:    * Calls channel to parse MIME headers, returning content length
  204:    * or -1 for unknown content length.
  205:    * If invalid MIME headers or no channel set, returns error.
  206:    */
  207:   long parseMimeHeaders(in string mimeHeaders, in unsigned long count);
  208: };
  209: 
  210: 
  211: [scriptable, uuid(8431e120-7ab1-11d4-8f02-006008948af5)]
  212: interface nsIPipeTransportListener : nsIPipeTransportHeaders
  213: {
  214:   /**
  215:    * Starts listener, and invokes OnStartRequest on listener, if any.
  216:    * NOTE: Should not be called if blocked for synchronous read.
  217:    */
  218:   void startRequest();
  219: 
  220:   /**
  221:    * Stops listener
  222:    */
  223:   void stopRequest(in nsresult status);
  224: };
  225: 
  226: 
  227: [noscript, uuid(8431e130-7ab1-11d4-8f02-006008948af5)]
  228: interface nsIPipeTransportPoller : nsISupports
  229: {
  230:   /**
  231:    * Starts polling of STDOUT
  232:    */
  233:   void asyncStart(in nsIOutputStream aOutputStream,
  234:                   in nsIPipeTransportListener aProxyPipeObserver,
  235:                   in unsigned long aMimeHeadersMaxSize);
  236: 
  237:   /**
  238:    * Interrupts polling thread.
  239:    */
  240:   boolean interrupt();
  241: 
  242:   /**
  243:    * Returns true if polling thread has been interrupted/
  244:    */
  245:   boolean isInterrupted();
  246: 
  247:   /**
  248:    * Controls console logging of STDOUT from process
  249:    */
  250:   attribute boolean loggingEnabled;
  251: };
  252: 
  253: 
  254: ///////////////////////////////////////////////////////////////////////////////

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