A ByteStream is an object that is basically a big wrapper around a character buffer. More...

#include <bytestream.hpp>

Public Types
enum	Access { READ_ONLY, READ_WRITE }
	This defines the kind of access that a ByteStream will have. More...

Public Member Functions
	ByteStream ()
	Default constructor; this creates a new, empty ByteStream.

	~ByteStream ()
	Destructor.

void	copyFrom (const std::string &bytes, Access access)
	This copies the bytes from the given string into the ByteStream's character buffer. More...

void	copyFrom (const std::vector< char > &bytes, Access access)
	This copies the bytes from the given vector into the ByteStream's character buffer. More...

void	copyFrom (const ByteStream &byteStream, Access access)
	This copies the bytes from the given ByteStream into the ByteStream's character buffer. More...

void	linkFrom (char *bytes, unsigned int bytesSize, Access access)
	This links the bytes given to the ByteStream's character buffer. More...

void	copyTo (std::vector< char > &buffer) const
	This copies the portion of the ByteStream that's currently available for reading to the specified target. More...

void	copyTo (std::string &buffer) const
	This copies the portion of the ByteStream that's currently available for reading to the specified target. More...

int	compareWith (const char *buffer, unsigned int bufferLength) const
	This compares the ByteStream to the given character buffer and returns the equivalent of "memcmp". More...

const bool	isErrored () const
	This returns whether or not the stream is in an errored state. More...

const bool	lastReadTimedOut () const
	If the last "read*" function failed, then this will return whether or not the cause was a timeout. More...

const bool	isLive () const
	This returns whether or not the stream is connected to "live" data, such as a socket. More...

void	setLive (bool isLive)
	This sets the "live" state of the stream. More...

std::chrono::milliseconds	readTimeout () const
	This returns the current read timeout for the stream. More...

void	readTimeout (const std::chrono::milliseconds &timeout)
	This sets the read timeout for the stream. More...

unsigned int	remainingReadLength () const
	This returns the number of bytes remaining in the stream. More...

unsigned int	remainingWriteLength () const
	This returns the number of bytes remaining in the stream. More...

void	reset ()
	This resets the internal character buffer (if owned by the ByteStream). More...

bool	peekByte (char &byte)
	This reads a byte from the ByteStream. More...

bool	readByte (char &byte)
	This reads a byte from the ByteStream. More...

bool	readBytes (char *buffer, unsigned int bufferSize, unsigned int &bytesRead)
	This reads an arbitrary amount of bytes into the specified character buffer. More...

bool	writeByte (char byte)
	This writes a byte to the ByteStream. More...

bool	writeBytes (const char *buffer, unsigned int bufferSize, unsigned int &bytesWritten)
	This writes the bytes given to the ByteStream. More...

void	endPacket ()
	This ends the current packet and starts a new one.

bool	hasNextPacket ()
	This returns whether or not there is a next packet. More...

bool	nextPacket ()
	This advances the ByteStream to the next packet, if there is one. More...

std::string	debugString ()
	This returns a string that can be printed in order to see debugging information about the ByteStream, including the position of the read and write heads, as well as a hexadecimal printout of the stream (wrapped every 50 bytes). More...

Protected Member Functions
void	freeBytes ()
	This frees the memory associated with the internal character buffer. More...

unsigned int	remainingReadLength_nolock () const
	This returns the number of bytes remaining in the stream. More...

unsigned int	remainingWriteLength_nolock () const
	This returns the number of bytes remaining in the stream. More...

bool	waitForReading (unsigned int increment)
	This attempts to wait for the given number of bytes to become available for reading. More...

bool	grow (unsigned int increment)
	This attempts to increase the size of the buffer by the specified amount. More...

Protected Attributes
bool	_isErrored
	This is whether or not this ByteStream is in an errored state. More...

bool	_lastReadTimedOut
	If this is a live stream, then this will be set to true if the last "read*" function failed due to a timeout. More...

bool	_isLive
	This is whether or not this ByteStream is hooked up (in some way) to live data. More...

std::mutex	liveLock
	This is the mutex for handling streaming operations.

std::condition_variable	liveConditionVariable
	TODO: DOCUMENT THIS VARIABLE.

bool	ownBytes
	This is whether or not this ByteStream owns the memory pointed to by "bytes". More...

char *	bytes
	This is the buffer allocated for this ByteStream.

unsigned int	bytesSize
	This is the current size of "bytes".

unsigned int	readIndex
	This is the current position for reading.

unsigned int	writeIndex
	This is the current position for writing.

std::list< unsigned int >	boundaries
	This is the list of the boundaries (if applicable) for this stream. More...

std::chrono::milliseconds	_readTimeout
	This is the timeout for reads.

Detailed Description

A ByteStream is an object that is basically a big wrapper around a character buffer.

There is a "read head" and a "write head", and when the read head reaches the write head, there is no more left to read.

A ByteStream also has the concept of "live". A live ByteStream is assumed to be hooked up to some mechanism that is writing to it while another thread is reading from it. In a live stream, the read operation can block until more information is written (or a timeout occurs).

A ByteStream also has the notion of "packet". A packet is a discrete chunk of data that has a beginning and an end. In the event of a read error, the ByteStream can be advanced to the next packet.

Exceptions:

None; A ByteStream throws no exceptions.

Member Enumeration Documentation

enum Access

This defines the kind of access that a ByteStream will have.

In particular, this refers to whether or not the "write" calls work.

Enumerator
READ_ONLY	Only read operations may be performed.
READ_WRITE	Both read and write operations may be performed.

Member Function Documentation

int compareWith	(	const char *	buffer,
		unsigned int	bufferLength
	)		const

This compares the ByteStream to the given character buffer and returns the equivalent of "memcmp".

Parameters

buffer	The character buffer to compare it with.
bufferLength	The length of the character buffer.

Returns: -1 if the ByteStream is smaller, 0 if it is equal, or +1 if it is greater than the buffer.

void copyFrom	(	const std::string &	bytes,
		Access	access
	)

This copies the bytes from the given string into the ByteStream's character buffer.

Parameters

bytes	The string to copy.
access	The kind of access that the ByteStream should have.

void copyFrom	(	const std::vector< char > &	bytes,
		Access	access
	)

This copies the bytes from the given vector into the ByteStream's character buffer.

Parameters

bytes	The vector to copy.
access	The kind of access that the ByteStream should have.

void copyFrom	(	const ByteStream &	byteStream,
		Access	access
	)

This copies the bytes from the given ByteStream into the ByteStream's character buffer.

Note that this copies the remaining bytes in the ByteStream.

Parameters

bytes	The ByteStream to copy.
access	The kind of access that the ByteStream should have.

void copyTo ( std::vector< char > & buffer ) const

This copies the portion of the ByteStream that's currently available for reading to the specified target.

Parameters

buffer The vector to replace.

void copyTo ( std::string & buffer ) const

This copies the portion of the ByteStream that's currently available for reading to the specified target.

Parameters

buffer The string to replace.

std::string debugString ( )

This returns a string that can be printed in order to see debugging information about the ByteStream, including the position of the read and write heads, as well as a hexadecimal printout of the stream (wrapped every 50 bytes).

Returns: A string with debugging information.

void freeBytes ( )

protected

This frees the memory associated with the internal character buffer.

Note, however, that this has no effect if the ByteStream does not own its own buffer.

If its bytes are simply linked, then this function does nothing.

bool grow ( unsigned int increment )

protected

This attempts to increase the size of the buffer by the specified amount.

Note, however, that if this ByteStream doesn't OWN its buffer, then this call will fail.

Returns: true if "increment" bytes may now be written; false otherwise.

bool hasNextPacket ( )

This returns whether or not there is a next packet.

Returns: true if there is a next packet, false if there is not.

const bool isErrored ( ) const

inline

This returns whether or not the stream is in an errored state.

Returns: true if the stream is in an errored state; false otherwise.

const bool isLive ( ) const

inline

This returns whether or not the stream is connected to "live" data, such as a socket.

A live stream has the ability to wait (and timeout) on "read*" operations if there is not enough data.

Returns: true if the stream is live; false otherwise.

const bool lastReadTimedOut ( ) const

inline

If the last "read*" function failed, then this will return whether or not the cause was a timeout.

Returns: true if the last "read*" function failed due a timeout; false otherwise.

void linkFrom	(	char *	bytes,
		unsigned int	bytesSize,
		Access	access
	)

This links the bytes given to the ByteStream's character buffer.

This is essentially creating a simple ByteStream wrapper around the buffer that already exists. You must not free "bytes" until this ByteStream is destroyed (or is no longer used).

Parameters

bytes	The character array to use.
bytesSize	The length of the character array to use.
access	The kind of access that the ByteStream should have.

bool nextPacket ( )

This advances the ByteStream to the next packet, if there is one.

Returns: true if the ByteStream actually advanced to a new packet, false if it did not.

bool peekByte ( char & byte )

This reads a byte from the ByteStream.

However, this does not advance the read head of the ByteStream.

Parameters

byte	A reference to the byte to read.

Returns: true on success, false on failure.

bool readByte ( char & byte )

This reads a byte from the ByteStream.

Parameters

byte	A reference to the character to store the byte.

Returns: true on success, false on failure.

bool readBytes	(	char *	buffer,
		unsigned int	bufferSize,
		unsigned int &	bytesRead
	)

This reads an arbitrary amount of bytes into the specified character buffer.

Parameters

buffer	The character buffer in which to store the read bytes.
bufferSize	The number of bytes to read. "buffer" must be at least this size.
bytesRead	A reference to an integer to hold the number of bytes that were actually read.

Returns: TODO

std::chrono::milliseconds readTimeout ( ) const

inline

This returns the current read timeout for the stream.

This is only useful if the stream is live.

Returns: The timeout, in milliseconds.

void readTimeout ( const std::chrono::milliseconds & timeout )

inline

This sets the read timeout for the stream.

This is only useful if the stream is live.

Parameters

timeout The new timeout, in milliseconds.

unsigned int remainingReadLength ( ) const

This returns the number of bytes remaining in the stream.

Returns: The number of bytes remaining.

unsigned int remainingReadLength_nolock ( ) const

protected

This returns the number of bytes remaining in the stream.

Returns: The number of bytes remaining.

unsigned int remainingWriteLength ( ) const

This returns the number of bytes remaining in the stream.

Returns: The number of bytes remaining.

unsigned int remainingWriteLength_nolock ( ) const

protected

This returns the number of bytes remaining in the stream.

Returns: The number of bytes remaining.

void reset ( )

This resets the internal character buffer (if owned by the ByteStream).

This will not free any memory, but it will copy the current data in the ByteStream to the beginning of the buffer; this way, it will not continue to grow unchecked indefinitely.

void setLive ( bool isLive )

This sets the "live" state of the stream.

Parameters

isLive The new live state of the stream.

bool waitForReading ( unsigned int increment )

protected

This attempts to wait for the given number of bytes to become available for reading.

If they all could not become available, then this returns false.

Returns: true if "increment" bytes may now be read; false otherwise.

bool writeByte ( char byte )

This writes a byte to the ByteStream.

Parameters

byte	The byte to write.

Returns: true on success, false on failure.

bool writeBytes	(	const char *	buffer,
		unsigned int	bufferSize,
		unsigned int &	bytesWritten
	)

This writes the bytes given to the ByteStream.

Parameters

buffer	The bytes to write.
bufferSize	The number of bytes to write. "buffer" must be at least this size.
bytesWritten	A reference to an integer to store the number of bytes actually written.

Returns: true on success, false on failure.

Member Data Documentation

bool _isErrored

protected

This is whether or not this ByteStream is in an errored state.

A stream in this state is useless and should be discarded.

bool _isLive

protected

This is whether or not this ByteStream is hooked up (in some way) to live data.

A streaming ByteStream will wait on "read" calls if there is not enough data to complete them. A non-live one will not.

bool _lastReadTimedOut

protected

If this is a live stream, then this will be set to true if the last "read*" function failed due to a timeout.

std::list<unsigned int> boundaries

protected

This is the list of the boundaries (if applicable) for this stream.

For example, TCP reads do not preserve message boundaries, but UDP reads do. When applicable, these boundaries (1) can be denoted here, and (2) will be used as a higher-priority end-of-buffer.

bool ownBytes

protected

This is whether or not this ByteStream owns the memory pointed to by "bytes".

If so, then it must clean it up when done.

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

include/private/bytestream.hpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation