channel.h

开源代码的pwlib的1.10.0版本,使用openh323的1.18.0版本毕备

/*
 * channel.h
 *
 * I/O channel ancestor 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: channel.h,v $
 * Revision 1.49  2005/11/30 12:47:37  csoutheren
 * Removed tabs, reformatted some code, and changed tags for Doxygen
 *
 * Revision 1.48  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.47  2005/09/18 11:05:36  dominance
 * include/ptlib/channel.h, include/ptlib/pstring.h, src/ptlib/common/contain.cxx,
 * src/ptlib/common/pchannel.cxx:
 *      correct the STL defined checking to use proper syntax.
 *
 * include/ptlib/object.h:
 *      re-add typedef to compile on mingw
 *
 * make/ptlib-config.in:
 *      import a long-standing fix from the Debian packs which allows usage of
 *      ptlib-config without manually adding -lpt for each of the subsequent
 *      projects
 *
 * Revision 1.46  2005/08/05 20:44:46  csoutheren
 * Fixed typo
 *
 * Revision 1.45  2005/08/05 20:41:41  csoutheren
 * Added unix support for scattered read/write
 *
 * Revision 1.44  2005/08/05 19:42:09  csoutheren
 * Added support for scattered read/write
 *
 * Revision 1.43  2004/04/09 06:38:10  rjongbloed
 * Fixed compatibility with STL based streams, eg as used by VC++2003
 *
 * Revision 1.42  2003/12/19 04:29:52  csoutheren
 * Changed GetLastReadCount and GetLastWriteCount to be virtual
 *
 * Revision 1.41  2003/09/17 05:41:58  csoutheren
 * Removed recursive includes
 *
 * Revision 1.40  2003/09/17 01:18:02  csoutheren
 * Removed recursive include file system and removed all references
 * to deprecated coooperative threading support
 *
 * Revision 1.39  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.38  2002/07/04 23:35:47  robertj
 * Fixed documentation error
 *
 * Revision 1.37  2002/04/09 02:30:18  robertj
 * Removed GCC3 variable as __GNUC__ can be used instead, thanks jason Spence
 *
 * Revision 1.36  2002/01/26 23:55:55  craigs
 * Changed for GCC 3.0 compatibility, thanks to [e-mail]
 *
 * Revision 1.35  2001/11/13 04:13:22  robertj
 * Added ability to adjust size of ios buffer on PChannels.
 *
 * Revision 1.34  2001/09/11 03:27:46  robertj
 * Improved error processing on high level protocol failures, usually
 *   caused by unexpected shut down of a socket.
 *
 * Revision 1.33  2001/09/10 02:51:22  robertj
 * Major change to fix problem with error codes being corrupted in a
 *   PChannel when have simultaneous reads and writes in threads.
 *
 * Revision 1.32  2001/06/04 10:13:08  robertj
 * Added compare function to compare value of os_handle.
 * Added has function based on os_handle value.
 *
 * Revision 1.31  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.30  1999/11/05 09:37:46  craigs
 * Made static form of ConvertOSError public scope
 *
 * Revision 1.29  1999/10/09 01:22:06  robertj
 * Fixed error display for sound channels.
 *
 * Revision 1.28  1999/03/09 02:59:49  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.27  1998/09/23 06:20:18  robertj
 * Added open source copyright license.
 *
 * Revision 1.26  1998/02/03 06:29:10  robertj
 * Added new function to read a block with minimum number of bytes.
 *
 * Revision 1.25  1997/07/08 13:15:03  robertj
 * DLL support.
 *
 * Revision 1.24  1996/11/04 03:41:04  robertj
 * Added extra error message for UDP packet truncated.
 *
 * Revision 1.23  1996/09/14 13:09:17  robertj
 * Major upgrade:
 *   rearranged sockets to help support IPX.
 *   added indirect channel class and moved all protocols to descend from it,
 *   separating the protocol from the low level byte transport.
 *
 * Revision 1.22  1996/08/17 10:00:19  robertj
 * Changes for Windows DLL support.
 *
 * Revision 1.21  1996/07/27 04:15:07  robertj
 * Created static version of ConvertOSError().
 * Created static version of GetErrorText().
 *
 * Revision 1.20  1996/05/26 03:24:40  robertj
 * Compatibility to GNU 2.7.x
 *
 * Revision 1.19  1996/04/15 12:33:03  robertj
 * Fixed SetReadTimeout/SetWriteTimeout to use const reference so works with GNU compiler.
 *
 * Revision 1.18  1996/04/14 02:53:30  robertj
 * Split serial and pipe channel into separate compilation units for Linux executable size reduction.
 *
 * Revision 1.17  1996/02/19 13:12:48  robertj
 * Added new error code for interrupted I/O.
 *
 * Revision 1.16  1996/01/23 13:09:14  robertj
 * Mac Metrowerks compiler support.
 *
 * Revision 1.15  1995/08/12 22:28:22  robertj
 * Work arounf for  GNU bug: can't have private copy constructor with multiple inheritance.
 *
 * Revision 1.14  1995/07/31 12:15:42  robertj
 * Removed PContainer from PChannel ancestor.
 *
 * Revision 1.13  1995/06/17 11:12:21  robertj
 * Documentation update.
 *
 * Revision 1.12  1995/06/04 08:42:00  robertj
 * Fixed comment.
 *
 * Revision 1.11  1995/03/14 12:41:03  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.10  1995/03/12  04:36:53  robertj
 * Moved GetHandle() function from PFile to PChannel.
 *
 * Revision 1.9  1994/12/21  11:52:48  robertj
 * Documentation and variable normalisation.
 *
 * Revision 1.8  1994/11/28  12:31:40  robertj
 * Documentation.
 *
 * Revision 1.7  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.6  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.5  1994/08/21  23:43:02  robertj
 * Moved meta-string transmitter from PModem to PChannel.
 * Added common entry point to convert OS error to PChannel error.
 *
 * Revision 1.4  1994/07/17  10:46:06  robertj
 * Unix support changes.
 *
 * Revision 1.3  1994/07/02  03:03:49  robertj
 * Changed to allow for platform dependent part.
 *
 * Revision 1.2  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.1  1994/04/20  12:17:44  robertj
 * Initial revision
 *
 */

#ifndef _PCHANNEL
#define _PCHANNEL

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/mutex.h>

///////////////////////////////////////////////////////////////////////////////
// I/O Channels

class PChannel;

/* Buffer class used in PChannel stream.
This class is necessary for implementing the standard C++ iostream interface
on #PChannel# classes and its descendents. It is an internal class and
should not ever be used by application writers.
*/
class PChannelStreamBuffer : public streambuf {

  protected:
    /* Construct the streambuf for standard streams on a channel. This is used
       internally by the #PChannel# class.
     */
    PChannelStreamBuffer(
      PChannel * chan   // Channel the buffer operates on.
    );

    virtual int overflow(int=EOF);
    virtual int underflow();
    virtual int sync();
#ifdef __USE_STL__
    virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
#else
    virtual streampos seekoff(streamoff, ios::seek_dir, int);
#endif

    BOOL SetBufferSize(
      PINDEX newSize
    );

  private:
    // Member variables
    PChannel * channel;
    PCharArray input, output;

  public:
    PChannelStreamBuffer(const PChannelStreamBuffer & sbuf);
    PChannelStreamBuffer & operator=(const PChannelStreamBuffer & sbuf);

  friend class PChannel;
};


/** Abstract class defining I/O channel semantics. An I/O channel can be a
   serial port, pipe, network socket or even just a simple file. Anything that
   requires opening and closing then reading and/or writing from.

   A descendent would typically have constructors and an #Open()# function which
   enables access to the I/O channel it represents. The #Read()# and
   #Write()# functions would then be overridden to the platform and I/O
   specific mechanisms required.

   The general model for a channel is that the channel accepts and/or supplies
   a stream of bytes. The access to the stream of bytes is via a set of
   functions that allow certain types of transfer. These include direct
   transfers, buffered transfers (via iostream) or asynchronous transfers.

   The model also has the fundamental state of the channel being {\it open}
   or {\it closed}. A channel instance that is closed contains sufficient
   information to describe the channel but does not allocate or lock any
   system resources. An open channel allocates or locks the particular system
   resource. The act of opening a channel is a key event that may fail. In this
   case the channel remains closed and error values are set.
 */
class PChannel : public PObject, public iostream {
  PCLASSINFO(PChannel, PObject);

  public:
  /**@name Construction */
  //@{
      /// Create the channel.
    PChannel();

      /// Close down the channel.
    ~PChannel();
  //@}

  /**@name Overrides from class PObject */
  //@{
    /**Get the relative rank of the two strings. The system standard function,
       eg strcmp(), is used.

       @return