---

GNE::Buffer Class Reference

The Buffer class provides functionality to pull data types out of a raw binary data buffer. More...

#include <Buffer.h>

List of all members.

Public Member Functions
	Buffer ()
	Creates a new Buffer of RAW_PACKET_LEN capacity.
	Buffer (int size)
	Creates a new Buffer of size capacity.
	Buffer (const Buffer &o)
	Creates a Buffer that is a copy of the passed Buffer.
	~Buffer ()
	Destructor.
Buffer &	operator= (const Buffer &rhs)
	Copies the contents of the right side Buffer to the left side.
gbyte *	getData ()
	Returns a pointer to the start of the backing byte buffer for this object.
const gbyte *	getData () const
	const form of the normal getData method.
int	getPosition () const
	Returns the current position for the Buffer -- this is the next byte that will be read from or written to.
void	setPosition (int newPosition)
	Sets the new position for the Buffer.
void	rewind ()
	A shortcut for setPosition( 0 ).
int	getLimit () const
	Returns the limit for this buffer.
void	setLimit (int newLimit)
	Sets the limit for the Buffer.
int	getCapacity () const
	Returns the size in bytes of the backing byte buffer.
int	getRemaining () const
	Returns limit - position.
void	clear ()
	Readies the buffer for writing.
void	flip ()
	After the data has been written into the Buffer, readies it for reading.
void	writeBuffer (Buffer &src)
	Writes all remaining bytes in Buffer src to this Buffer.
void	writeBuffer (Buffer &src, int length)
	Writes length bytes from the Buffer src into this Buffer.
void	writeRaw (const gbyte *block, int length)
	Writes raw data starting at the current position.
void	readRaw (gbyte *block, int length)
	Like writeRaw, but just the other way around.
Buffer &	operator<< (gint8 x)
	Stream operators for writing to this Buffer.
Buffer &	operator<< (guint8 x)
	This operator also works for gbool and gbyte.
Buffer &	operator<< (gint16 x)
Buffer &	operator<< (guint16 x)
Buffer &	operator<< (gint32 x)
Buffer &	operator<< (guint32 x)
Buffer &	operator<< (gsingle x)
Buffer &	operator<< (gdouble x)
Buffer &	operator<< (const std::string &x)
Buffer &	operator<< (const Time &x)
Buffer &	operator<< (const Packet &packet)
	Writes a packet to the Buffer.
Buffer &	operator>> (gint8 &x)
	Stream operators for reading from this Buffer.
Buffer &	operator>> (guint8 &x)
	This operator also works for gbool and gbyte.
Buffer &	operator>> (gint16 &x)
Buffer &	operator>> (guint16 &x)
Buffer &	operator>> (gint32 &x)
Buffer &	operator>> (guint32 &x)
Buffer &	operator>> (gsingle &x)
Buffer &	operator>> (gdouble &x)
Buffer &	operator>> (std::string &x)
Buffer &	operator>> (Time &x)
Buffer &	operator>> (Packet &packet)
	This function calls the packet's readPacket function.
Static Public Member Functions
int	getStringSize (int x)
	Returns the maximum possible serialized size of a string of the given length in ASCII characters.
int	getSizeOf (const std::string &x)
	Returns the serialized size in bytes of the given variable, to be used in your overridden Packet::getSize method.
int	getSizeOf (guint8 x)
int	getSizeOf (gint16 x)
int	getSizeOf (guint16 x)
int	getSizeOf (gint32 x)
int	getSizeOf (guint32 x)
int	getSizeOf (gsingle x)
int	getSizeOf (gdouble x)
int	getSizeOf (const Time &x)
Static Public Attributes
const int	RAW_PACKET_LEN = 512
	The max length of a GNE network packet.

---

Detailed Description

The Buffer class provides functionality to pull data types out of a raw binary data buffer.

This class is the replacement for the Buffer class that used to exist. There are a few reasons for this rename. The first being that I wanted to fix up the interface -- it had changed so much I didn't want people getting confused so it's a new class now. The second reason is because people were getting confused thinking Buffer was a Packet type since all Packets typically are named WhateverPacket. The third reason is because I chose to somewhat base my interface off a class by the same name in Java, java.nio.Buffer.

Advantages over Buffer include easier and much much safer memory allocation and management. Previously in Buffer there was no knowledge about the buffer size and it was very easy to overflow or underflow the buffer.

This Buffer class should be very safe in that it won't allow you under or overflow.

The Buffer has 3 key concepts, the position, the limit, and the capacity.

The position is the byte offset where the next byte will be read to or written from. The limit is first byte that is invalid to access. The capacity is the size of the underlying byte array allocated to this Buffer.

It is always true that 0 <= position <= limit <= capacity.

Data is always written to the Buffer in GNE's network data format. And when reading it is assumed to be in GNE's network data format. Obviously, when using the rawRead and rawWrite methods no endian or format conversions are applied to the data read or written in those methods.

Most of the methods in Buffer throw BufferError when an error occurs, usually because of buffer overflow or underflow. Unless otherwise stated, if an exception is thrown during a Buffer operation, the Buffer is unchanged. Exceptions include the read packet and write packet operations.

---

Constructor & Destructor Documentation

GNE::Buffer::Buffer (   )

Creates a new Buffer of RAW_PACKET_LEN capacity. Postcondition: position == 0 limit == RAW_PACKET_LEN capacity == RAW_PACKET_LEN

GNE::Buffer::Buffer (  int  size  )

Creates a new Buffer of size capacity. Postcondition: position == 0 limit == size capacity == size

GNE::Buffer::Buffer (  const Buffer &  o  )

Creates a Buffer that is a copy of the passed Buffer. Works similarly to operator = for Buffer, in that 2 identical but independent Buffers are created as a result of this operation, but the capacities will be the same after the operation.

---

Member Function Documentation

void GNE::Buffer::clear (   )

Readies the buffer for writing. The bytes in the buffer are not actually cleared by this method. Postcondition: position == 0 limit == capacity capacity is unchanged

void GNE::Buffer::flip (   )

After the data has been written into the Buffer, readies it for reading. The current position for this Buffer becomes the new limit, and position is set back to 0. Postcondition: position == 0 limit == current position capacity is unchanged

gbyte * GNE::Buffer::getData (   )

Returns a pointer to the start of the backing byte buffer for this object. Unfortunately this method is a necessary evil since at some point the Buffer's data needs to be passed into some low-level system I/O function. It is suggested that this method be used only when necessary, to benefit from the overflow/underflow detection that the Buffer class provides.

int GNE::Buffer::getLimit (   )  const

Returns the limit for this buffer. The limit is the first byte of data that may not be accessed in any way.

int GNE::Buffer::getPosition (   )  const

Returns the current position for the Buffer -- this is the next byte that will be read from or written to. Its value is always between 0 and limit, inclusive.

Buffer & GNE::Buffer::operator<< (  const Packet &  packet  )

Writes a packet to the Buffer. This function will simply call the packet's writePacket function. If the writePacket method throws an exception, the buffer may have been modified if the packet successfully completed some of its write operations. An Error with code BufferOverflow will be thrown if there is not enough room in the buffer for packet.getSize() more bytes. See also: Packet::writePacket

Buffer & GNE::Buffer::operator<< (  gint8  x  )

Stream operators for writing to this Buffer. All data is converted when appropriate into little endian format, and whatever other conversions are required to place the data into GNE network format. Any of the write operators will increase the position and will throw a BufferError with code BufferOverflow if there is not room in the buffer.

Buffer & GNE::Buffer::operator= (  const Buffer &  rhs  )

Copies the contents of the right side Buffer to the left side. Produces two Buffers with the same data, position, and limit. Changes made to one will not affect the other. To make this operation efficent, the backing array for this Buffer is only recreated if the capacity of the left Buffer is smaller than the capacity of the right. Thus the resulting Buffer's capacity is equal to or greater than the capacities of the two Buffers before the operation.

Buffer & GNE::Buffer::operator>> (  Packet &  packet  )

This function calls the packet's readPacket function. You will already need to know what kind of packet is next. If you don't, use PacketPaser::parseNextPacket. If an exception occurs during the readPacket method, then the Buffer may have been modified if any calls to the Buffer succeeded. See also: PacketParser::parseNextPacket Packet::readPacket

Buffer & GNE::Buffer::operator>> (  gint8 &  x  )

Stream operators for reading from this Buffer. Any of the read operators will increase the position and will throw a BufferError with code BufferUnderflow if there is no more data to read.

void GNE::Buffer::readRaw (  gbyte *  block, int  length )

Like writeRaw, but just the other way around. The position is moved up by length. See also: writeRaw

void GNE::Buffer::setLimit (  int  newLimit  )

Sets the limit for the Buffer. Exceptions: BufferError  with InvalidBufferLimit code if newLimit is less than position or greater than capacity.

void GNE::Buffer::setPosition (  int  newPosition  )

Sets the new position for the Buffer. Exceptions: BufferError  with InvalidBufferPosition code if newPosition > limit or if newPosition < 0.

void GNE::Buffer::writeBuffer (  Buffer &  src, int  length )

Writes length bytes from the Buffer src into this Buffer. This is done by reading length bytes from src, then writing length bytes into this object. The position of each Buffer is increased by length. If an Error is thrown because of underflow on src or overflow on this object, no changes are made to either Buffer. Exceptions: BufferError  if this Buffer cannot hold length more data, or if the buffer src does not have length more data to read.

void GNE::Buffer::writeBuffer (  Buffer &  src  )

Writes all remaining bytes in Buffer src to this Buffer. This is the same as calling writeBuffer( src, src.getRemaining() ). Only an overflow Error can be thrown from this method. Exceptions: BufferError  if this Buffer cannot hold all of the data remaining in src.

void GNE::Buffer::writeRaw (  const gbyte *  block, int  length )

Writes raw data starting at the current position. This acts similar to the memcpy function. The position is moved up by length. See also: readRaw

---

Member Data Documentation

const int GNE::Buffer::RAW_PACKET_LEN = 512 [static]

The max length of a GNE network packet. This constant is used mostly by GNE's internal code to create packet combonation buffers.

---

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

• Buffer.h
• Buffer.cpp

---