Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

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  * $Log: channel.h,v $
00030  * Revision 1.43  2004/04/09 06:38:10  rjongbloed
00031  * Fixed compatibility with STL based streams, eg as used by VC++2003
00032  *
00033  * Revision 1.42  2003/12/19 04:29:52  csoutheren
00034  * Changed GetLastReadCount and GetLastWriteCount to be virtual
00035  *
00036  * Revision 1.41  2003/09/17 05:41:58  csoutheren
00037  * Removed recursive includes
00038  *
00039  * Revision 1.40  2003/09/17 01:18:02  csoutheren
00040  * Removed recursive include file system and removed all references
00041  * to deprecated coooperative threading support
00042  *
00043  * Revision 1.39  2002/09/16 01:08:59  robertj
00044  * Added #define so can select if #pragma interface/implementation is used on
00045  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00046  *
00047  * Revision 1.38  2002/07/04 23:35:47  robertj
00048  * Fixed documentation error
00049  *
00050  * Revision 1.37  2002/04/09 02:30:18  robertj
00051  * Removed GCC3 variable as __GNUC__ can be used instead, thanks jason Spence
00052  *
00053  * Revision 1.36  2002/01/26 23:55:55  craigs
00054  * Changed for GCC 3.0 compatibility, thanks to manty@manty.net
00055  *
00056  * Revision 1.35  2001/11/13 04:13:22  robertj
00057  * Added ability to adjust size of ios buffer on PChannels.
00058  *
00059  * Revision 1.34  2001/09/11 03:27:46  robertj
00060  * Improved error processing on high level protocol failures, usually
00061  *   caused by unexpected shut down of a socket.
00062  *
00063  * Revision 1.33  2001/09/10 02:51:22  robertj
00064  * Major change to fix problem with error codes being corrupted in a
00065  *   PChannel when have simultaneous reads and writes in threads.
00066  *
00067  * Revision 1.32  2001/06/04 10:13:08  robertj
00068  * Added compare function to compare value of os_handle.
00069  * Added has function based on os_handle value.
00070  *
00071  * Revision 1.31  2001/05/22 12:49:32  robertj
00072  * Did some seriously wierd rewrite of platform headers to eliminate the
00073  *   stupid GNU compiler warning about braces not matching.
00074  *
00075  * Revision 1.30  1999/11/05 09:37:46  craigs
00076  * Made static form of ConvertOSError public scope
00077  *
00078  * Revision 1.29  1999/10/09 01:22:06  robertj
00079  * Fixed error display for sound channels.
00080  *
00081  * Revision 1.28  1999/03/09 02:59:49  robertj
00082  * Changed comments to doc++ compatible documentation.
00083  *
00084  * Revision 1.27  1998/09/23 06:20:18  robertj
00085  * Added open source copyright license.
00086  *
00087  * Revision 1.26  1998/02/03 06:29:10  robertj
00088  * Added new function to read a block with minimum number of bytes.
00089  *
00090  * Revision 1.25  1997/07/08 13:15:03  robertj
00091  * DLL support.
00092  *
00093  * Revision 1.24  1996/11/04 03:41:04  robertj
00094  * Added extra error message for UDP packet truncated.
00095  *
00096  * Revision 1.23  1996/09/14 13:09:17  robertj
00097  * Major upgrade:
00098  *   rearranged sockets to help support IPX.
00099  *   added indirect channel class and moved all protocols to descend from it,
00100  *   separating the protocol from the low level byte transport.
00101  *
00102  * Revision 1.22  1996/08/17 10:00:19  robertj
00103  * Changes for Windows DLL support.
00104  *
00105  * Revision 1.21  1996/07/27 04:15:07  robertj
00106  * Created static version of ConvertOSError().
00107  * Created static version of GetErrorText().
00108  *
00109  * Revision 1.20  1996/05/26 03:24:40  robertj
00110  * Compatibility to GNU 2.7.x
00111  *
00112  * Revision 1.19  1996/04/15 12:33:03  robertj
00113  * Fixed SetReadTimeout/SetWriteTimeout to use const reference so works with GNU compiler.
00114  *
00115  * Revision 1.18  1996/04/14 02:53:30  robertj
00116  * Split serial and pipe channel into separate compilation units for Linux executable size reduction.
00117  *
00118  * Revision 1.17  1996/02/19 13:12:48  robertj
00119  * Added new error code for interrupted I/O.
00120  *
00121  * Revision 1.16  1996/01/23 13:09:14  robertj
00122  * Mac Metrowerks compiler support.
00123  *
00124  * Revision 1.15  1995/08/12 22:28:22  robertj
00125  * Work arounf for  GNU bug: can't have private copy constructor with multiple inheritance.
00126  *
00127  * Revision 1.14  1995/07/31 12:15:42  robertj
00128  * Removed PContainer from PChannel ancestor.
00129  *
00130  * Revision 1.13  1995/06/17 11:12:21  robertj
00131  * Documentation update.
00132  *
00133  * Revision 1.12  1995/06/04 08:42:00  robertj
00134  * Fixed comment.
00135  *
00136  * Revision 1.11  1995/03/14 12:41:03  robertj
00137  * Updated documentation to use HTML codes.
00138  *
00139  * Revision 1.10  1995/03/12  04:36:53  robertj
00140  * Moved GetHandle() function from PFile to PChannel.
00141  *
00142  * Revision 1.9  1994/12/21  11:52:48  robertj
00143  * Documentation and variable normalisation.
00144  *
00145  * Revision 1.8  1994/11/28  12:31:40  robertj
00146  * Documentation.
00147  *
00148  * Revision 1.7  1994/08/23  11:32:52  robertj
00149  * Oops
00150  *
00151  * Revision 1.6  1994/08/22  00:46:48  robertj
00152  * Added pragma fro GNU C++ compiler.
00153  *
00154  * Revision 1.5  1994/08/21  23:43:02  robertj
00155  * Moved meta-string transmitter from PModem to PChannel.
00156  * Added common entry point to convert OS error to PChannel error.
00157  *
00158  * Revision 1.4  1994/07/17  10:46:06  robertj
00159  * Unix support changes.
00160  *
00161  * Revision 1.3  1994/07/02  03:03:49  robertj
00162  * Changed to allow for platform dependent part.
00163  *
00164  * Revision 1.2  1994/06/25  11:55:15  robertj
00165  * Unix version synchronisation.
00166  *
00167  * Revision 1.1  1994/04/20  12:17:44  robertj
00168  * Initial revision
00169  *
00170  */
00171 
00172 #ifndef _PCHANNEL
00173 #define _PCHANNEL
00174 
00175 #ifdef P_USE_PRAGMA
00176 #pragma interface
00177 #endif
00178 
00179 #include <ptlib/mutex.h>
00180 
00182 // I/O Channels
00183 
00184 class PChannel;
00185 
00186 /* Buffer class used in PChannel stream.
00187 This class is necessary for implementing the standard C++ iostream interface
00188 on #PChannel# classes and its descendents. It is an internal class and
00189 should not ever be used by application writers.
00190 */
00191 class PChannelStreamBuffer : public streambuf {
00192 
00193   protected:
00194     /* Construct the streambuf for standard streams on a channel. This is used
00195        internally by the #PChannel# class.
00196      */
00197     PChannelStreamBuffer(
00198       PChannel * chan   // Channel the buffer operates on.
00199     );
00200 
00201     virtual int overflow(int=EOF);
00202     virtual int underflow();
00203     virtual int sync();
00204 #if __USE_STL__
00205     virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
00206     virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
00207 #else
00208     virtual streampos seekoff(streamoff, ios::seek_dir, int);
00209 #endif
00210 
00211     BOOL SetBufferSize(
00212       PINDEX newSize
00213     );
00214 
00215   private:
00216     // Member variables
00217     PChannel * channel;
00218     PCharArray input, output;
00219 
00220   public:
00221     PChannelStreamBuffer(const PChannelStreamBuffer & sbuf);
00222     PChannelStreamBuffer & operator=(const PChannelStreamBuffer & sbuf);
00223 
00224   friend class PChannel;
00225 };
00226 
00227 
00249 class PChannel : public PObject, public iostream {
00250   PCLASSINFO(PChannel, PObject);
00251 
00252   public:
00255 
00256     PChannel();
00257 
00259     ~PChannel();
00261 
00273     virtual Comparison Compare(
00274       const PObject & obj   
00275     ) const;
00276 
00290     virtual PINDEX HashFunction() const;
00292 
00302     virtual BOOL IsOpen() const;
00303 
00309     virtual PString GetName() const;
00310 
00316     int GetHandle() const;
00317 
00327     virtual PChannel * GetBaseReadChannel() const;
00328 
00338     virtual PChannel * GetBaseWriteChannel() const;
00340 
00350     void SetReadTimeout(
00351       const PTimeInterval & time  
00352     );
00353 
00360     PTimeInterval GetReadTimeout() const;
00361 
00374     virtual BOOL Read(
00375       void * buf,   
00376       PINDEX len    
00377     );
00378 
00393     virtual PINDEX GetLastReadCount() const;
00394 
00402     virtual int ReadChar();
00403 
00412     BOOL ReadBlock(
00413       void * buf,   
00414       PINDEX len    
00415     );
00416 
00424     PString ReadString(PINDEX len);
00425 
00437     virtual BOOL ReadAsync(
00438       void * buf,   
00439       PINDEX len    
00440     );
00441 
00446     virtual void OnReadComplete(
00447       void * buf, 
00448       PINDEX len  
00449     );
00451 
00461     void SetWriteTimeout(
00462       const PTimeInterval & time 
00463     );
00464 
00472     PTimeInterval GetWriteTimeout() const;
00473 
00485     virtual BOOL Write(
00486       const void * buf, 
00487       PINDEX len        
00488     );
00489 
00502     virtual PINDEX GetLastWriteCount() const;
00503 
00512     BOOL WriteChar(int c);
00513 
00520     BOOL WriteString(const PString & str);
00521 
00531     virtual BOOL WriteAsync(
00532       const void * buf, 
00533       PINDEX len        
00534     );
00535 
00541     virtual void OnWriteComplete(
00542       const void * buf, 
00543       PINDEX len        
00544     );
00546 
00553     virtual BOOL Close();
00554 
00555     enum ShutdownValue {
00556       ShutdownRead         = 0,
00557       ShutdownWrite        = 1,
00558       ShutdownReadAndWrite = 2
00559     };
00560 
00568     virtual BOOL Shutdown(
00569       ShutdownValue option
00570     );
00571 
00577     BOOL SetBufferSize(
00578       PINDEX newSize    
00579     );
00580 
00620     BOOL SendCommandString(
00621       const PString & command  
00622     );
00623 
00628     void AbortCommandString();
00630 
00636     enum Errors {
00637       NoError,
00639       NotFound,       
00641       FileExists,     
00643       DiskFull,       
00645       AccessDenied,   
00647       DeviceInUse,    
00649       BadParameter,   
00651       NoMemory,       
00653       NotOpen,        
00655       Timeout,        
00657       Interrupted,    
00659       BufferTooSmall, 
00661       Miscellaneous,
00663       ProtocolFailure,
00664       NumNormalisedErrors
00665     };
00666 
00672     enum ErrorGroup {
00673       LastReadError,      
00674       LastWriteError,     
00675       LastGeneralError,   
00676       NumErrorGroups
00677     };
00678 
00683     Errors GetErrorCode(
00684       ErrorGroup group = NumErrorGroups   
00685     ) const;
00686 
00692     int GetErrorNumber(
00693       ErrorGroup group = NumErrorGroups   
00694     ) const;
00695 
00701     virtual PString GetErrorText(
00702       ErrorGroup group = NumErrorGroups   
00703     ) const;
00704 
00711     static PString GetErrorText(
00712       Errors lastError,   
00713       int osError = 0     
00714     );
00716 
00723     static BOOL ConvertOSError(
00724       int libcReturnValue,
00725       Errors & lastError,
00726       int & osError
00727     );
00728 
00729 
00730   protected:
00731     PChannel(const PChannel &);
00732     PChannel & operator=(const PChannel &);
00733     // Prevent usage by external classes
00734 
00735 
00742     virtual BOOL ConvertOSError(
00743       int libcReturnValue,
00744       ErrorGroup group = LastGeneralError 
00745     );
00746 
00750     BOOL SetErrorValues(
00751       Errors errorCode,   
00752       int osError,        
00753       ErrorGroup group = LastGeneralError 
00754     );
00755 
00764     int ReadCharWithTimeout(
00765       PTimeInterval & timeout  // Timeout for read.
00766     );
00767 
00768     // Receive a (partial) command string, determine if completed yet.
00769     BOOL ReceiveCommandString(
00770       int nextChar,
00771       const PString & reply,
00772       PINDEX & pos,
00773       PINDEX start
00774     );
00775 
00776 
00777     // Member variables
00779     int os_handle;
00781     Errors lastErrorCode[NumErrorGroups+1];
00783     int lastErrorNumber[NumErrorGroups+1];
00785     PINDEX lastReadCount;
00787     PINDEX lastWriteCount;
00789     PTimeInterval readTimeout;
00791     PTimeInterval writeTimeout;
00792 
00793 
00794   private:
00795     // New functions for class
00796     void Construct();
00797       // Complete platform dependent construction.
00798 
00799     // Member variables
00800     BOOL abortCommandString;
00801       // Flag to abort the transmission of a command in SendCommandString().
00802 
00803 
00804 // Include platform dependent part of class
00805 #ifdef _WIN32
00806 #include "msos/ptlib/channel.h"
00807 #else
00808 #include "unix/ptlib/channel.h"
00809 #endif
00810 
00811 };
00812 
00813 #endif
00814 
00815 // End Of File ///////////////////////////////////////////////////////////////

Generated on Sat Dec 22 16:46:50 2007 for PWLib by  doxygen 1.4.2