# channel.h

Go to the documentation of this file.

    00001 /*
    00002  * channel.h
    00003  *
    00004  * I/O channel ancestor class.
    00005  *
    00006  * Portable Windows Library
    00007  *
    00008  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
    00009  *
    00010  * The contents of this file are subject to the Mozilla Public License
    00011  * Version 1.0 (the "License"); you may not use this file except in
    00012  * compliance with the License. You may obtain a copy of the License at
    00013  * http://www.mozilla.org/MPL/
    00014  *
    00015  * Software distributed under the License is distributed on an "AS IS"
    00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
    00017  * the License for the specific language governing rights and limitations
    00018  * under the License.
    00019  *
    00020  * The Original Code is Portable Windows Library.
    00021  *
    00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
    00023  *
    00024  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
    00025  * All Rights Reserved.
    00026  *
    00027  * Contributor(s): ______________________________________.
    00028  *
    00029  * $Revision: 24459 $
    00030  * $Author: shorne $
    00031  * $Date: 2010-06-06 08:59:59 -0500 (Sun, 06 Jun 2010) $
    00032  */
    00033
    00034 #ifndef PTLIB_CHANNEL_H
    00035 #define PTLIB_CHANNEL_H
    00036
    00037 #ifdef P_USE_PRAGMA
    00038 #pragma interface
    00039 #endif
    00040
    00041 #include <ptlib/mutex.h>
    00042
    00044 // I/O Channels
    00045
    00046 class PChannel;
    00047
    00048 /* Buffer class used in PChannel stream.
    00049 This class is necessary for implementing the standard C++ iostream interface
    00050 on <code>PChannel</code> classes and its descendents. It is an internal class and
    00051 should not ever be used by application writers.
    00052 */
    00053 class PChannelStreamBuffer : public streambuf {
    00054
    00055   protected:
    00056     /* Construct the streambuf for standard streams on a channel. This is used
    00057        internally by the <code>PChannel</code> class.
    00058      */
    00059     PChannelStreamBuffer(
    00060       PChannel * chan   // Channel the buffer operates on.
    00061     );
    00062
    00063     virtual int_type overflow(int_type = EOF);
    00064     virtual int_type underflow();
    00065     virtual int sync();
    00066     virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
    00067     virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
    00068
    00069     PBoolean SetBufferSize(
    00070       PINDEX newSize
    00071     );
    00072
    00073   private:
    00074     // Member variables
    00075     PChannel * channel;
    00076     PCharArray input, output;
    00077
    00078   public:
    00079     PChannelStreamBuffer(const PChannelStreamBuffer & sbuf);
    00080     PChannelStreamBuffer & operator=(const PChannelStreamBuffer & sbuf);
    00081
    00082   friend class PChannel;
    00083 };
    00084
    00085
    00107 class PChannel : public PObject, public iostream {
    00108   PCLASSINFO(PChannel, PObject);
    00109
    00110   public:
    00113
    00114     PChannel();
    00115
    00117     ~PChannel();
    00119
    00131     virtual Comparison Compare(
    00132       const PObject & obj
    00133     ) const;
    00134
    00148     virtual PINDEX HashFunction() const;
    00150
    00160     virtual PBoolean IsOpen() const;
    00161
    00167     virtual PString GetName() const;
    00168
    00174     int GetHandle() const;
    00175
    00185     virtual PChannel * GetBaseReadChannel() const;
    00186
    00196     virtual PChannel * GetBaseWriteChannel() const;
    00198
    00208     void SetReadTimeout(
    00209       const PTimeInterval & time
    00210     );
    00211
    00218     PTimeInterval GetReadTimeout() const;
    00219
    00232     virtual PBoolean Read(
    00233       void * buf,
    00234       PINDEX len
    00235     );
    00236
    00251     virtual PINDEX GetLastReadCount() const;
    00252
    00260     virtual int ReadChar();
    00261
    00270     PBoolean ReadBlock(
    00271       void * buf,
    00272       PINDEX len
    00273     );
    00274
    00282     PString ReadString(
    00283       PINDEX len
    00284     );
    00285
    00297     virtual PBoolean ReadAsync(
    00298       void * buf,
    00299       PINDEX len
    00300     );
    00301
    00306     virtual void OnReadComplete(
    00307       void * buf,
    00308       PINDEX len
    00309     );
    00311
    00321     void SetWriteTimeout(
    00322       const PTimeInterval & time
    00323     );
    00324
    00332     PTimeInterval GetWriteTimeout() const;
    00333
    00345     virtual PBoolean Write(
    00346       const void * buf,
    00347       PINDEX len
    00348     );
    00349
    00362     virtual PBoolean Write(
    00363       const void * buf,
    00364       PINDEX len,
    00365           const void * mark
    00366     );
    00367
    00380     virtual PINDEX GetLastWriteCount() const;
    00381
    00390     PBoolean WriteChar(int c);
    00391
    00398     PBoolean WriteString(const PString & str);
    00399
    00409     virtual PBoolean WriteAsync(
    00410       const void * buf,
    00411       PINDEX len
    00412     );
    00413
    00419     virtual void OnWriteComplete(
    00420       const void * buf,
    00421       PINDEX len
    00422     );
    00424
    00431     virtual PBoolean Close();
    00432
    00433     enum ShutdownValue {
    00434       ShutdownRead         = 0,
    00435       ShutdownWrite        = 1,
    00436       ShutdownReadAndWrite = 2
    00437     };
    00438
    00446     virtual PBoolean Shutdown(
    00447       ShutdownValue option
    00448     );
    00449
    00457     virtual bool SetLocalEcho(
    00458       bool localEcho
    00459     );
    00460
    00464     virtual bool FlowControl(const void * flowData);
    00465
    00471     PBoolean SetBufferSize(
    00472       PINDEX newSize
    00473     );
    00474
    00513     PBoolean SendCommandString(
    00514       const PString & command
    00515     );
    00516
    00521     void AbortCommandString();
    00523
    00529     enum Errors {
    00530       NoError,
    00532       NotFound,
    00534       FileExists,
    00536       DiskFull,
    00538       AccessDenied,
    00540       DeviceInUse,
    00542       BadParameter,
    00544       NoMemory,
    00546       NotOpen,
    00548       Timeout,
    00550       Interrupted,
    00552       BufferTooSmall,
    00554       Miscellaneous,
    00556       ProtocolFailure,
    00557       NumNormalisedErrors
    00558     };
    00559
    00565     enum ErrorGroup {
    00566       LastReadError,
    00567       LastWriteError,
    00568       LastGeneralError,
    00569       NumErrorGroups
    00570     };
    00571
    00576     Errors GetErrorCode(
    00577       ErrorGroup group = NumErrorGroups
    00578     ) const;
    00579
    00585     int GetErrorNumber(
    00586       ErrorGroup group = NumErrorGroups
    00587     ) const;
    00588
    00594     virtual PString GetErrorText(
    00595       ErrorGroup group = NumErrorGroups
    00596     ) const;
    00597
    00604     static PString GetErrorText(
    00605       Errors lastError,
    00606       int osError = 0
    00607     );
    00609
    00616     static PBoolean ConvertOSError(
    00617       int libcReturnValue,
    00618       Errors & lastError,
    00619       int & osError
    00620     );
    00621
    00626 #if P_HAS_RECVMSG
    00627     typedef iovec Slice;
    00628 #else
    00629     struct Slice {
    00630       void * iov_base;
    00631       size_t iov_len;
    00632     };
    00633 #endif
    00634
    00635     typedef std::vector<Slice> VectorOfSlice;
    00636
    00646     virtual PBoolean Read(
    00647       const VectorOfSlice & slices    // slices to read to
    00648     );
    00649
    00659     virtual PBoolean Write(
    00660       const VectorOfSlice & slices    // slices to read to
    00661     );
    00663
    00664   protected:
    00665     PChannel(const PChannel &);
    00666     PChannel & operator=(const PChannel &);
    00667     // Prevent usage by external classes
    00668
    00669
    00676     virtual PBoolean ConvertOSError(
    00677       int libcReturnValue,
    00678       ErrorGroup group = LastGeneralError
    00679     );
    00680
    00681   public:
    00685     PBoolean SetErrorValues(
    00686       Errors errorCode,
    00687       int osError,
    00688       ErrorGroup group = LastGeneralError
    00689     );
    00690
    00691   protected:
    00700     int ReadCharWithTimeout(
    00701       PTimeInterval & timeout  // Timeout for read.
    00702     );
    00703
    00704     // Receive a (partial) command string, determine if completed yet.
    00705     PBoolean ReceiveCommandString(
    00706       int nextChar,
    00707       const PString & reply,
    00708       PINDEX & pos,
    00709       PINDEX start
    00710     );
    00711
    00712
    00713     // Member variables
    00715     int os_handle;
    00717     Errors lastErrorCode[NumErrorGroups+1];
    00719     int lastErrorNumber[NumErrorGroups+1];
    00721     PINDEX lastReadCount;
    00723     PINDEX lastWriteCount;
    00725     PTimeInterval readTimeout;
    00727     PTimeInterval writeTimeout;
    00728
    00729
    00730   private:
    00731     // New functions for class
    00732     void Construct();
    00733       // Complete platform dependent construction.
    00734
    00735     // Member variables
    00736     PBoolean abortCommandString;
    00737       // Flag to abort the transmission of a command in SendCommandString().
    00738
    00739
    00740 // Include platform dependent part of class
    00741 #ifdef _WIN32
    00742 #include "msos/ptlib/channel.h"
    00743 #else
    00744 #include "unix/ptlib/channel.h"
    00745 #endif
    00746
    00747 };
    00748
    00749
    00750 #endif // PTLIB_CHANNEL_H
    00751
    00752
    00753 // End Of File ///////////////////////////////////////////////////////////////