/*
 * 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):
 * Patrick Brunschwig <patrick@mozilla-enigmail.org>
 *
 * 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"
#include "nsIFile.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;

  /**
   * Runs executable with parameters (args[]) and returns the standard output
   * emitted by the executable as a string. No shell expansion is carried out.
   * Unquoting (stripping quotes/backaslashes) is not done.
   * This method blocks for the completion of the executable.
   */
  string run(in nsIFile executable,
             [array, size_is(argCount)] in string args,
             in unsigned long argCount);

  /**
   * Runs executable with parameters (args[]) and 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.)
   * PreInput may be used for passphrases etc.
   * Unquoting the command (stripping quotes/backaslashes) is not done.
   * This method blocks for the completion of the command.
   */
  long runPipe (in nsIFile executable,
                [array, size_is(argCount)] in string args,
                in unsigned long argCount,
                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);

  /**
   * Runs executable, with parameters (args[]) and 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.
   *
   * PreInput may be used for passphrases etc.
   * Unquoting the command (stripping quotes/backslashes) is not done.
   */
  nsIIPCRequest runAsync(in nsIFile executable,
                         [array, size_is(argCount)] in string args,
                         in unsigned long argCount,
                         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 secret random cookie used for security
   */
  readonly attribute string cookie;
  
  /**
   * Creates scriptable string channel 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 executable, 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 executable;

  readonly attribute nsIPipeTransport pipeTransport;

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

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