channel.h

Go to the documentation of this file.

/*
 * 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.50  2006/01/27 07:54:32  csoutheren
 * Exposed PChannel::SetError function
 *
 * 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 manty@manty.net
 *
 * 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;
};


class PChannel : public PObject, public iostream {
  PCLASSINFO(PChannel, PObject);

  public:

    PChannel();

    ~PChannel();

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual PINDEX HashFunction() const;

    virtual BOOL IsOpen() const;

    virtual PString GetName() const;

    int GetHandle() const;

    virtual PChannel * GetBaseReadChannel() const;

    virtual PChannel * GetBaseWriteChannel() const;

    void SetReadTimeout(
      const PTimeInterval & time  
    );

    PTimeInterval GetReadTimeout() const;

    virtual BOOL Read(
      void * buf,   
      PINDEX len    
    );

    virtual PINDEX GetLastReadCount() const;

    virtual int ReadChar();

    BOOL ReadBlock(
      void * buf,   
      PINDEX len    
    );

    PString ReadString(PINDEX len);

    virtual BOOL ReadAsync(
      void * buf,   
      PINDEX len    
    );

    virtual void OnReadComplete(
      void * buf, 
      PINDEX len  
    );

    void SetWriteTimeout(
      const PTimeInterval & time 
    );

    PTimeInterval GetWriteTimeout() const;

    virtual BOOL Write(
      const void * buf, 
      PINDEX len        
    );

    virtual PINDEX GetLastWriteCount() const;

    BOOL WriteChar(int c);

    BOOL WriteString(const PString & str);

    virtual BOOL WriteAsync(
      const void * buf, 
      PINDEX len        
    );

    virtual void OnWriteComplete(
      const void * buf, 
      PINDEX len        
    );

    virtual BOOL Close();

    enum ShutdownValue {
      ShutdownRead         = 0,
      ShutdownWrite        = 1,
      ShutdownReadAndWrite = 2
    };

    virtual BOOL Shutdown(
      ShutdownValue option
    );

    BOOL SetBufferSize(
      PINDEX newSize    
    );

    BOOL SendCommandString(
      const PString & command  
    );

    void AbortCommandString();

    enum Errors {
      NoError,
      NotFound,       
      FileExists,     
      DiskFull,       
      AccessDenied,   
      DeviceInUse,    
      BadParameter,   
      NoMemory,       
      NotOpen,        
      Timeout,        
      Interrupted,    
      BufferTooSmall, 
      Miscellaneous,
      ProtocolFailure,
      NumNormalisedErrors
    };

    enum ErrorGroup {
      LastReadError,      
      LastWriteError,     
      LastGeneralError,   
      NumErrorGroups
    };

    Errors GetErrorCode(
      ErrorGroup group = NumErrorGroups   
    ) const;

    int GetErrorNumber(
      ErrorGroup group = NumErrorGroups   
    ) const;

    virtual PString GetErrorText(
      ErrorGroup group = NumErrorGroups   
    ) const;

    static PString GetErrorText(
      Errors lastError,   
      int osError = 0     
    );

    static BOOL ConvertOSError(
      int libcReturnValue,
      Errors & lastError,
      int & osError
    );

#if P_HAS_RECVMSG
    typedef iovec Slice;
#else
    struct Slice {
      void * iov_base;
      size_t iov_len;
    };
#endif

    typedef std::vector<Slice> VectorOfSlice;

    virtual BOOL Read(
      const VectorOfSlice & slices    // slices to read to
    );

    virtual BOOL Write(
      const VectorOfSlice & slices    // slices to read to
    );

  protected:
    PChannel(const PChannel &);
    PChannel & operator=(const PChannel &);
    // Prevent usage by external classes


    virtual BOOL ConvertOSError(
      int libcReturnValue,
      ErrorGroup group = LastGeneralError 
    );

  public:
    BOOL SetErrorValues(
      Errors errorCode,   
      int osError,        
      ErrorGroup group = LastGeneralError 
    );

  protected:
    int ReadCharWithTimeout(
      PTimeInterval & timeout  // Timeout for read.
    );

    // Receive a (partial) command string, determine if completed yet.
    BOOL ReceiveCommandString(
      int nextChar,
      const PString & reply,
      PINDEX & pos,
      PINDEX start
    );


    // Member variables
    int os_handle;
    Errors lastErrorCode[NumErrorGroups+1];
    int lastErrorNumber[NumErrorGroups+1];
    PINDEX lastReadCount;
    PINDEX lastWriteCount;
    PTimeInterval readTimeout;
    PTimeInterval writeTimeout;


  private:
    // New functions for class
    void Construct();
      // Complete platform dependent construction.

    // Member variables
    BOOL abortCommandString;
      // Flag to abort the transmission of a command in SendCommandString().


// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/channel.h"
#else
#include "unix/ptlib/channel.h"
#endif

};

#endif

// End Of File ///////////////////////////////////////////////////////////////

---