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): ______________________________________.
 */

#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(std::streamoff, 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 std::iostream
{
  PCLASSINFO(PChannel, PObject);

  protected:
    PChannel();

  public:
    ~PChannel();

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual PINDEX HashFunction() const;

    virtual PBoolean IsOpen() const;

    virtual PString GetName() const = 0;

    virtual P_INT_PTR GetHandle() const;

    FILE * FDOpen(const char * mode);

    virtual PChannel * GetBaseReadChannel() const;

    virtual PChannel * GetBaseWriteChannel() const;

    virtual bool CloseBaseReadChannel();

    virtual bool CloseBaseWriteChannel();

    enum Errors {
      NoError,        
      NotFound,       
      FileExists,     
      DiskFull,       
      AccessDenied,   
      DeviceInUse,    
      BadParameter,   
      NoMemory,       
      NotOpen,        
      Timeout,        
      Interrupted,    
      BufferTooSmall, 
      Miscellaneous,  
      ProtocolFailure,
      Unavailable,    
      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     
    );

    void SetReadTimeout(
      const PTimeInterval & time  
    );

    PTimeInterval GetReadTimeout() const;

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

    virtual PINDEX GetLastReadCount() const;
    virtual PINDEX SetLastReadCount(PINDEX count);

    virtual int ReadChar();

    PBoolean ReadBlock(
      void * buf,   
      PINDEX len    
    );

    PString ReadString(
      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*/   
     ) { return Write(buf,len); }        
 

    virtual PINDEX GetLastWriteCount() const;
    virtual PINDEX SetLastWriteCount(PINDEX count);

    PBoolean WriteChar(int c);

    PBoolean WriteString(
      const PString & str   
    );

    class AsyncContext;
    typedef PNotifierTemplate<PChannel::AsyncContext &> AsyncNotifier;
    #define PDECLARE_AsyncNotifier(cls, fn) PDECLARE_NOTIFIER2(PChannel, cls, fn, PChannel::AsyncContext &)
    #define PCREATE_AsyncNotifier(fn) PCREATE_NOTIFIER2(fn, PChannel::AsyncContext &)

#ifdef _WIN32
    typedef OVERLAPPED AsyncContextBase;
#elif defined _AIO_H
    typedef struct aiocb AsyncContextBase;
#else
    class AsyncContextBase { off_t m_offset; };
#endif
    class AsyncContext : public AsyncContextBase
    {
      public:
        AsyncContext(
          void * buf = NULL,
          PINDEX len = 0,
          const AsyncNotifier & notifier = AsyncNotifier()
        );

        void SetOffset(off_t offset);

        void        * m_buffer;       
        PINDEX        m_length;       
        AsyncNotifier m_notifier;     

        Errors        m_errorCode;    
        int           m_errorNumber;  

        // Internal stuff
        PChannel * m_channel;
        typedef void (PChannel::*CompletionFunction)(AsyncContext &);
        P_ALIGN_FIELD(CompletionFunction,m_onComplete,16);
        bool Initialise(PChannel * channel, CompletionFunction onComplete);
        void OnIOComplete(PINDEX length, int errorNumber);

        PNEW_AND_DELETE_FUNCTIONS(16)
    };

    virtual bool ReadAsync(
      AsyncContext & context 
    );

    virtual void OnReadComplete(
      AsyncContext & context 
    );

    virtual bool WriteAsync(
      AsyncContext & context 
    );

    virtual void OnWriteComplete(
      AsyncContext & context 
    );

    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();

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


    virtual PBoolean ConvertOSError(
      P_INT_PTR 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
    );

    bool CheckNotOpen();
    virtual int os_errno() const;

    // Member variables
    PTimeInterval readTimeout;  
    PTimeInterval writeTimeout; 
 
    atomic<P_INT_PTR> os_handle; 

    struct Status
    {
      PINDEX m_lastCount;        
      Errors m_lastErrorCode;    
      int    m_lastErrorNumber;  

      Status()
        : m_lastCount(0)
        , m_lastErrorCode(NoError)
        , m_lastErrorNumber(0)
      { }
    };
    PThreadLocalStorage<Status> m_status[NumErrorGroups+1];

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

    // Member variables
    bool m_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

};


class PNullChannel : public PChannel
{
    PCLASSINFO(PNullChannel, PChannel)
  public:
    PNullChannel();

    virtual PString GetName() const { return "null"; }
    virtual PBoolean Read(void *, PINDEX);
    virtual PBoolean Write(const void *, PINDEX);
};


class P_fd_set
{
public:
  P_fd_set();
  P_fd_set(intptr_t fd);
  ~P_fd_set()
  {
    free(set);
  }

  P_fd_set & operator=(intptr_t fd);
  P_fd_set & operator+=(intptr_t fd);
  P_fd_set & operator-=(intptr_t fd);

  void Zero();

  PBoolean IsPresent(intptr_t fd) const;

  operator fd_set*() const
  {
    return set;
  }

protected:
  void Construct();

  intptr_t max_fd;
  fd_set * set;

private:
  P_fd_set(const P_fd_set &) : max_fd(), set() { }
  void operator=(const P_fd_set &) { }
};


#endif // PTLIB_CHANNEL_H


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