IODevice Class Reference

The IODevice class provides a framework for reading and writing to device. More...

#include <iodevice.h>

Public Types
enum	Flags {   None = 0 , FlushesOnEndl = 1 << 0 , HasInputLimit = 1 << 1 , HasOutputLimit = 1 << 2 , IsEnabled = 1 << 3 ,   HasTimeout = 1 << 4 }
enum	Error { Unknown , Timeout }
enum	LogLevel { ErrorLevel , InfoLevel , WarningLevel , DebugLevel }

Public Member Functions
	IODevice (int f=0)
virtual	~IODevice (void)
void	clear (void)
void	setFlags (unsigned int f)
void	clearFlags (unsigned int f)
void	setMaxInputBufferSize (unsigned int max)
void	setMaxOutputBufferSize (unsigned int max)
void	setTimeout (unsigned int t)
unsigned int	getTimeout (void) const
void	setOutputLevel (LogLevel level)
LogLevel	getOutputLevel (void) const
void	setOutputLevelLimit (LogLevel level)
LogLevel	getOutputLevelLimit (void) const
unsigned int	getReadCount (void) const
unsigned int	getWriteCount (void) const
void	enableProtocolDumping (void)
template<class T >
IODevice &	operator<< (const T &source)
IODevice &	operator<< (std::ostream &(*source)(std::ostream &))
virtual bool	canRead (void) const
bool	readStr (std::string *dest, unsigned int max=0)
bool	readChar (char *dest=0)
void	unreadChar (char c)
void	unreadStr (const std::string &s)
bool	skipTo (char c)
bool	flush (void)
Error	getLastError (void) const
std::string	getLastErrorString (void) const
virtual std::string	service (void) const

Protected Types
enum	WriteResult { WriteWait = 0 , WriteDone = 1 << 0 , WriteError = 1 << 1 }

Protected Member Functions
virtual bool	waitForWrite (void) const
virtual bool	waitForRead (void) const
virtual WriteResult	write (void)
virtual bool	fillInputBuffer (void)

Protected Attributes
BincStream	inputBuffer
BincStream	outputBuffer
unsigned int	flags
unsigned int	maxInputBufferSize
unsigned int	maxOutputBufferSize
unsigned int	timeout
unsigned int	readCount
unsigned int	writeCount
LogLevel	outputLevel
LogLevel	outputLevelLimit
Error	error
std::string	errorString
int	dumpfd

Detailed Description

The IODevice class provides a framework for reading and writing to device.

Implement new devices by inheriting this class and overloading all virtual methods.

service() returns the service that the specific device is used for. Two values are "log" and "client".

See also

IOFactory, MultilogDevice, SyslogDevice, StdIODevice

Definition at line 31 of file iodevice.h.

Member Enumeration Documentation

Error

enum Error

Errors from when an operation returned false.

Enumerator
Unknown
Timeout

Definition at line 48 of file iodevice.h.

Flags

enum Flags

Standard options for an IODevice.

Enumerator
None
FlushesOnEndl
HasInputLimit
HasOutputLimit
IsEnabled
HasTimeout

Definition at line 36 of file iodevice.h.

LogLevel

enum LogLevel

Enumerator
ErrorLevel
InfoLevel
WarningLevel
DebugLevel

Definition at line 135 of file iodevice.h.

WriteResult

enum WriteResult

protected

Types of results from a write.

Enumerator
WriteWait
WriteDone
WriteError

Definition at line 313 of file iodevice.h.

Constructor & Destructor Documentation

IODevice()

IODevice

(

int

f = 0

)

Constructs an invalid IODevice.

Instances of IODevice perform no operations, and all boolean functions always return false. This constructor is only useful if called from a subclass that reimplements all virtual methods.

Definition at line 18 of file iodevice.cc.

~IODevice()

~IODevice ( void  )

virtual

Destructs an IODevice; does nothing.

Definition at line 31 of file iodevice.cc.

Member Function Documentation

canRead()

bool canRead ( void  ) const

virtual

Returns true if data can be read from the device; otherwise returns false.

Reimplemented in StdIODevice.

Definition at line 59 of file iodevice.cc.

clear()

void clear

(

void

)

Clears all data in the input and output buffers.

Definition at line 65 of file iodevice.cc.

Here is the call graph for this function:

clearFlags()

void clearFlags

(

unsigned int

f

)

Clears one or more flags.

Parameters

f	A bitwise OR of flags from the Flags enum.

Definition at line 100 of file iodevice.cc.

Here is the caller graph for this function:

enableProtocolDumping()

void enableProtocolDumping

(

void

)

Calling this function enables the built-in protocol dumping feature in the device. All input and output to this device will be dumped to a file in /tmp.

Definition at line 274 of file iodevice.cc.

Here is the call graph for this function:

fillInputBuffer()

bool fillInputBuffer ( void  )

protectedvirtual

Reads data from the device, and stores it in the input buffer. Returns true on success; otherwise returns false.

This method will fail if there is no more data available, if a timeout occurred or if an error with the device prevents more data from being read.

The number of bytes read from the device is undefined.

Reimplemented in MultilogDevice, StdIODevice, and SyslogDevice.

Definition at line 244 of file iodevice.cc.

Here is the caller graph for this function:

flush()

bool flush

(

void

)

Flushes the output buffer. Writes all data in the output buffer to the device.

Definition at line 74 of file iodevice.cc.

Here is the call graph for this function:

Here is the caller graph for this function:

getLastError()

IODevice::Error getLastError

(

void

)

const

Returns the type of error that most recently occurred.

Definition at line 250 of file iodevice.cc.

getLastErrorString()

string getLastErrorString

(

void

)

const

Returns a human readable description of the error that most recently occurred. If no known error has occurred, this method returns "Unknown error".

Definition at line 256 of file iodevice.cc.

getOutputLevel()

IODevice::LogLevel getOutputLevel

(

void

)

const

Returns the current output level.

See also

setOutputLevel()

Definition at line 141 of file iodevice.cc.

getOutputLevelLimit()

IODevice::LogLevel getOutputLevelLimit

(

void

)

const

Returns the current output level limit.

See also

setOutputLevelLimit()

Definition at line 153 of file iodevice.cc.

getReadCount()

unsigned int getReadCount

(

void

)

const

Returns the number of bytes that have been read from this device since it was created.

Definition at line 262 of file iodevice.cc.

getTimeout()

unsigned int getTimeout

(

void

)

const

Returns the timeout in seconds, or 0 if there is no timeout.

See also

setTimeout()

Definition at line 129 of file iodevice.cc.

Here is the caller graph for this function:

getWriteCount()

unsigned int getWriteCount

(

void

)

const

Returns the number of bytes that have been written to this device since it was created.

Definition at line 268 of file iodevice.cc.

operator<<() [1/2]

IODevice & operator<<

(

const T &

source

)

Writes data to the device. Depending on the value of the max output buffer size, the data may not be written immediately.

See also

setMaxOutputBufferSize()

Definition at line 361 of file iodevice.h.

Here is the call graph for this function:

operator<<() [2/2]

IODevice & operator<<

(

std::ostream &(*)(std::ostream &)

source

)

Writes data to the device. This function specializes on standard ostream derivates, such as std::endl.

readChar()

bool readChar

(

char *

dest = 0

)

Reads exactly one byte from the device and stores this in a char. Returns true on success; otherwise returns false.

Parameters

dest	The incoming byte is stored in this char.

Definition at line 182 of file iodevice.cc.

Here is the call graph for this function:

readStr()

bool readStr	(	std::string *	dest,
		unsigned int	max = 0
	)

Reads data from the device, and stores this in a string. Returns true on success; otherwise returns false.

Parameters

dest	The incoming data is stored in this string.
max	No more than this number of bytes is read from the device.

Definition at line 159 of file iodevice.cc.

Here is the call graph for this function:

service()

string service ( void  ) const

virtual

Returns the type of service provided by this device. Two valid return values are "client" and "log".

Reimplemented in MultilogDevice, StdIODevice, and SyslogDevice.

Definition at line 220 of file iodevice.cc.

Here is the caller graph for this function:

setFlags()

void setFlags

(

unsigned int

f

)

Sets one or more flags.

Parameters

f	A bitwise OR of flags from the Flags enum.

Definition at line 94 of file iodevice.cc.

Here is the caller graph for this function:

setMaxInputBufferSize()

void setMaxInputBufferSize

(

unsigned int

max

)

Sets the maximum allowed input buffer size. If this size is non-zero and exceeded, reading from the device will fail. This functionality is used to prevent clients from forcing this class to consume so much memory that the program crashes.

Setting the max input buffer size to 0 disables the input size limit.

Parameters

max	The maximum input buffer size in bytes.

Definition at line 106 of file iodevice.cc.

setMaxOutputBufferSize()

void setMaxOutputBufferSize

(

unsigned int

max

)

Sets the maximum allowed output buffer size. If this size is non-zero and exceeded, flush() is called implicitly.

Setting the max output buffer size to 0 disables the output size limit. This is generally discouraged.

As a contrast to setMaxInputBufferSize(), this function is used to bundle up consequent write calls, allowing more efficient use of the underlying device as larger blocks of data are written at a time.

Parameters

max	The maximum output buffer size in bytes.

Definition at line 112 of file iodevice.cc.

Here is the caller graph for this function:

setOutputLevel()

void setOutputLevel

(

LogLevel

level

)

Sets the output level for the following write operations on this device.

The output level is a number which gives the following write operations a priority. You can use setOutputLevelLimit() to filter the write operations valid for different operating modes. This enables you to have certain write operations ignored.

For instance, if the output level is set to 0, then "Hello" is written, and the output level is set to 1, followed by writing "Daisy", the output level limit value will decive wether only "Hello" is written, or if also "Daisy" is written.

A low value of the level gives higher priority, and a high level will give low priority. The default value is 0, and write operations that are done with output level 0 are never ignored.

Parameters

level

The output level

See also

getOutputLevel(), setOutputLevelLimit()

Definition at line 135 of file iodevice.cc.

setOutputLevelLimit()

void setOutputLevelLimit

(

LogLevel

level

)

Sets the current output level limit. Write operations with a level higher than the output level limit are ignored.

Parameters

level

The output level limit

See also

setOutputLevel()

Definition at line 147 of file iodevice.cc.

Here is the caller graph for this function:

setTimeout()

void setTimeout

(

unsigned int

t

)

Sets the device's internal timeout in seconds. This timeout is used both when waiting for data to read and for waiting for the ability to write.

If this timeout is exceeded, the read or write function that triggered the timeout will fail.

Setting the timeout to 0 disables the timeout.

Parameters

t	The timeout in seconds.

See also

getTimeout()

Definition at line 118 of file iodevice.cc.

skipTo()

bool skipTo

(

char

c

)

Reads characters from the device, until and including one certain character is found. All read characters are discarded.

This function can be used to skip to the beginning of a line, with the terminating character being '
'.

Parameters

The	certain character.

Definition at line 208 of file iodevice.cc.

Here is the call graph for this function:

unreadChar()

void unreadChar

(

char

c

)

FIXME: add docs

Definition at line 196 of file iodevice.cc.

Here is the call graph for this function:

unreadStr()

void unreadStr

(

const std::string &

s

)

FIXME: add docs

Definition at line 202 of file iodevice.cc.

Here is the call graph for this function:

waitForRead()

bool waitForRead ( void  ) const

protectedvirtual

Waits until data can be read from the device.

See also

waitForWrite()

Reimplemented in MultilogDevice, StdIODevice, and SyslogDevice.

Definition at line 232 of file iodevice.cc.

waitForWrite()

bool waitForWrite ( void  ) const

protectedvirtual

Waits until data can be written to the device. If the timeout is 0, this function waits indefinitely. Otherwise, it waits until the timeout has expired.

If this function returns true, data can be written to the device; otherwise, getLastError() must be checked to determine whether a timeout occurred or whether an error with the device prevents further writing.

Reimplemented in MultilogDevice, StdIODevice, and SyslogDevice.

Definition at line 226 of file iodevice.cc.

Here is the caller graph for this function:

write()

IODevice::WriteResult write ( void  )

protectedvirtual

Writes as much data as possible to the device. If some but not all data was written, returns WriteWait. If all data was written, returns WriteDone. If an error occurred, returns WriteError.

Reimplemented in MultilogDevice, StdIODevice, and SyslogDevice.

Definition at line 238 of file iodevice.cc.

Here is the caller graph for this function:

Field Documentation

dumpfd

int dumpfd

protected

Definition at line 357 of file iodevice.h.

error

Error error

mutableprotected

Definition at line 354 of file iodevice.h.

errorString

std::string errorString

mutableprotected

Definition at line 355 of file iodevice.h.

flags

unsigned int flags

protected

Definition at line 342 of file iodevice.h.

inputBuffer

BincStream inputBuffer

protected

Definition at line 339 of file iodevice.h.

maxInputBufferSize

unsigned int maxInputBufferSize

protected

Definition at line 343 of file iodevice.h.

maxOutputBufferSize

unsigned int maxOutputBufferSize

protected

Definition at line 344 of file iodevice.h.

outputBuffer

BincStream outputBuffer

protected

Definition at line 340 of file iodevice.h.

outputLevel

LogLevel outputLevel

protected

Definition at line 351 of file iodevice.h.

outputLevelLimit

LogLevel outputLevelLimit

protected

Definition at line 352 of file iodevice.h.

readCount

unsigned int readCount

protected

Definition at line 348 of file iodevice.h.

timeout

unsigned int timeout

protected

Definition at line 346 of file iodevice.h.

writeCount

unsigned int writeCount

protected

Definition at line 349 of file iodevice.h.

---

The documentation for this class was generated from the following files:

• 2.0/bincimap-2.0.16/src/include/iodevice.h
• 2.0/bincimap-2.0.16/src/iodevice.cc