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: 32474 $
 * $Author: rjongbloed $
 * $Date: 2014-08-09 14:23:47 +1000 (Sat, 09 Aug 2014) $
 */

#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 { return channelName; }

    virtual P_INT_PTR GetHandle() const;

    FILE * FDOpen(const char * mode);

    virtual PChannel * GetBaseReadChannel() const;

    virtual PChannel * GetBaseWriteChannel() const;

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

    PINDEX GetLastReadCount() const;

    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;

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

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

    virtual int os_errno() const;

    // Member variables
    P_INT_PTR os_handle;

    Errors lastErrorCode[NumErrorGroups+1];
    int lastErrorNumber[NumErrorGroups+1];
    PINDEX lastReadCount;
    PINDEX lastWriteCount;
    PTimeInterval readTimeout;
    PTimeInterval writeTimeout;
    PString channelName;

  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

};


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

    PBoolean Read(void *, PINDEX);
    PBoolean Write(const void *, PINDEX);
};


#endif // PTLIB_CHANNEL_H


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