PTLib  Version 2.10.10
channel.h
Go to the documentation of this file.
1 /*
2  * channel.h
3  *
4  * I/O channel ancestor class.
5  *
6  * Portable Windows Library
7  *
8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
25  * All Rights Reserved.
26  *
27  * Contributor(s): ______________________________________.
28  *
29  * $Revision: 24459 $
30  * $Author: shorne $
31  * $Date: 2010-06-06 08:59:59 -0500 (Sun, 06 Jun 2010) $
32  */
33 
34 #ifndef PTLIB_CHANNEL_H
35 #define PTLIB_CHANNEL_H
36 
37 #ifdef P_USE_PRAGMA
38 #pragma interface
39 #endif
40 
41 #include <ptlib/mutex.h>
42 
44 // I/O Channels
45 
46 class PChannel;
47 
48 /* Buffer class used in PChannel stream.
49 This class is necessary for implementing the standard C++ iostream interface
50 on <code>PChannel</code> classes and its descendents. It is an internal class and
51 should not ever be used by application writers.
52 */
53 class PChannelStreamBuffer : public streambuf {
54 
55  protected:
56  /* Construct the streambuf for standard streams on a channel. This is used
57  internally by the <code>PChannel</code> class.
58  */
60  PChannel * chan // Channel the buffer operates on.
61  );
62 
63  virtual int_type overflow(int_type = EOF);
64  virtual int_type underflow();
65  virtual int sync();
66  virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
67  virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
68 
70  PINDEX newSize
71  );
72 
73  private:
74  // Member variables
75  PChannel * channel;
76  PCharArray input, output;
77 
78  public:
81 
82  friend class PChannel;
83 };
84 
85 
107 class PChannel : public PObject, public iostream {
108  PCLASSINFO(PChannel, PObject);
109 
110  public:
113  PChannel();
115 
117  ~PChannel();
119 
131  virtual Comparison Compare(
132  const PObject & obj
133  ) const;
134 
148  virtual PINDEX HashFunction() const;
150 
160  virtual PBoolean IsOpen() const;
161 
167  virtual PString GetName() const;
168 
174  int GetHandle() const;
175 
185  virtual PChannel * GetBaseReadChannel() const;
186 
196  virtual PChannel * GetBaseWriteChannel() const;
198 
208  void SetReadTimeout(
209  const PTimeInterval & time
210  );
211 
219 
232  virtual PBoolean Read(
233  void * buf,
234  PINDEX len
235  );
236 
251  virtual PINDEX GetLastReadCount() const;
252 
260  virtual int ReadChar();
261 
271  void * buf,
272  PINDEX len
273  );
274 
283  PINDEX len
284  );
285 
297  virtual PBoolean ReadAsync(
298  void * buf,
299  PINDEX len
300  );
301 
306  virtual void OnReadComplete(
307  void * buf,
308  PINDEX len
309  );
311 
321  void SetWriteTimeout(
322  const PTimeInterval & time
323  );
324 
333 
345  virtual PBoolean Write(
346  const void * buf,
347  PINDEX len
348  );
349 
362  virtual PBoolean Write(
363  const void * buf,
364  PINDEX len,
365  const void * mark
366  );
367 
380  virtual PINDEX GetLastWriteCount() const;
381 
390  PBoolean WriteChar(int c);
391 
398  PBoolean WriteString(const PString & str);
399 
409  virtual PBoolean WriteAsync(
410  const void * buf,
411  PINDEX len
412  );
413 
419  virtual void OnWriteComplete(
420  const void * buf,
421  PINDEX len
422  );
424 
431  virtual PBoolean Close();
432 
437  };
438 
446  virtual PBoolean Shutdown(
447  ShutdownValue option
448  );
449 
457  virtual bool SetLocalEcho(
458  bool localEcho
459  );
460 
464  virtual bool FlowControl(const void * flowData);
465 
472  PINDEX newSize
473  );
474 
514  const PString & command
515  );
516 
521  void AbortCommandString();
523 
529  enum Errors {
558  };
559 
565  enum ErrorGroup {
570  };
571 
577  ErrorGroup group = NumErrorGroups
578  ) const;
579 
585  int GetErrorNumber(
586  ErrorGroup group = NumErrorGroups
587  ) const;
588 
594  virtual PString GetErrorText(
595  ErrorGroup group = NumErrorGroups
596  ) const;
597 
604  static PString GetErrorText(
605  Errors lastError,
606  int osError = 0
607  );
609 
616  static PBoolean ConvertOSError(
617  int libcReturnValue,
618  Errors & lastError,
619  int & osError
620  );
621 
626 #if P_HAS_RECVMSG
627  typedef iovec Slice;
628 #else
629  struct Slice {
630  void * iov_base;
631  size_t iov_len;
632  };
633 #endif
634 
635  typedef std::vector<Slice> VectorOfSlice;
636 
646  virtual PBoolean Read(
647  const VectorOfSlice & slices // slices to read to
648  );
649 
659  virtual PBoolean Write(
660  const VectorOfSlice & slices // slices to read to
661  );
663 
664  protected:
665  PChannel(const PChannel &);
666  PChannel & operator=(const PChannel &);
667  // Prevent usage by external classes
668 
669 
676  virtual PBoolean ConvertOSError(
677  int libcReturnValue,
679  );
680 
681  public:
686  Errors errorCode,
687  int osError,
689  );
690 
691  protected:
701  PTimeInterval & timeout // Timeout for read.
702  );
703 
704  // Receive a (partial) command string, determine if completed yet.
706  int nextChar,
707  const PString & reply,
708  PINDEX & pos,
709  PINDEX start
710  );
711 
712 
713  // Member variables
728 
729 
730  private:
731  // New functions for class
732  void Construct();
733  // Complete platform dependent construction.
734 
735  // Member variables
736  PBoolean abortCommandString;
737  // Flag to abort the transmission of a command in SendCommandString().
738 
739 
740 // Include platform dependent part of class
741 #ifdef _WIN32
742 #include "msos/ptlib/channel.h"
743 #else
744 #include "unix/ptlib/channel.h"
745 #endif
746 
747 };
748 
749 
750 #endif // PTLIB_CHANNEL_H
751 
752 
753 // End Of File ///////////////////////////////////////////////////////////////
Operation fail due to insufficient privilege.
Definition: channel.h:538
PString ReadString(PINDEX len)
Read len character into a string from the channel.
PINDEX lastWriteCount
Number of byte last written by the Write() function.
Definition: channel.h:723
virtual PBoolean Shutdown(ShutdownValue option)
Close one or both of the data streams associated with a channel.
void AbortCommandString()
Abort a command string that is in progress.
virtual PBoolean Write(const void *buf, PINDEX len)
Low level write to the channel.
PTimeInterval readTimeout
Timeout for read operations.
Definition: channel.h:725
virtual int sync()
Definition: channel.h:569
int GetHandle() const
Get the integer operating system handle for the channel.
Open fail due to file already existing.
Definition: channel.h:534
This class defines an arbitrary time interval to millisecond accuracy.
Definition: timeint.h:55
Definition: channel.h:530
Array of characters.
Definition: array.h:551
Operation failed due to a timeout.
Definition: channel.h:548
virtual void OnWriteComplete(const void *buf, PINDEX len)
User callback function for when a WriteAsync() call has completed or timed out.
Error during other operation, eg Open()
Definition: channel.h:568
virtual PChannel * GetBaseWriteChannel() const
Get the base channel of channel indirection using PIndirectChannel.
virtual PBoolean Read(void *buf, PINDEX len)
Low level read from the channel.
virtual PBoolean Close()
Close the channel, shutting down the link to the data source.
PTimeInterval writeTimeout
Timeout for write operations.
Definition: channel.h:727
PChannel & operator=(const PChannel &)
Definition: channel.h:435
Operation fail due to bad parameters.
Definition: channel.h:542
PTimeInterval GetWriteTimeout() const
Get the timeout for write operations to complete.
virtual PINDEX HashFunction() const
Calculate a hash value for use in sets and dictionaries.
PBoolean WriteString(const PString &str)
Write a string to the channel.
void * iov_base
Definition: channel.h:630
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
size_t iov_len
Definition: channel.h:631
Definition: channel.h:53
Definition: channel.h:434
PChannel()
Create the channel.
virtual PINDEX GetLastWriteCount() const
Get the number of bytes written by the last Write() call.
Open fail due to device or file not found.
Definition: channel.h:532
PBoolean SetBufferSize(PINDEX newSize)
PBoolean ReceiveCommandString(int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
ShutdownValue
Definition: channel.h:433
virtual Comparison Compare(const PObject &obj) const
Get the relative rank of the two strings.
Definition: channel.h:557
PBoolean ReadBlock(void *buf, PINDEX len)
Read len bytes into the buffer from the channel.
Errors
Normalised error codes.
Definition: channel.h:529
int lastErrorNumber[NumErrorGroups+1]
The operating system error number (eg as returned by errno).
Definition: channel.h:719
static PBoolean ConvertOSError(int libcReturnValue, Errors &lastError, int &osError)
Convert an operating system error into platform independent error.
virtual PString GetName() const
Get the platform and I/O channel type name of the channel.
PINDEX lastReadCount
Number of byte last read by the Read() function.
Definition: channel.h:721
std::vector< Slice > VectorOfSlice
Definition: channel.h:635
BOOL PBoolean
Definition: object.h:102
Errors lastErrorCode[NumErrorGroups+1]
The platform independant error code.
Definition: channel.h:717
High level protocol failure.
Definition: channel.h:556
void SetReadTimeout(const PTimeInterval &time)
Set the timeout for read operations.
~PChannel()
Close down the channel.
Error during Read() operation.
Definition: channel.h:566
Definition: channel.h:436
PBoolean SetErrorValues(Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
Set error values to those specified.
void SetWriteTimeout(const PTimeInterval &time)
Set the timeout for write operations to complete.
virtual bool FlowControl(const void *flowData)
Flow Control information Pass data to the channel for flowControl determination.
Abstract class defining I/O channel semantics.
Definition: channel.h:107
PBoolean SendCommandString(const PString &command)
Send a command meta-string.
Errors GetErrorCode(ErrorGroup group=NumErrorGroups) const
Get normalised error code.
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)
int ReadCharWithTimeout(PTimeInterval &timeout)
Read a character with specified timeout.
Operations buffer was too small for data.
Definition: channel.h:552
The character string class.
Definition: pstring.h:108
virtual int_type underflow()
virtual int_type overflow(int_type=EOF)
virtual PINDEX GetLastReadCount() const
Get the number of bytes read by the last Read() call.
PChannelStreamBuffer & operator=(const PChannelStreamBuffer &sbuf)
ErrorGroup
Error groups.
Definition: channel.h:565
Operation fail due to channel not being open yet.
Definition: channel.h:546
Miscellaneous error.
Definition: channel.h:554
Operation fail due to insufficient memory.
Definition: channel.h:544
Error during Write() operation.
Definition: channel.h:567
virtual PBoolean IsOpen() const
Determine if the channel is currently open.
Open fail due to device already open for exclusive use.
Definition: channel.h:540
PTimeInterval GetReadTimeout() const
Get the timeout for read operations.
virtual PBoolean WriteAsync(const void *buf, PINDEX len)
Begin an asynchronous write from channel.
Operation was interrupted.
Definition: channel.h:550
virtual PString GetErrorText(ErrorGroup group=NumErrorGroups) const
Get error message description.
virtual int ReadChar()
Read a single 8 bit byte from the channel.
virtual PChannel * GetBaseReadChannel() const
Get the base channel of channel indirection using PIndirectChannel.
PBoolean SetBufferSize(PINDEX newSize)
Set the iostream buffer size for reads and writes.
virtual bool SetLocalEcho(bool localEcho)
Set local echo mode.
int GetErrorNumber(ErrorGroup group=NumErrorGroups) const
Get OS errro code.
Write fail due to disk full.
Definition: channel.h:536
virtual void OnReadComplete(void *buf, PINDEX len)
User callback function for when a ReadAsync() call has completed or timed out.
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
PChannelStreamBuffer(PChannel *chan)
int os_handle
The operating system file handle return by standard open() function.
Definition: channel.h:715
PBoolean WriteChar(int c)
Write a single character to the channel.
virtual PBoolean ReadAsync(void *buf, PINDEX len)
Begin an asynchronous read from channel.