pipechan.h

pwlib源码库

/*
 * pipechan.h
 *
 * Sub-process with communications using pipe I/O channel class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: pipechan.h,v $
 * Revision 1.22  2003/09/17 05:41:59  csoutheren
 * Removed recursive includes
 *
 * Revision 1.21  2003/09/17 01:18:02  csoutheren
 * Removed recursive include file system and removed all references
 * to deprecated coooperative threading support
 *
 * Revision 1.20  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.19  2001/05/22 12:49:32  robertj
 * Did some seriously wierd rewrite of platform headers to eliminate the
 *   stupid GNU compiler warning about braces not matching.
 *
 * Revision 1.18  1999/03/09 02:59:50  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.17  1999/02/16 08:11:09  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.16  1998/11/02 10:06:39  robertj
 * Added capability of pip output to go to stdout/stderr.
 *
 * Revision 1.15  1998/10/30 10:42:29  robertj
 * Better function arrangement for multi platforming.
 *
 * Revision 1.14  1998/10/29 11:29:17  robertj
 * Added ability to set environment in sub-process.
 *
 * Revision 1.13  1998/10/26 09:11:05  robertj
 * Added ability to separate out stdout from stderr on pipe channels.
 *
 * Revision 1.12  1998/09/23 06:21:08  robertj
 * Added open source copyright license.
 *
 * Revision 1.11  1997/01/03 05:25:05  robertj
 * Added Wait and Kill functions.
 *
 * Revision 1.10  1996/03/31 08:50:51  robertj
 * Changed string list to array.
 * Added function to idicate if sub-process is running.
 *
 * Revision 1.9  1995/07/31 12:15:45  robertj
 * Removed PContainer from PChannel ancestor.
 *
 * Revision 1.8  1995/06/17 11:12:53  robertj
 * Documentation update.
 *
 * Revision 1.7  1995/03/14 12:42:02  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.6  1995/01/09  12:39:01  robertj
 * Documentation.
 *
 * Revision 1.5  1994/10/23  04:50:55  robertj
 * Further refinement of semantics after implementation.
 *
 * Revision 1.4  1994/09/25  10:43:19  robertj
 * Added more implementation.
 *
 * Revision 1.3  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.2  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.1  1994/04/20  12:17:44  robertj
 * Initial revision
 *
 */

#ifndef _PPIPECHANNEL
#define _PPIPECHANNEL

#ifdef P_USE_PRAGMA
#pragma interface
#endif


/**A channel that uses a operating system pipe between the current process and
   a sub-process. On platforms that support {\it multi-processing}, the
   sub-program is executed concurrently with the calling process.
   
   Where full multi-processing is not supported then the sub-program is run
   with its input supplied from, or output captured to, a disk file. The
   current process is then suspended during the execution of the sub-program.
   In the latter case the semantics of the #Execute()# and #Close()#
   functions change from the usual for channels.

   Note that for platforms that do not support multi-processing, the current
   process is suspended until the sub-program terminates. The input and output
   of the sub-program is transferred via a temporary file. The exact moment of
   execution of the sub-program depends on the mode. If mode is
   #ReadOnly# then it is executed immediately and its output
   captured. In #WriteOnly# mode the sub-program is run when the
   #Close()# function is called, or when the pipe channel is destroyed.
   In #ReadWrite# mode the sub-program is run when the
   #Execute()# function is called indicating that the output from the
   current process to the sub-program has completed and input is now desired.
   
   The #CanReadAndWrite()# function effectively determines whether full
   multi-processing is supported by the platform. Note that this is different
   to whether {\it multi-threading} is supported.
 */
class PPipeChannel : public PChannel
{
  PCLASSINFO(PPipeChannel, PChannel);

  public:
  /**@name Construction */
  //@{
    /// Channel mode for the pipe to the sub-process.
    enum OpenMode {
      /// Pipe is only from the sub-process to the current process.
      ReadOnly,   
      /// Pipe is only from the current process to the sub-process.
      WriteOnly,  
      /// Pipe is bidirectional between current and sub-processes.
      ReadWrite,  
      /**Pipe is bidirectional between current and sub-processes but the write
         side goes to stdout and stderr */
      ReadWriteStd
    };

    /**Create a new pipe channel.
     */
    PPipeChannel();
    /**Create a new pipe channel.
       This executes the subProgram and transfers data from its stdin/stdout/stderr.
       
       See the #Open()# function for details of various parameters.
     */
    PPipeChannel(
      const PString & subProgram,  /// Sub program name or command line.
      OpenMode mode = ReadWrite,   /// Mode for the pipe channel.
      BOOL searchPath = TRUE,      /// Flag for system PATH to be searched.
      BOOL stderrSeparate = FALSE  /// Standard error is on separate pipe
    );
    /**Create a new pipe channel.
       This executes the subProgram and transfers data from its stdin/stdout/stderr.
       
       See the #Open()# function for details of various parameters.
     */
    PPipeChannel(
      const PString & subProgram,  /// Sub program name or command line.
      const PStringArray & argumentList, /// Array of arguments to sub-program.
      OpenMode mode = ReadWrite,   /// Mode for the pipe channel.
      BOOL searchPath = TRUE,      /// Flag for system PATH to be searched.
      BOOL stderrSeparate = FALSE  /// Standard error is on separate pipe
    );
    /**Create a new pipe channel.
       This executes the subProgram and transfers data from its stdin/stdout/stderr.
       
       See the #Open()# function for details of various parameters.
     */
    PPipeChannel(
      const PString & subProgram,  /// Sub program name or command line.
      const PStringToString & environment, /// Array of arguments to sub-program.
      OpenMode mode = ReadWrite,   /// Mode for the pipe channel.
      BOOL searchPath = TRUE,      /// Flag for system PATH to be searched.
      BOOL stderrSeparate = FALSE  /// Standard error is on separate pipe
    );
    /**Create a new pipe channel.
       This executes the subProgram and transfers data from its stdin/stdout/stderr.
       
       See the #Open()# function for details of various parameters.
     */
    PPipeChannel(
      const PString & subProgram,  /// Sub program name or command line.
      const PStringArray & argumentList, /// Array of arguments to sub-program.
      const PStringToString & environment, /// Array of arguments to sub-program.
      OpenMode mode = ReadWrite,   /// Mode for the pipe channel.
      BOOL searchPath = TRUE,      /// Flag for system PATH to be searched.
      BOOL stderrSeparate = FALSE  /// Standard error is on separate pipe
    );

    /// Close the pipe channel, killing the sub-process.
    ~PPipeChannel();
  //@}

  /**@name Overrides from class PObject */
  //@{
    /**Determine if the two objects refer to the same pipe channel. This
       actually compares the sub-program names that are passed into the
       constructor.

       @return
       Comparison value of the sub-program strings.
     */
    Comparison Compare(
      const PObject & obj   /// Another pipe channel to compare against.
    ) const;
  //@}


  /**@name Overrides from class PChannel */
  //@{
    /**Get the name of the channel.
    
       @return
       string for the sub-program that is run.
     */
    virtual PString GetName() const;

    /**Low level read from the channel. This function may block until the
       requested number of characters were read or the read timeout was
       reached. The GetLastReadCount() function returns the actual number