File:  [mozdev] / protozilla / ipc / public / nsIPipeTransport.idl
Revision 1.2: download - view: text, annotated - select for diffs - revision graph
Tue Nov 6 22:22:58 2001 UTC (18 years, 3 months ago) by saravn
Branches: MAIN
CVS tags: HEAD
Fixed deadlock bug in PipeConsole. Version 0.15.1

    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 useShell if true, use shell to expand command line
  130:      * @param env         environment (variable=value) string array
  131:      * @param timeoutMS   timeout (in milliseconds) after which the process
  132:      *                    at the other end of the pipe can be assumed to be
  133:      *                    dead
  134:      *                    (if == 0, a default value, usually an hour, is used)
  135:      * @param killString  string to be transmitted to process before it is
  136:      *                    killed (specify null string, if none)
  137:      * @param usePolling  use PR_Poll to poll pipes (doesn't work on Win32)
  138:      * @param mergeStderr merge STDERR with STDOUT
  139:      * @param console     nsIPipeConsole object to capture STDERR
  140:      */
  141:     void initCommand(in string command,
  142:               in boolean useShell,
  143:               [array, size_is(envCount)] in string env,
  144:               in unsigned long envCount,
  145:               in unsigned long timeoutMS,
  146:               in string killString,
  147:               in boolean usePolling,
  148:               in boolean mergeStderr,
  149:               in nsIPipeConsole console);
  150: 
  151:     /**
  152:      * Returns console object used to capture STDERR by default
  153:      */
  154:     readonly attribute nsIPipeConsole console;
  155: 
  156:     /**
  157:      * Specifies interface to handle MIME headers read from STDOUT
  158:      */
  159:     attribute nsIPipeTransportHeaders headerProcessor;
  160: 
  161:     /**
  162:      * Controls console logging of STDOUT from process
  163:      */
  164:     attribute boolean loggingEnabled;
  165: 
  166:     /**
  167:      * Checks if process is still actively piping I/O
  168:      */
  169:     readonly attribute boolean isAttached;
  170: 
  171:     /**
  172:      * Terminates process, if active.
  173:      */
  174:     void terminate();
  175: 
  176:     /**
  177:      * Returns exit code of process which has exited;
  178:      *  fails with an exception if process is still attached.
  179:      */
  180:     long exitCode();
  181: 
  182:     /**
  183:      * Transmits command string to process, blocks for output and returns the
  184:      * STDOUT response as a string upto maxChars (=-1 for unlimited) long,
  185:      * delimited by an optional prompt.
  186:      * If prompt begins with newline, that newline character is returned,
  187:      * but the rest of the prompt string is not returned.
  188:      * If clear is true, any prior data in STDOUT is cleared.
  189:      */
  190: 
  191:     string execPrompt(in string command, in string prompt,
  192:                       in long maxOutputLen, in boolean clearPrev);
  193: 
  194:     attribute unsigned long bufferSegmentSize;
  195:     attribute unsigned long bufferMaxSize;
  196:     attribute unsigned long headersMaxSize;
  197: 
  198: };
  199: 
  200: 
  201: [scriptable, uuid(8431e110-7ab1-11d4-8f02-006008948af5)]
  202: interface nsIPipeTransportHeaders : nsISupports
  203: {
  204:   /**
  205:    * Calls channel to parse MIME headers, returning content length
  206:    * or -1 for unknown content length.
  207:    * If invalid MIME headers or no channel set, returns error.
  208:    */
  209:   long parseMimeHeaders(in string mimeHeaders, in unsigned long count);
  210: };
  211: 
  212: 
  213: [scriptable, uuid(8431e120-7ab1-11d4-8f02-006008948af5)]
  214: interface nsIPipeTransportListener : nsIPipeTransportHeaders
  215: {
  216:   /**
  217:    * Starts listener, and invokes OnStartRequest on listener, if any.
  218:    * NOTE: Should not be called if blocked for synchronous read.
  219:    */
  220:   void startRequest();
  221: 
  222:   /**
  223:    * Stops listener
  224:    */
  225:   void stopRequest(in nsresult status);
  226: };
  227: 
  228: 
  229: [noscript, uuid(8431e130-7ab1-11d4-8f02-006008948af5)]
  230: interface nsIPipeTransportPoller : nsISupports
  231: {
  232:   /**
  233:    * Starts polling of STDOUT
  234:    */
  235:   void asyncStart(in nsIOutputStream aOutputStream,
  236:                   in nsIPipeTransportListener aProxyPipeObserver,
  237:                   in unsigned long aMimeHeadersMaxSize);
  238: 
  239:   /**
  240:    * Interrupts polling thread.
  241:    */
  242:   boolean interrupt();
  243: 
  244:   /**
  245:    * Returns true if polling thread has been interrupted/
  246:    */
  247:   boolean isInterrupted();
  248: 
  249:   /**
  250:    * Controls console logging of STDOUT from process
  251:    */
  252:   attribute boolean loggingEnabled;
  253: };
  254: 
  255: 
  256: ///////////////////////////////////////////////////////////////////////////////

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