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): ______________________________________.
 *
 * $Revision: 24459 $
 * $Author: shorne $
 * $Date: 2010-06-06 08:59:59 -0500 (Sun, 06 Jun 2010) $
 */

#ifndef PTLIB_CHANNEL_H
#define PTLIB_CHANNEL_H

#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 <code>PChannel</code> 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 <code>PChannel</code> class.
     */
    PChannelStreamBuffer(
      PChannel * chan   // Channel the buffer operates on.
    );

    virtual int_type overflow(int_type = EOF);
    virtual int_type underflow();
    virtual int sync();
    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);

    PBoolean 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 PBoolean 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 PBoolean Read(
      void * buf,   
      PINDEX len    
    );

    virtual PINDEX GetLastReadCount() const;

    virtual int ReadChar();

    PBoolean ReadBlock(
      void * buf,   
      PINDEX len    
    );

    PString ReadString(
      PINDEX len  
    );

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

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

    void SetWriteTimeout(
      const PTimeInterval & time 
    );

    PTimeInterval GetWriteTimeout() const;

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

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

    virtual PINDEX GetLastWriteCount() const;

    PBoolean WriteChar(int c);

    PBoolean WriteString(const PString & str);

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

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

    virtual PBoolean Close();

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

    virtual PBoolean Shutdown(
      ShutdownValue option
    );

    virtual bool SetLocalEcho(
      bool localEcho
    );

    virtual bool FlowControl(const void * flowData);

    PBoolean SetBufferSize(
      PINDEX newSize    
    );

    PBoolean 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 PBoolean 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 PBoolean Read(
      const VectorOfSlice & slices    // slices to read to
    );

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

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


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

  public:
    PBoolean 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.
    PBoolean 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
    PBoolean 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 // PTLIB_CHANNEL_H


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

---