File:  [mozdev] / protozilla / ipc / public / nsIPipeTransport.idl
Revision 1.7: download - view: text, annotated - select for diffs - revision graph
Sat Apr 6 08:09:51 2002 UTC (17 years, 10 months ago) by saravn
Branches: MAIN
CVS tags: ipc-0-99-9, HEAD
IPC 1.0 for Mozilla 1.0; added charset parameter to newStringChannel; added preInput parameter to execPipe and execAsync; added write method to PipeTransport

    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: #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 usePolling  use PR_Poll to poll pipes (doesn't work on Win32)
  110:      * @param mergeStderr merge STDERR with STDOUT
  111:      * @param console     nsIPipeConsole object to capture STDERR
  112:      * @param joinConsole join STDERR console on encountering EOF on STDOUT
  113:      *                    (i.e., wait for EOF on STDERR as well)
  114:      */
  115: 
  116:     void init(in string executable,
  117:               [array, size_is(argCount)] in string args,
  118:               in unsigned long argCount,
  119:               [array, size_is(envCount)] in string env,
  120:               in unsigned long envCount,
  121:               in unsigned long timeoutMS,
  122:               in string killString,
  123:               in boolean usePolling,
  124:               in boolean mergeStderr,
  125:               in nsIPipeConsole console,
  126:               in boolean joinConsole);
  127: 
  128:     /**
  129:      * Initializes PipeTransport by executing the specified command line,
  130:      * using the supplied environment variables.
  131:      *
  132:      * @param command  command line string (executable + arguments)
  133:      *                 (Remember to escape any backslashes etc. in arguments)
  134:      * @param env         environment (variable=value) string array
  135:      * @param timeoutMS   timeout (in milliseconds) after which the process
  136:      *                    at the other end of the pipe can be assumed to be
  137:      *                    dead
  138:      *                    (if == 0, a default value, usually an hour, is used)
  139:      * @param killString  string to be transmitted to process before it is
  140:      *                    killed (specify null string, if none)
  141:      * @param usePolling  use PR_Poll to poll pipes (doesn't work on Win32)
  142:      * @param mergeStderr merge STDERR with STDOUT
  143:      * @param console     nsIPipeConsole object to capture STDERR
  144:      * @param joinConsole join STDERR console on encountering EOF on STDOUT
  145:      *                    (i.e., wait for EOF on STDERR as well)
  146:      */
  147:     void initCommand(in string command,
  148:               [array, size_is(envCount)] in string env,
  149:               in unsigned long envCount,
  150:               in unsigned long timeoutMS,
  151:               in string killString,
  152:               in boolean usePolling,
  153:               in boolean mergeStderr,
  154:               in nsIPipeConsole console,
  155:               in boolean joinConsole);
  156: 
  157:     /**
  158:      * Returns console object used to capture STDERR by default
  159:      */
  160:     readonly attribute nsIPipeConsole console;
  161: 
  162:     /**
  163:      * Specifies interface to handle MIME headers read from STDOUT
  164:      */
  165:     attribute nsIPipeTransportHeaders headerProcessor;
  166: 
  167:     /**
  168:      * Controls console logging of STDOUT from process
  169:      */
  170:     attribute boolean loggingEnabled;
  171: 
  172:     /**
  173:      * Checks if process is still actively piping I/O
  174:      */
  175:     boolean isAttached();
  176: 
  177:     /**
  178:      * Terminates process, if active.
  179:      */
  180:     void terminate();
  181: 
  182:     /**
  183:      * Returns exit code of process which has exited;
  184:      *  fails with an exception if process is still attached.
  185:      */
  186:     long exitCode();
  187: 
  188:     /**
  189:      * Writes string to process STDIN (synchronously)
  190:      */
  191:     void write(in string inputData, in unsigned long inputLength);
  192: 
  193:     /**
  194:      * Writes string to process STDIN (asynchronously) and closes STDIN
  195:      */
  196:     void writeAndClose(in string inputData, in unsigned long inputLength);
  197: 
  198:     /**
  199:      * Transmits command string to process, blocks for output and returns the
  200:      * STDOUT response as a string upto maxChars (=-1 for unlimited) long,
  201:      * delimited by an optional prompt.
  202:      * If prompt begins with newline, that newline character is returned,
  203:      * but the rest of the prompt string is not returned.
  204:      * If clear is true, any prior data in STDOUT is cleared.
  205:      */
  206: 
  207:     string execPrompt(in string command, in string prompt,
  208:                       in long maxOutputLen, in boolean clearPrev);
  209: 
  210:     attribute unsigned long bufferSegmentSize;
  211:     attribute unsigned long bufferMaxSize;
  212:     attribute unsigned long headersMaxSize;
  213: 
  214: };
  215: 
  216: 
  217: [scriptable, uuid(8431e110-7ab1-11d4-8f02-006008948af5)]
  218: interface nsIPipeTransportHeaders : nsISupports
  219: {
  220:   /**
  221:    * Calls channel to parse MIME headers, returning content length
  222:    * or -1 for unknown content length.
  223:    * If invalid MIME headers or no channel set, returns error.
  224:    */
  225:   long parseMimeHeaders(in string mimeHeaders, in unsigned long count);
  226: };
  227: 
  228: 
  229: [scriptable, uuid(8431e120-7ab1-11d4-8f02-006008948af5)]
  230: interface nsIPipeTransportListener : nsIPipeTransportHeaders
  231: {
  232:   /**
  233:    * Starts listener, and invokes OnStartRequest on listener, if any.
  234:    * NOTE: Should not be called if blocked for synchronous read.
  235:    */
  236:   void startRequest();
  237: 
  238:   /**
  239:    * Stops listener
  240:    */
  241:   void stopRequest(in nsresult status);
  242: };
  243: 
  244: 
  245: [noscript, uuid(8431e130-7ab1-11d4-8f02-006008948af5)]
  246: interface nsIPipeTransportPoller : nsISupports
  247: {
  248:   /**
  249:    * Starts polling of STDOUT
  250:    */
  251:   void asyncStart(in nsIOutputStream aOutputStream,
  252:                   in nsIPipeTransportListener aProxyPipeObserver,
  253:                   in unsigned long aMimeHeadersMaxSize);
  254: 
  255:   /**
  256:    * Interrupts polling thread.
  257:    */
  258:   boolean interrupt();
  259: 
  260:   /**
  261:    * Returns true if polling thread has been interrupted/
  262:    */
  263:   boolean isInterrupted();
  264: 
  265:   /**
  266:    * Controls console logging of STDOUT from process
  267:    */
  268:   attribute boolean loggingEnabled;
  269: };
  270: 
  271: 
  272: [ptr] native IPCFileDescStar(IPCFileDesc);
  273: 
  274: [noscript, uuid(8431e190-7ab1-11d4-8f02-006008948af5)]
  275: interface nsIPipeTransportWriter : nsISupports
  276: {
  277:   /**
  278:    * writes string data to pipe (asynchronously) and then closes the pipe
  279:    */
  280:   void writeAndClose(in string inputData, in unsigned long inputLength,
  281:                      in IPCFileDescStar pipe);
  282: };
  283: 
  284: 
  285: ///////////////////////////////////////////////////////////////////////////////

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