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

#include <SocketSelector.h++>

Collaboration diagram for Connection:

[legend]

Public Member Functions
virtual	~Connection ()
	Destructor. More...

bool	writeData (ByteBuffer &buffer)
	Write data on the connection. More...

bool	writeData (const byte_t *buf, size_t count)
	Write data on the connection. More...

bool	writeLine (const String &text)
	Write a "line" of text followed by a CR+LF terminator on the connection. More...

void	beginWrite ()

void	endWrite ()

void	cancelWrite ()

size_t	readData (ByteBuffer &buffer, bool fully=true)
	Read data on the connection. More...

size_t	readData (byte_t *buf, size_t count, bool fully=true)
	Read data on the connection. More...

size_t	readLine (String &text, size_t maxLen)
	Read a "line" of text followed by a CR+LF terminator on the connection. More...

uint32_t	readUInt32 ()
	Read a 32-bit unsigned integer (assumed to be in network byte order) from the connection. More...

uint64_t	readUInt64 ()
	Read a 64-bit unsigned integer (assumed to be in network byte order) from the connection. More...

StreamSocket *	getSocket ()
	Get the socket for this connection. More...

void	setReadLowWaterMark (size_t count)
	Set the read low-water mark for the connection. More...

void	setReadHighWaterMark (size_t count)
	Set the read high-water mark for the connection. More...

size_t	getReadLowWaterMark () const
	Get the current value of the read low-water mark. More...

bool	isReadLow () const
	Test if the amount of data available to be read on the connection is less than the read low-water mark. More...

bool	isReadHigh () const
	Test if the amount of data available to be read on the connection is greater than or equal to the read high-water mark. More...

void	setWriteLowWaterMark (size_t count)
	Set the write low-water mark for the connection. More...

void	setWriteHighWaterMark (size_t count)
	Set the write high-water mark for the connection. More...

size_t	getWriteLowWaterMark () const
	Get the current value of the write low-water mark. More...

size_t	getWriteHighWaterMark () const
	Get the current value of the write high-water mark. More...

bool	isWriteLow () const
	Test if the amount of data queued to be written on the connection is less than the write low-water mark. More...

bool	isWriteHigh () const
	Test if the amount of data queued to be written on the connection is greater than or equal to the write high-water mark. More...

size_t	getBytesAvailableToRead () const
	Returns the number of bytes available to be read. More...

size_t	getBytesAvailableToWrite () const
	Returns the number of bytes available to be written. More...

void	close (bool immediate=false)
	Close the connection. More...

byte_t	getOOBData ()
	Get any pending out-of-band data byte, and clear the OOB flag. More...

bool	getOOBFlag () const
	Test the out-of-band flag. More...

time_ms_t	getTimestamp () const
	Get the time at which data was last received on this connection. More...

bool	isClosePending () const
	Test if a close is pending on the connection. More...

Static Public Attributes
static const size_t	DEFAULT_BUFFER_SIZE = 4096
	The default I/O buffer size. More...

Protected Member Functions
	Connection (size_t bufferSize=DEFAULT_BUFFER_SIZE)
	Construct a new Connection. More...

Protected Attributes
CircularByteBuffer	readBuffer

CircularByteBuffer	writeBuffer

Friends
class	SocketSelector

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()

~Connection ( )

virtual

Destructor.

◆ Connection()

Connection ( size_t bufferSize = DEFAULT_BUFFER_SIZE )

protected

Construct a new Connection.

Parameters

bufferSize The size for the I/O buffers.

Member Function Documentation

◆ beginWrite()

void beginWrite ( )

◆ cancelWrite()

void cancelWrite ( )

◆ close()

void close ( bool immediate = false )

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.

◆ endWrite()

void endWrite ( )

◆ getBytesAvailableToRead()

size_t getBytesAvailableToRead ( ) const

Returns the number of bytes available to be read.

◆ getBytesAvailableToWrite()

size_t getBytesAvailableToWrite ( ) const

Returns the number of bytes available to be written.

◆ getOOBData()

byte_t getOOBData ( )

inline

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

Returns: The most recent byte of OOB data received.

◆ getOOBFlag()

bool getOOBFlag ( ) const

inline

Test the out-of-band flag.

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

◆ getReadLowWaterMark()

size_t getReadLowWaterMark ( ) const

inline

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

Returns: The low-water mark, in bytes.

◆ getSocket()

StreamSocket* getSocket ( )

inline

Get the socket for this connection.

◆ getTimestamp()

time_ms_t getTimestamp ( ) const

inline

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

◆ getWriteHighWaterMark()

size_t getWriteHighWaterMark ( ) const

inline

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

Returns: The high-water mark, in bytes.

◆ getWriteLowWaterMark()

size_t getWriteLowWaterMark ( ) const

inline

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

Returns: The low-water mark, in bytes.

◆ isClosePending()

bool isClosePending ( ) const

Test if a close is pending on the connection.

◆ isReadHigh()

bool isReadHigh ( ) const

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

◆ isReadLow()

bool isReadLow ( ) const

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

◆ isWriteHigh()

bool isWriteHigh ( ) const

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

◆ isWriteLow()

bool isWriteLow ( ) const

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

◆ readData() [1/2]

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.

◆ readData() [2/2]

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.

◆ readLine()

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.

◆ readUInt32()

uint32_t readUInt32 ( )

Read a 32-bit unsigned integer (assumed to be in network byte order) from the connection.

Returns: The value read, or 0 if there aren't at least 4 bytes available to be read.

◆ readUInt64()

uint64_t readUInt64 ( )

Read a 64-bit unsigned integer (assumed to be in network byte order) from the connection.

Returns: The value read, or 0 if there aren't at least 8 bytes available to be read.

◆ setReadHighWaterMark()

void setReadHighWaterMark ( size_t count )

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 SocketSelector 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.

◆ setReadLowWaterMark()

void setReadLowWaterMark ( size_t count )

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 SocketSelector::dataReceived() callback is invoked for the connection. The default value is 1.

Parameters

count The low-water mark, in bytes.

◆ setWriteHighWaterMark()

void setWriteHighWaterMark ( size_t count )

Set the write high-water mark for the connection.

The SocketSelector 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.

◆ setWriteLowWaterMark()

void setWriteLowWaterMark ( size_t count )

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 SocketSelector 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.

◆ writeData() [1/2]

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.

◆ writeData() [2/2]

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.

◆ writeLine()

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

◆ SocketSelector

friend class SocketSelector

friend

Member Data Documentation

◆ DEFAULT_BUFFER_SIZE

const size_t DEFAULT_BUFFER_SIZE = 4096

static

The default I/O buffer size.

◆ readBuffer

CircularByteBuffer readBuffer

protected

◆ writeBuffer

CircularByteBuffer writeBuffer

protected

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

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~Connection()

◆ Connection()

Member Function Documentation

◆ beginWrite()

◆ cancelWrite()

◆ close()

◆ endWrite()

◆ getBytesAvailableToRead()

◆ getBytesAvailableToWrite()

◆ getOOBData()

◆ getOOBFlag()

◆ getReadLowWaterMark()

◆ getSocket()

◆ getTimestamp()

◆ getWriteHighWaterMark()

◆ getWriteLowWaterMark()

◆ isClosePending()

◆ isReadHigh()

◆ isReadLow()

◆ isWriteHigh()

◆ isWriteLow()

◆ readData() [1/2]

◆ readData() [2/2]

◆ readLine()

◆ readUInt32()

◆ readUInt64()

◆ setReadHighWaterMark()

◆ setReadLowWaterMark()

◆ setWriteHighWaterMark()

◆ setWriteLowWaterMark()

◆ writeData() [1/2]

◆ writeData() [2/2]

◆ writeLine()

Friends And Related Function Documentation

◆ SocketSelector

Member Data Documentation

◆ DEFAULT_BUFFER_SIZE

◆ readBuffer

◆ writeBuffer