All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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: 24459 $
* $Author: shorne $
* $Date: 2010-06-06 08:59:59 -0500 (Sun, 06 Jun 2010) $
*/
#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(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);
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 iostream {
PCLASSINFO(PChannel, PObject);
public:
PChannel();
~PChannel();
virtual Comparison Compare(
const PObject & obj
) const;
virtual PINDEX HashFunction() const;
virtual PBoolean IsOpen() const;
virtual PString GetName() const;
int GetHandle() const;
virtual PChannel * GetBaseReadChannel() const;
virtual PChannel * GetBaseWriteChannel() const;
void SetReadTimeout(
const PTimeInterval & time
);
PTimeInterval GetReadTimeout() const;
virtual PBoolean Read(
void * buf,
PINDEX len
);
virtual PINDEX GetLastReadCount() const;
virtual int ReadChar();
PBoolean ReadBlock(
void * buf,
PINDEX len
);
PString ReadString(
PINDEX len
);
virtual PBoolean ReadAsync(
void * buf,
PINDEX len
);
virtual void OnReadComplete(
void * buf,
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
);
virtual PINDEX GetLastWriteCount() const;
PBoolean WriteChar(int c);
PBoolean WriteString(const PString & str);
virtual PBoolean WriteAsync(
const void * buf,
PINDEX len
);
virtual void OnWriteComplete(
const void * buf,
PINDEX len
);
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();
enum Errors {
NoError,
NotFound,
FileExists,
DiskFull,
AccessDenied,
DeviceInUse,
BadParameter,
NoMemory,
NotOpen,
Timeout,
Interrupted,
BufferTooSmall,
Miscellaneous,
ProtocolFailure,
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
);
static PBoolean ConvertOSError(
int libcReturnValue,
Errors & lastError,
int & osError
);
#if P_HAS_RECVMSG
typedef iovec Slice;
#else
struct Slice {
void * iov_base;
size_t iov_len;
};
#endif
typedef std::vector<Slice> VectorOfSlice;
virtual PBoolean Read(
const VectorOfSlice & slices // slices to read to
);
virtual PBoolean Write(
const VectorOfSlice & slices // slices to read to
);
protected:
PChannel(const PChannel &);
PChannel & operator=(const PChannel &);
// Prevent usage by external classes
virtual PBoolean ConvertOSError(
int 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
);
// Member variables
int os_handle;
Errors lastErrorCode[NumErrorGroups+1];
int lastErrorNumber[NumErrorGroups+1];
PINDEX lastReadCount;
PINDEX lastWriteCount;
PTimeInterval readTimeout;
PTimeInterval writeTimeout;
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
};
#endif // PTLIB_CHANNEL_H
// End Of File ///////////////////////////////////////////////////////////////
PChannel::AccessDenied
Operation fail due to insufficient privilege.
Definition: channel.h:538
PChannel::ReadString
PString ReadString(PINDEX len)
Read len character into a string from the channel.
PChannel::lastWriteCount
PINDEX lastWriteCount
Number of byte last written by the Write() function.
Definition: channel.h:723
PChannel::Shutdown
virtual PBoolean Shutdown(ShutdownValue option)
Close one or both of the data streams associated with a channel.
PChannel::AbortCommandString
void AbortCommandString()
Abort a command string that is in progress.
PChannel::Write
virtual PBoolean Write(const void *buf, PINDEX len)
Low level write to the channel.
PChannel::readTimeout
PTimeInterval readTimeout
Timeout for read operations.
Definition: channel.h:725
PChannelStreamBuffer::sync
virtual int sync()
PChannel::NumErrorGroups
Definition: channel.h:569
PChannel::GetHandle
int GetHandle() const
Get the integer operating system handle for the channel.
PChannel::FileExists
Open fail due to file already existing.
Definition: channel.h:534
PTimeInterval
This class defines an arbitrary time interval to millisecond accuracy.
Definition: timeint.h:55
PChannel::NoError
Definition: channel.h:530
PCharArray
Array of characters.
Definition: array.h:551
PChannel::Timeout
Operation failed due to a timeout.
Definition: channel.h:548
PChannel::OnWriteComplete
virtual void OnWriteComplete(const void *buf, PINDEX len)
User callback function for when a WriteAsync() call has completed or timed out.
PChannel::LastGeneralError
Error during other operation, eg Open()
Definition: channel.h:568
PChannel::GetBaseWriteChannel
virtual PChannel * GetBaseWriteChannel() const
Get the base channel of channel indirection using PIndirectChannel.
PChannel::Read
virtual PBoolean Read(void *buf, PINDEX len)
Low level read from the channel.
PChannel::Close
virtual PBoolean Close()
Close the channel, shutting down the link to the data source.
PChannel::writeTimeout
PTimeInterval writeTimeout
Timeout for write operations.
Definition: channel.h:727
PChannel::operator=
PChannel & operator=(const PChannel &)
PChannel::ShutdownWrite
Definition: channel.h:435
PChannel::BadParameter
Operation fail due to bad parameters.
Definition: channel.h:542
PChannel::GetWriteTimeout
PTimeInterval GetWriteTimeout() const
Get the timeout for write operations to complete.
PChannel::HashFunction
virtual PINDEX HashFunction() const
Calculate a hash value for use in sets and dictionaries.
PChannel::WriteString
PBoolean WriteString(const PString &str)
Write a string to the channel.
PChannel::Slice::iov_base
void * iov_base
Definition: channel.h:630
PObject::Comparison
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
PChannel::Slice::iov_len
size_t iov_len
Definition: channel.h:631
PChannelStreamBuffer
Definition: channel.h:53
PChannel::ShutdownRead
Definition: channel.h:434
PChannel::PChannel
PChannel()
Create the channel.
PChannel::GetLastWriteCount
virtual PINDEX GetLastWriteCount() const
Get the number of bytes written by the last Write() call.
PChannel::NotFound
Open fail due to device or file not found.
Definition: channel.h:532
PChannelStreamBuffer::SetBufferSize
PBoolean SetBufferSize(PINDEX newSize)
PChannel::ReceiveCommandString
PBoolean ReceiveCommandString(int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
PChannel::ShutdownValue
ShutdownValue
Definition: channel.h:433
PChannel::Compare
virtual Comparison Compare(const PObject &obj) const
Get the relative rank of the two strings.
PChannel::NumNormalisedErrors
Definition: channel.h:557
PChannel::ReadBlock
PBoolean ReadBlock(void *buf, PINDEX len)
Read len bytes into the buffer from the channel.
PChannel::Errors
Errors
Normalised error codes.
Definition: channel.h:529
PChannel::lastErrorNumber
int lastErrorNumber[NumErrorGroups+1]
The operating system error number (eg as returned by errno).
Definition: channel.h:719
PChannel::ConvertOSError
static PBoolean ConvertOSError(int libcReturnValue, Errors &lastError, int &osError)
Convert an operating system error into platform independent error.
PChannel::GetName
virtual PString GetName() const
Get the platform and I/O channel type name of the channel.
PChannel::lastReadCount
PINDEX lastReadCount
Number of byte last read by the Read() function.
Definition: channel.h:721
PChannel::VectorOfSlice
std::vector< Slice > VectorOfSlice
Definition: channel.h:635
PBoolean
BOOL PBoolean
Definition: object.h:102
PChannel::lastErrorCode
Errors lastErrorCode[NumErrorGroups+1]
The platform independant error code.
Definition: channel.h:717
PChannel::ProtocolFailure
High level protocol failure.
Definition: channel.h:556
PChannel::SetReadTimeout
void SetReadTimeout(const PTimeInterval &time)
Set the timeout for read operations.
PChannel::~PChannel
~PChannel()
Close down the channel.
PChannel::LastReadError
Error during Read() operation.
Definition: channel.h:566
PChannel::ShutdownReadAndWrite
Definition: channel.h:436
PChannel::SetErrorValues
PBoolean SetErrorValues(Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
Set error values to those specified.
PChannel::SetWriteTimeout
void SetWriteTimeout(const PTimeInterval &time)
Set the timeout for write operations to complete.
PChannel::FlowControl
virtual bool FlowControl(const void *flowData)
Flow Control information Pass data to the channel for flowControl determination.
PChannel
Abstract class defining I/O channel semantics.
Definition: channel.h:107
PChannel::SendCommandString
PBoolean SendCommandString(const PString &command)
Send a command meta-string.
PChannel::GetErrorCode
Errors GetErrorCode(ErrorGroup group=NumErrorGroups) const
Get normalised error code.
PChannelStreamBuffer::seekoff
virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode=ios_base::in|ios_base::out)
PChannelStreamBuffer::seekpos
virtual pos_type seekpos(pos_type, ios_base::openmode=ios_base::in|ios_base::out)
PChannel::ReadCharWithTimeout
int ReadCharWithTimeout(PTimeInterval &timeout)
Read a character with specified timeout.
PChannel::BufferTooSmall
Operations buffer was too small for data.
Definition: channel.h:552
PString
The character string class.
Definition: pstring.h:108
PChannelStreamBuffer::underflow
virtual int_type underflow()
PChannelStreamBuffer::overflow
virtual int_type overflow(int_type=EOF)
mutex.h
PChannel::GetLastReadCount
virtual PINDEX GetLastReadCount() const
Get the number of bytes read by the last Read() call.
PChannelStreamBuffer::operator=
PChannelStreamBuffer & operator=(const PChannelStreamBuffer &sbuf)
PChannel::ErrorGroup
ErrorGroup
Error groups.
Definition: channel.h:565
PChannel::NotOpen
Operation fail due to channel not being open yet.
Definition: channel.h:546
PChannel::Miscellaneous
Miscellaneous error.
Definition: channel.h:554
PChannel::NoMemory
Operation fail due to insufficient memory.
Definition: channel.h:544
PChannel::LastWriteError
Error during Write() operation.
Definition: channel.h:567
PChannel::IsOpen
virtual PBoolean IsOpen() const
Determine if the channel is currently open.
PChannel::DeviceInUse
Open fail due to device already open for exclusive use.
Definition: channel.h:540
PChannel::GetReadTimeout
PTimeInterval GetReadTimeout() const
Get the timeout for read operations.
PChannel::WriteAsync
virtual PBoolean WriteAsync(const void *buf, PINDEX len)
Begin an asynchronous write from channel.
PChannel::Interrupted
Operation was interrupted.
Definition: channel.h:550
PChannel::GetErrorText
virtual PString GetErrorText(ErrorGroup group=NumErrorGroups) const
Get error message description.
PChannel::ReadChar
virtual int ReadChar()
Read a single 8 bit byte from the channel.
PChannel::GetBaseReadChannel
virtual PChannel * GetBaseReadChannel() const
Get the base channel of channel indirection using PIndirectChannel.
PChannel::SetBufferSize
PBoolean SetBufferSize(PINDEX newSize)
Set the iostream buffer size for reads and writes.
PChannel::SetLocalEcho
virtual bool SetLocalEcho(bool localEcho)
Set local echo mode.
PChannel::GetErrorNumber
int GetErrorNumber(ErrorGroup group=NumErrorGroups) const
Get OS errro code.
PChannel::Slice
Structure that defines a "slice" of memory to be written to.
Definition: channel.h:629
PChannel::DiskFull
Write fail due to disk full.
Definition: channel.h:536
PChannel::OnReadComplete
virtual void OnReadComplete(void *buf, PINDEX len)
User callback function for when a ReadAsync() call has completed or timed out.
PObject
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
PChannelStreamBuffer::PChannelStreamBuffer
PChannelStreamBuffer(PChannel *chan)
PChannel::os_handle
int os_handle
The operating system file handle return by standard open() function.
Definition: channel.h:715
PChannel::WriteChar
PBoolean WriteChar(int c)
Write a single character to the channel.
PChannel::ReadAsync
virtual PBoolean ReadAsync(void *buf, PINDEX len)
Begin an asynchronous read from channel.