File:  [mozdev] / protozilla / ipc / public / nsIIPCService.idl
Revision 1.7: download - view: text, annotated - select for diffs - revision graph
Thu May 30 05:02:05 2002 UTC (17 years, 6 months ago) by saravn
Branches: MAIN
CVS tags: ipc-1-0-3, ipc-1-0-2, ipc-1-0-1, ipc-1-0-0-branch-for-mozilla-trunk, ipc-1-0-0-2, ipc-1-0-0-1, ipc-1-0-0, ipc-0-99-63, ipc-0-99-62, ipc-0-99-60, HEAD
Added version property; bundling string implementation with IPC DLL

/*
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "MPL"); you may not use this file
 * except in compliance with the MPL. You may obtain a copy of
 * the MPL at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the MPL is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the MPL for the specific language governing
 * rights and limitations under the MPL.
 * 
 * The Original Code is protoZilla.
 * 
 * The Initial Developer of the Original Code is Ramalingam Saravanan.
 * Portions created by Ramalingam Saravanan <svn@xmlterm.org> are
 * Copyright (C) 2000 Ramalingam Saravanan. All Rights Reserved.
 * 
 * Contributor(s):
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License (the "GPL"), in which case
 * the provisions of the GPL are applicable instead of
 * those above. If you wish to allow use of your version of this
 * file only under the terms of the GPL and not to allow
 * others to use your version of this file under the MPL, indicate
 * your decision by deleting the provisions above and replace them
 * with the notice and other provisions required by the GPL.
 * If you do not delete the provisions above, a recipient
 * may use your version of this file under either the MPL or the
 * GPL.
 */

#include "nsIPipeTransport.idl"
#include "nsIPipeConsole.idl"

interface nsIURI;
interface nsIChannel;
interface nsIRequestObserver;
interface nsIIPCRequest;

%{C++
#define NS_IPCSERVICE_CLASSNAME  "IPCService"
#define NS_IPCSERVICE_CONTRACTID "@mozilla.org/process/ipc-service;1"
     
#define NS_IPCSERVICE_CID                        \
{ /* 8431e161-7ab1-11d4-8f02-006008948af5 */     \
   0x8431e161, 0x7ab1, 0x11d4,                   \
{0x8f, 0x02, 0x00, 0x60, 0x08, 0x94, 0x8a, 0xf5} }

%}

/**
 * The nsIIPCService interface provides helper services for pipe-based
 * protocols.
 */
[scriptable, uuid(8431e160-7ab1-11d4-8f02-006008948af5)]
interface nsIIPCService : nsISupports
{

  /* NOTE: In output string values, the NUL character is escaped as follows:
   *   NUL -> DEL '0'
   *   DEL -> DEL DEL
   * This allows raw binary data to be returned as NUL-delimited strings.
   */

  /** 
   * Returns version of IPC Module
   */
  readonly attribute string version;

  /**
   * Executes command and returns the standard output emitted by the command
   * as a string. (Uses shell expansion)
   * This method blocks for the completion of the command.
   */
  string execSh(in string command);

  /**
   * Executes command and returns the standard output emitted by the command
   * as a string. No shell expansion is carried out.
   * Unquoting (stripping quotes/backaslashes) is always done.
   * This method blocks for the completion of the command.
   */
  string exec(in string command);

  /**
   * Executes command, with optional data for standard input,
   * and returns the exit code from the process. The standard output
   * and standard error strings are returned as "out" arguments.
   * (If outputError is null, use default console to capture error output.)
   * UseShell controls shell expansion.
   * PreInput may be used for passphrases etc.
   * Unquoting the command (stripping quotes/backaslashes) is always done.
   * This method blocks for the completion of the command.
   */
  long execPipe(in string command,
                in boolean useShell,
                in string preInput,
                in string inputData,
                in unsigned long inputLength,
                [array, size_is(envCount)] in string env,
                in unsigned long envCount,
                [size_is(outputCount)] out string outputData,
                out unsigned long outputCount,
                [size_is(errorCount)] out string outputError,
                out unsigned long errorCount);

  /**
   * Executes command, with optional data for standard input,
   * and asynchronously captures the standard output (and standard error
   * output) in supplied console(s). This method does not block for
   * command completion, unlike the other exec methods. The nsIIPCRequest
   * object associated with the command execution is returned, and may
   * be used to determine request status or cancel it.
   * If an nsIRequestObserver object is suppled, then it is used to
   * "observe" the standard output console, and the nsIIPCRequest object
   * is automatically supplied as the context argument to the observer.
   * 
   * UseShell controls shell expansion.
   * PreInput may be used for passphrases etc.
   * Unquoting the command (stripping quotes/backslashes) is always done.
   */
  nsIIPCRequest execAsync(in string command,
                          in boolean useShell,
                          in string preInput,
                          in string inputData,
                          in unsigned long inputLength,
                          [array, size_is(envCount)] in string env,
                          in unsigned long envCount,
                          in nsIPipeListener outConsole,
                          in nsIPipeListener errConsole,
                          in nsIRequestObserver requestObserver);

  /**
   * Returns console object used to capture STDERR by default
   */
  readonly attribute nsIPipeConsole console;

  /**
   * Returns "random" portion of current time, combining
   * microsecond values for current local time and
   * millisecond values for elapsed time
   */
  unsigned long getRandomTime();

  /**
   * Returns random number with specified number of digits,
   * in hexadecimal format.
   * CAUTION: This call uses the entropy source, which may cause the
   * calling thread to block until sufficient entropy is collected.
   */
  string getRandomHex(in unsigned long nDigits);

  /** 
   * Returns secret random cookie used for security
   */
  readonly attribute string cookie;

  /**
   * Creates scriptable schannel from input string data.
   */
  nsIChannel newStringChannel(in nsIURI uri, in AUTF8String contentType,
                              in AUTF8String contentCharset,
                              in string channelData);
};

[scriptable, uuid(8431e1A0-7ab1-11d4-8f02-006008948af5)]
interface nsIIPCRequest : nsISupports
{
  void init(in string command, in nsIPipeTransport pipeTransport,
            in nsIPipeListener stdoutConsole, in nsIPipeListener stderrConsole);

  /**
   * Returns true if the request is still pending
   */
  boolean isPending();

  /**
   * Terminates the pipeTransport associated with the request.
   * If CloseConsoles is true, the stdout/stderr consoles are also closed.
   */
  void close(in boolean closeConsoles);

  readonly attribute string command;

  readonly attribute nsIPipeTransport pipeTransport;

  readonly attribute nsIPipeListener stdoutConsole;
  readonly attribute nsIPipeListener stderrConsole;
};

///////////////////////////////////////////////////////////////////////////////

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