Connection Class Reference

An abstract object representing a network connection. More...

#include <SocketMuxer.h++>

Collaboration diagram for Connection:

[legend]

List of all members.

Public Member Functions
virtual	~Connection () throw ()
	Destructor.
bool	writeData (ByteBuffer &buffer)
	Write data on the connection.
bool	writeData (const byte_t *buf, size_t count)
	Write data on the connection.
bool	writeLine (const String &text)
	Write a "line" of text followed by a CR+LF terminator on the connection.
size_t	readData (ByteBuffer &buffer, bool fully=true)
	Read data on the connection.
size_t	readData (byte_t *buf, size_t count, bool fully=true)
	Read data on the connection.
size_t	readLine (String &text, size_t maxLen)
	Read a "line" of text followed by a CR+LF terminator on the connection.
StreamSocket *	getSocket () throw ()
	Get the socket for this connection.
void	setReadLowWaterMark (size_t count) throw ()
	Set the read low-water mark for the connection.
void	setReadHighWaterMark (size_t count) throw ()
	Set the read high-water mark for the connection.
size_t	getReadLowWaterMark () const throw ()
	Get the current value of the read low-water mark.
bool	isReadLow () const throw ()
	Test if the amount of data available to be read on the connection is less than the read low-water mark.
bool	isReadHigh () const throw ()
	Test if the amount of data available to be read on the connection is greater than or equal to the read high-water mark.
void	setWriteLowWaterMark (size_t count) throw ()
	Set the write low-water mark for the connection.
void	setWriteHighWaterMark (size_t count) throw ()
	Set the write high-water mark for the connection.
size_t	getWriteLowWaterMark () const throw ()
	Get the current value of the write low-water mark.
size_t	getWriteHighWaterMark () const throw ()
	Get the current value of the write high-water mark.
bool	isWriteLow () const throw ()
	Test if the amount of data queued to be written on the connection is less than the write low-water mark.
bool	isWriteHigh () const throw ()
	Test if the amount of data queued to be written on the connection is greater than or equal to the write high-water mark.
void	close (bool immediate=false) throw ()
	Close the connection.
byte_t	getOOBData () throw ()
	Get any pending out-of-band data byte, and clear the OOB flag.
bool	getOOBFlag () const throw ()
	Test the out-of-band flag.
time_ms_t	getTimestamp () const throw ()
	Get the time at which data was last received on this connection.
bool	isClosePending () const throw ()
	Test if a close is pending on the connection.
Static Public Attributes
static const size_t	DEFAULT_BUFFER_SIZE = 4096
	The default I/O buffer size.
Protected Member Functions
	Connection (size_t bufferSize=DEFAULT_BUFFER_SIZE)
	Construct a new Connection.
Protected Attributes
CircularByteBuffer	readBuffer
CircularByteBuffer	writeBuffer
Friends
class	SocketMuxer

---

Detailed Description

An abstract object representing a network connection.

It holds a reference to a connected StreamSocket, and is intended to be subclassed to include application-specific data and/or logic associated with the connection.

Author:

Mark Lindner

---

Constructor & Destructor Documentation

~Connection

(

)

throw () [virtual]

Destructor.

Connection

(

size_t

bufferSize = DEFAULT_BUFFER_SIZE

)

[protected]

Construct a new Connection.

Parameters:

bufferSize

The size for the I/O buffers.

---

Member Function Documentation

void close

(

bool

immediate = false

)

throw ()

Close the connection.

Parameters:

immediate

If true, close the connection immediately, even if data is still in the write buffer; otherwise, close the connection after all pending data has been written.

byte_t getOOBData

(

)

throw () [inline]

Get any pending out-of-band data byte, and clear the OOB flag.

Returns:

The most recent byte of OOB data received.

bool getOOBFlag

(

)

const throw () [inline]

Test the out-of-band flag.

Returns:

true if a byte of OOB data is pending, false otherwise.

size_t getReadLowWaterMark

(

)

const throw () [inline]

Get the current value of the read low-water mark.

Returns:

The low-water mark, in bytes.

StreamSocket* getSocket

(

)

throw () [inline]

Get the socket for this connection.

time_ms_t getTimestamp

(

)

const throw () [inline]

Get the time at which data was last received on this connection.

size_t getWriteHighWaterMark

(

)

const throw () [inline]

Get the current value of the write high-water mark.

Returns:

The high-water mark, in bytes.

size_t getWriteLowWaterMark

(

)

const throw () [inline]

Get the current value of the write low-water mark.

Returns:

The low-water mark, in bytes.

bool isClosePending

(

)

const throw ()

Test if a close is pending on the connection.

bool isReadHigh

(

)

const throw ()

Test if the amount of data available to be read on the connection is greater than or equal to the read high-water mark.

bool isReadLow

(

)

const throw ()

Test if the amount of data available to be read on the connection is less than the read low-water mark.

bool isWriteHigh

(

)

const throw ()

Test if the amount of data queued to be written on the connection is greater than or equal to the write high-water mark.

bool isWriteLow

(

)

const throw ()

Test if the amount of data queued to be written on the connection is less than the write low-water mark.

size_t readData	(	byte_t *	buf,
		size_t	count,
		bool	fully = true
	)

Read data on the connection.

Reads data that has already been received on the connection.

Parameters:

	buf	The buffer to which the data should be written.
	count	The number of bytes to read.
	fully	If true, fail if there is not enough data available to fill the buffer.

Returns:

The number of bytes read.

size_t readData	(	ByteBuffer &	buffer,
		bool	fully = true
	)

Read data on the connection.

Reads data that has already been received on the connection.

Parameters:

	buffer	The buffer to which the data should be written.
	fully	If true, fail if there is not enough data available to fill the buffer.

Returns:

The number of bytes read.

size_t readLine	(	String &	text,
		size_t	maxLen
	)

Read a "line" of text followed by a CR+LF terminator on the connection.

The terminator is not discarded.

Parameters:

	text	The String to read the text into.
	maxLen	The maximum number of characters to read (including the CR+LF terminator).

Returns:

The number of characters read.

void setReadHighWaterMark

(

size_t

count

)

throw ()

Set the read high-water mark for the connection.

If the amount of data in the input buffer reaches or exceeds the high-water mark, the SocketMuxer will stop attempting to receive more data on this connection until the amount of data in the input buffer falls below the high-water mark.

Parameters:

count

The low-water mark, in bytes.

void setReadLowWaterMark

(

size_t

count

)

throw ()

Set the read low-water mark for the connection.

This is the minimum amount of data that must be available in the input buffer before the SocketMuxer::dataReceived() callback is invoked for the connection. The default value is 1.

Parameters:

count

The low-water mark, in bytes.

void setWriteHighWaterMark

(

size_t

count

)

throw ()

Set the write high-water mark for the connection.

The SocketMuxer does not use this value directly, but subclasses of Connection may choose to use it when implementing an output throttling strategy.

Parameters:

count

The high-water mark, in bytes.

void setWriteLowWaterMark

(

size_t

count

)

throw ()

Set the write low-water mark for the connection.

If the amount of data queued in the output buffer drops below the high-water mark, the SocketMuxer will stop attempting to transmit the queued data over the connection until the amount of data in the output buffer rises above the low-water mark. The default value is 1.

Parameters:

count

The low-water mark, in bytes.

bool writeData	(	const byte_t *	buf,
		size_t	count
	)

Write data on the connection.

The data is enqueued for transmission on the connection.

Parameters:

	buf	The buffer containing the data to be sent.
	count	The number of elements to write.

Returns:

true if the data was successfully enqueued, false if there was not enough room in the output buffer to enqueue the data.

bool writeData

(

ByteBuffer &

buffer

)

Write data on the connection.

The data is enqueued for transmission on the connection.

Parameters:

buffer

The buffer containing the data to be sent.

Returns:

true if the data was successfully enqueued, false if there was not enough room in the output buffer to enqueue the data.

bool writeLine

(

const String &

text

)

Write a "line" of text followed by a CR+LF terminator on the connection.

Parameters:

text

The text to write.

Returns:

true if the data was successfully enqueued, false if there was not enough room in the output buffer to enqueue the data.

---

Friends And Related Function Documentation

friend class SocketMuxer [friend]

---

Member Data Documentation

const size_t DEFAULT_BUFFER_SIZE = 4096 [static]

The default I/O buffer size.

CircularByteBuffer readBuffer [protected]

CircularByteBuffer writeBuffer [protected]

---

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

• SocketMuxer.h++
• SocketMuxer.c++