Utils::Encodings::BinaryReader Class Reference

#include <BinaryReader.h> [code]

Inherited by Protocols::Gnutella::Packets::BinaryReader.

Inheritance diagram for Utils::Encodings::BinaryReader:

[legend]Collaboration diagram for Utils::Encodings::BinaryReader:

[legend]List of all members.

Detailed Description

Reads binary data from a raw buffer (QByteArray).

This class encapsulates some functions, which would make it easier to read binary data out of raw data buffers. All functions do byte order conversions when necessary.

It is safe to read pass the end of the underlying raw data. Use hasReadPastEnd() to check whether such event occurred. Use hasReadAll() to check whether all underlying data has been read.

If you want to change the binary format used by some function or add support for further user types, derive a new class from this one.

Todo:: Drop the Data and make its fields members of BinaryReader.
Extract an interface class? Rename to BinaryReader base and make the dtor protected to avoid deleting using base-class pointer? Same for BinaryWriter.

Definition at line 47 of file BinaryReader.h.

Public Types

enum ByteOrder {
  BigEndian = 0,
  LittleEndian = 1
}

enum ReadOrigin {
  ReadFromStart = 0,
  ReadFromEnd = 1
}

Public Member Functions

BinaryReader (const QByteArray &rawData, ByteOrder)

Constructs a BinaryReader object for rawData.

uchar lookAhead (const int count)

Looks ahead in the buffer without changing the read pointers.

bool canRead (const int count)

Returns whether count bytes are available for reading.

uchar readByte ()

Reads a single byte from the underlying raw data buffer.

quint16 readUInt16 ()

Reads a two byte unsigned integer from the underlying raw data buffer.

quint32 readUInt32 ()

Reads a four byte unsigned integer from the underlying raw data buffer.

quint64 readUInt64 ()

Reads eight byte unsigned integer from the underlying raw data buffer.

qint16 readInt16 ()

qint32 readInt32 ()

qint64 readInt64 ()

QByteArray readAll ()

Read all bytes still available in the underlying buffer.

QByteArray readBytes (size_t count)

Reads count bytes from the underlying raw data buffer.

QByteArray readString (char terminator= '\0')

Reads a terminator terminated string from the underlying raw data buffer.

QByteArray getSharedBytes (size_t count)

Returns a QByteArray that shares some part of the underlying raw data.

ByteOrder byteOrder () const

Returns the currently set ByteOrder.

ReadOrigin readOrigin () const

Returns the currently set ReadOrigin.

void setByteOrder (ByteOrder)

Sets the byte order of the used in the underlying raw data buffer.

void setReadOrigin (ReadOrigin)

Sets the read origin (from start to end or end to start or raw data buffer).

bool hasReadPastEnd () const

Tells whether a read would have read past the end of the data buffer.

bool hasReadAll () const

Tells whether all data from the underlying data buffer has been read.

Private Member Functions

BinaryReader (const BinaryReader &)

BinaryReader & operator= (const BinaryReader &)

void doRead (char *destination, size_t count)

Reads size bytes from the underlying raw buffer into destination.

void bumpPtrs (size_t count)

Moves internal read pointers depending on current readOrigin().

void copyBytes (const char *beg, const char *end, char *dest)

Copies (possibly swapped) bytes from end - beg bytes in dest.

const char * getRangePtrs (size_t count)

Returns pointer to the position from which to read count bytes.

Private Attributes

Data d

Classes

class Data

Member Enumeration Documentation

enum Utils::Encodings::BinaryReader::ByteOrder

Enumerator:

BigEndian

LittleEndian

Definition at line 52 of file BinaryReader.h.

enum Utils::Encodings::BinaryReader::ReadOrigin

Enumerator:

ReadFromStart

ReadFromEnd

Definition at line 58 of file BinaryReader.h.

Constructor & Destructor Documentation

Utils::Encodings::BinaryReader::BinaryReader ( const BinaryReader & ) [private]

BinaryReader::BinaryReader ( const QByteArray & rawData,

ByteOrder byteOrder

)

Constructs a BinaryReader object for rawData.
Initializes the underlying raw data buffer using rawData and sets default byte order using byteOrder.
Definition at line 34 of file BinaryReader.cpp.

Member Function Documentation

void BinaryReader::bumpPtrs ( size_t count ) [private]

Moves internal read pointers depending on current readOrigin().
Moves the start read position count bytes forward, or moves the end read position count backward depending on the current readOrigin().
Definition at line 100 of file BinaryReader.cpp.

BinaryReader::ByteOrder Utils::Encodings::BinaryReader::byteOrder ( ) const [inline]

Returns the currently set ByteOrder.

See also:
setByteOrder()

Definition at line 125 of file BinaryReader.h.

bool BinaryReader::canRead ( const int count )

Returns whether count bytes are available for reading.

Definition at line 136 of file BinaryReader.cpp.

void BinaryReader::copyBytes ( const char * beg,

const char * end,

char * dest

) [private]

Copies (possibly swapped) bytes from end - beg bytes in dest.
The function will copy the bytes and if required by the selected byteOrder() it will swap them while copying.
Definition at line 87 of file BinaryReader.cpp.

void BinaryReader::doRead ( char * destination,

size_t count

) [private]

Reads size bytes from the underlying raw buffer into destination.
This function performs a safe read from the underlying buffer. It will not read beyond the end of the buffer and if it would have done so, then hasReadPastEnd() would return true. Byte ordering conversions are also performed if required.

See also:
setByteOrder(), setReadOrigin()

Definition at line 54 of file BinaryReader.cpp.

const char * BinaryReader::getRangePtrs ( size_t count ) [private]

Returns pointer to the position from which to read count bytes.
If the current readOrigin() is ReadFromEnd than the returned pointer can be used to read the last count bytes. Otherwise, a pointer to the first count bytes is returned.

Precondition:
The caller must make sure there are at least count bytes available, e.g. by calling canRead().

Definition at line 73 of file BinaryReader.cpp.

QByteArray BinaryReader::getSharedBytes ( size_t count )

Returns a QByteArray that shares some part of the underlying raw data.

Note:
Be very careful when using this function. It is provided for optimization purposes. If you are not sure whether you should use it, use readBytes() instead!
The start or end read position is moved by count bytes according to the current ReadOrigin and a QByteArray wrapping the count bytes is returned,
This function may be useful when reading nested data structures. For example you read a packet and encounter an extension which you know should be of size count bytes. If corrupt extension data could result in reading more than these count bytes, then a BinaryReader will both ease reading and verification of data. It may however be inefficient to copy data using readBytes() and getSharedBytes() is the solution.
This function uses QByteArray::fromRawData() to create a QByteArray object that wraps around the underlying data of the BinaryReader without copying bytes. The called MUST ensure that this BinaryReader exists as long as any unmodified copy of the QByteArray returned by getSharedBytes() exists.
Use this function with caution!

See also:
readBytes()

Definition at line 260 of file BinaryReader.cpp.

bool BinaryReader::hasReadAll ( ) const

Tells whether all data from the underlying data buffer has been read.
This function returns true if the user of the object of class BinaryReader read all the data available in the underlying data buffer. If user tried to read past the end, then both hasReadAll() and hasReadPastEnd() will return true!

See also:
hasReadPastEnd()

Definition at line 363 of file BinaryReader.cpp.

bool BinaryReader::hasReadPastEnd ( ) const

Tells whether a read would have read past the end of the data buffer.
If the user of the object tried to read more bytes than were actually available in the underlying raw data buffer, no matter from which readOridin(), this function returns true and false otherwise.

See also:
hasReadAll()

Definition at line 349 of file BinaryReader.cpp.

uchar BinaryReader::lookAhead ( const int count )

Looks ahead in the buffer without changing the read pointers.
This function returns a single byte which is count bytes away from the current read postition. If the requested byte is beyond the end of the raw data buffer a zero byte is returned. Call canRead() if you want to make sure that the returned byte is within the data.

Note:
count Must be greater or equal to 1.

See also:
canRead()

Definition at line 118 of file BinaryReader.cpp.

BinaryReader& Utils::Encodings::BinaryReader::operator= ( const BinaryReader & ) [private]

QByteArray BinaryReader::readAll ( )

Read all bytes still available in the underlying buffer.

Definition at line 206 of file BinaryReader.cpp.

uchar BinaryReader::readByte ( )

Reads a single byte from the underlying raw data buffer.
This function performs a safe read from the underlying buffer. It will not read beyond the end of the buffer and if it would have done so, then hasReadPastEnd() would return true. Byte ordering conversions are also performed if required.

See also:
setByteOrder(), setReadOrigin()

Definition at line 150 of file BinaryReader.cpp.

QByteArray BinaryReader::readBytes ( size_t count )

Reads count bytes from the underlying raw data buffer.
This function performs a safe read from the underlying buffer. It will not read beyond the end of the buffer and if it would have done so, then hasReadPastEnd() would return true.

Note:
NO Byte ordering conversions are performed.

See also:
setByteOrder(), setReadOrigin(), getSharedBytes()

Definition at line 224 of file BinaryReader.cpp.

qint16 Utils::Encodings::BinaryReader::readInt16 ( ) [inline]

See also:
readUInt16()

Definition at line 136 of file BinaryReader.h.

qint32 Utils::Encodings::BinaryReader::readInt32 ( ) [inline]

See also:
readUInt32()

Definition at line 140 of file BinaryReader.h.

qint64 Utils::Encodings::BinaryReader::readInt64 ( ) [inline]

See also:
readUInt64()

Definition at line 144 of file BinaryReader.h.

BinaryReader::ReadOrigin Utils::Encodings::BinaryReader::readOrigin ( ) const [inline]

Returns the currently set ReadOrigin.

See also:
setReadOrigin()

Definition at line 132 of file BinaryReader.h.

QByteArray BinaryReader::readString ( char terminator = '\0' )

Reads a terminator terminated string from the underlying raw data buffer.
Reads bytes from the underlying data buffer until terminator is reached. The terminator is not appended to the returned QByteArray, but the internal start read position is set beyond that terminator byte. If the end of the data buffer is reached before the terminator byte is encountered, then a QByteArray containing the data read so far is returned and hasReadPastEnd() will return true.
If readOrigin() is ReadFromEnd, then a terminator started string will be extracted from the end of the underlying data buffer. The terminator will not be appended to the returned QByteArray, but the end read position is set at the zero. The first byte in the returned QByteArray is the byte right after the starting terminator byte.
Definition at line 290 of file BinaryReader.cpp.

quint16 BinaryReader::readUInt16 ( )

Reads a two byte unsigned integer from the underlying raw data buffer.
This function performs a safe read from the underlying buffer. It will not read beyond the end of the buffer and if it would have done so, then hasReadPastEnd() would return true. Byte ordering conversions are also performed if required.

See also:
setByteOrder(), setReadOrigin()

Definition at line 166 of file BinaryReader.cpp.

quint32 BinaryReader::readUInt32 ( )

Reads a four byte unsigned integer from the underlying raw data buffer.
This function performs a safe read from the underlying buffer. It will not read beyond the end of the buffer and if it would have done so, then hasReadPastEnd() would return true. Byte ordering conversions are also performed if required.

See also:
setByteOrder(), setReadOrigin()

Definition at line 182 of file BinaryReader.cpp.

quint64 BinaryReader::readUInt64 ( )

Reads eight byte unsigned integer from the underlying raw data buffer.
This function performs a safe read from the underlying buffer. It will not read beyond the end of the buffer and if it would have done so, then hasReadPastEnd() would return true. Byte ordering conversions are also performed if required.

See also:
setByteOrder(), setReadOrigin()

Definition at line 198 of file BinaryReader.cpp.

void BinaryReader::setByteOrder ( ByteOrder byteOrder )

Sets the byte order of the used in the underlying raw data buffer.
The byteOrder determines whether any conversions should be made by the functions readUInt16(), readUInt32(), readUInt64(), etc.
Definition at line 314 of file BinaryReader.cpp.

void BinaryReader::setReadOrigin ( ReadOrigin readOrigin )

Sets the read origin (from start to end or end to start or raw data buffer).
If readOrigin is set to ReadFromStart, then data is read as normally - from the beginning of the raw data buffer. After a read the start position of the reader is incremented accordingly.
If readOrigin is set to ReadFromEnd, then data is read off the end of the of the underlying raw data buffer. After a read the end position of the reader is decremented accordingly.
Definition at line 335 of file BinaryReader.cpp.

Member Data Documentation

Data Utils::Encodings::BinaryReader::d [private]

Definition at line 118 of file BinaryReader.h.

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

Utils/Encodings/BinaryReader.h
Utils/Encodings/BinaryReader.cpp


Public Types
enum	ByteOrder { BigEndian = 0, LittleEndian = 1 }
enum	ReadOrigin { ReadFromStart = 0, ReadFromEnd = 1 }
Public Member Functions
	BinaryReader (const QByteArray &rawData, ByteOrder)
	Constructs a BinaryReader object for rawData.
uchar	lookAhead (const int count)
	Looks ahead in the buffer without changing the read pointers.
bool	canRead (const int count)
	Returns whether count bytes are available for reading.
uchar	readByte ()
	Reads a single byte from the underlying raw data buffer.
quint16	readUInt16 ()
	Reads a two byte unsigned integer from the underlying raw data buffer.
quint32	readUInt32 ()
	Reads a four byte unsigned integer from the underlying raw data buffer.
quint64	readUInt64 ()
	Reads eight byte unsigned integer from the underlying raw data buffer.
qint16	readInt16 ()
qint32	readInt32 ()
qint64	readInt64 ()
QByteArray	readAll ()
	Read all bytes still available in the underlying buffer.
QByteArray	readBytes (size_t count)
	Reads count bytes from the underlying raw data buffer.
QByteArray	readString (char terminator= '\0')
	Reads a terminator terminated string from the underlying raw data buffer.
QByteArray	getSharedBytes (size_t count)
	Returns a QByteArray that shares some part of the underlying raw data.
ByteOrder	byteOrder () const
	Returns the currently set ByteOrder.
ReadOrigin	readOrigin () const
	Returns the currently set ReadOrigin.
void	setByteOrder (ByteOrder)
	Sets the byte order of the used in the underlying raw data buffer.
void	setReadOrigin (ReadOrigin)
	Sets the read origin (from start to end or end to start or raw data buffer).
bool	hasReadPastEnd () const
	Tells whether a read would have read past the end of the data buffer.
bool	hasReadAll () const
	Tells whether all data from the underlying data buffer has been read.
Private Member Functions
	BinaryReader (const BinaryReader &)
BinaryReader &	operator= (const BinaryReader &)
void	doRead (char *destination, size_t count)
	Reads size bytes from the underlying raw buffer into destination.
void	bumpPtrs (size_t count)
	Moves internal read pointers depending on current readOrigin().
void	copyBytes (const char beg, const char end, char *dest)
	Copies (possibly swapped) bytes from end - beg bytes in dest.
const char *	getRangePtrs (size_t count)
	Returns pointer to the position from which to read count bytes.
Private Attributes
Data	d
Classes
class	Data