Tes::IO::PacketBuffer Class Reference

The Tes.IO.PacketBuffer is used to collate incoming network data and extract a Tes.IO.PacketHeader and payload. More...

List of all members.

Public Member Functions
	PacketBuffer ()
	Default constructor.
	PacketBuffer (int initialBufferSize, bool useBufferPool=true)
	Create a packet with the given initial buffer size.
void	Dispose ()
	Returns the internal buffer pack to the T:ArrayPool when using a rented buffer.
void	Reset ()
	Full reset the packet.
void	Reset (ushort routingId, ushort messageId)
	Reset the packet while maintaining the current header with a new routingId
void	WriteHeader (PacketHeader header)
	Resets the buffer and writes a new header to the packet.
void	WriteBytes (byte[] bytes, bool toNetworkEndian, int offset=0, int length=0)
	Write data into the packet.
bool	FinalisePacket (bool addCrc=true)
	Finalise an output packet.
int	ExportTo (BinaryWriter writer)
	Exports the packet contents to the given BinaryWriter .
int	ExportTo (Stream stream)
	Exports the packet contents to the given Stream .
ushort	PeekUInt16 (int offset)
	Peek at two bytes in the message content.
uint	PeekUInt32 (int offset)
	Peek at four bytes in the message content.
ulong	PeekUInt64 (int offset)
	Peek at four bytes in the message content.
bool	PeekBytes (int offset, byte[] bytes, int byteCount)
	Peek at a number of bytes in the message content.
Stream	CreateReadStream (bool skipHeader)
	Instantiates a memory stream which reads the bytes in this packet buffer.
bool	Append (byte[] bytes, int available)
	Appends data to the internal buffer to complete the current message.
bool	Append (Stream stream, int available)
	An overload supporting reading bytes from a Stream instead of a byte array.
PacketBuffer	PopPacket (out bool crcOk)
	Pops the next available packet from the internal buffer.
int	Emplace (byte[] bytes, int available)
	Emplace bytes within the buffer, returning true if this completes the packet.
int	Emplace (byte[] bytes, int offset, int length)
	Emplace bytes within the buffer, returning true if this completes the packet.
int	Emplace (Stream stream, int available)
	Emplace bytes from a stream.
Properties
PacketBufferStatus	Status [get, set]
	Packet status.
bool	ValidHeader [get, set]
	Is the header valid?
PacketHeader	Header [get]
	The current packet header.
int	Count [get]
	Returns the number of byte available in the buffer.
byte[]	Data [get]
	Direct access to the internal buffer bytes.
int	Cursor [get]
	Marks the start of the next packet in the buffer.
int	DroppedByteCount [get, set]
	Tracks the number of dropped bytes.

---

Detailed Description

The Tes.IO.PacketBuffer is used to collate incoming network data and extract a Tes.IO.PacketHeader and payload.

A

PacketBuffer

can be used in two ways: input and output

An input packet is used to collate data coming from a network or file stream. Bytes are read from the stream and added to the

PacketBuffer

by calling Append(byte[], int). Individual messages are extracted using PopPacket(out bool), which creates a new PacketBuffer containing data for a single message. Data are read from this message by obtaining a

Stream

from CreateReadStream(bool). This is summarised below:

• Add data by calling Append(byte[], int) until it returns

  true
  

  .
• Extract messages by calling PopPacket(out bool)
• Read from extracted messages by creating a stream using CreateReadStream(bool)

Output packets are used to generate content for writing to a network or file stream. An output packet first requires a PacketHeader, which is added to the buffer via WriteHeader(PacketHeader). Message data are then written to the buffer by calling WriteBytes(byte[], bool, int, int). Note that data should only be added to the buffer in network byte order (Big Endian). This conversion must occur before calling WriteBytes(byte[], bool, int, int).

Once all data are written, the packet is finalised calling FinalisePacket(bool) and may be exported by calling one of the export methods: ExportTo(BinaryWriter). Once exported a

PacketBuffer

may be reused by calling Reset() and starting the process from the beginning. Alternatively, the existing header may be preserved by calling Reset(ushort, ushort) and updating only the PacketHeader.RoutingID.

The output process is summarised below:

• Create and write a new header to the packet using WriteHeader(PacketHeader)
• Write message data in network byte order using WriteBytes(byte[], bool, int, int)
• Finalise the packet size and CRC using FinalisePacket(bool)
• Export the packet using ExportTo(BinaryWriter)
• Optionally reset and reuse the packet with Reset(ushort, ushort)

---

Constructor & Destructor Documentation

Tes::IO::PacketBuffer::PacketBuffer	(	int	initialBufferSize,
		bool	useBufferPool = true
	)		[inline]

Create a packet with the given initial buffer size.

Parameters:

initialBufferSize	The initial buffer size (bytes)
useBufferPool	Allow the use of the T:ArrayPool?

---

Member Function Documentation

bool Tes::IO::PacketBuffer::Append	(	byte[]	bytes,
		int	available
	)		[inline]

Appends data to the internal buffer to complete the current message.

Returns a PacketBuffer with a completed message if bytes completes the current message.

Parameters:

bytes	The data stream to append.
available	The number of bytes from bytes to append. This allows the given buffer to be larger than the available data.

Returns:

True if there is a completed packet available.

As data bytes are appended, the buffer code searches for a valid header, consuming all bytes until a valid header is found - i.e., bytes before the valid header are lost.

Once a valid header is found,

Append()

waits for sufficient bytes to complete the packet as specified in the validated header. At this point

Append()

returns

true

. Available packets may be extracted by calling PopPacket(out bool) until that method returns null.

Calling

Append()

will change the PacketBuffer.Status as follows:

Status	Conditions
Empty	The append call did not add any data, or an invalid header has been consumed leaving the buffer empty.
Collating	Bytes have been appended, but no complete packet is available yet. The header may be valid: check ValidHeader
Available	A header has been validated and sufficient bytes are present to extract a packet. Call PopPacket(out bool).

"

bool Tes::IO::PacketBuffer::Append	(	Stream	stream,
		int	available
	)		[inline]

An overload supporting reading bytes from a

Stream

instead of a byte array.

Parameters:

stream	The stream to read from.
available	The number of bytes available to read from the stream.

Returns:

See Append(byte[], int).

Stream Tes::IO::PacketBuffer::CreateReadStream

(

bool

skipHeader

)

[inline]

Instantiates a memory stream which reads the bytes in this packet buffer.

Returns:

The read only memory stream.

Parameters:

skipHeader

True to skip the header bytes, moving on to the payload. Includes respecting the payload offset.

void Tes::IO::PacketBuffer::Dispose

(

)

[inline]

Returns the internal buffer pack to the T:ArrayPool when using a rented buffer.

Call Dispose when you are finished using the T:Tes.IO.PacketBuffer. The Dispose method leaves the T:Tes.IO.PacketBuffer in an unusable state. After calling Dispose, you must release all references to the T:Tes.IO.PacketBuffer so the garbage collector can reclaim the memory that the T:Tes.IO.PacketBuffer was occupying.

int Tes::IO::PacketBuffer::Emplace	(	byte[]	bytes,
		int	available
	)		[inline]

Emplace bytes within the buffer, returning true if this completes the packet.

This is equivalent to Append(byte[], int), except this object represents the completed packet.

Parameters:

bytes	The data stream to append.
available	The number of bytes from bytes to append. This allows the given buffer to be larger than the available data.

Returns:

The number of bytes added from bytes .

int Tes::IO::PacketBuffer::Emplace	(	byte[]	bytes,
		int	offset,
		int	length
	)		[inline]

Emplace bytes within the buffer, returning true if this completes the packet.

This is equivalent to Append(byte[], int), except this object represents the completed packet.

Parameters:

bytes	The data stream to append.
offset	Byte offset into bytes to start reading from.
length	The number of bytes from bytes to append. This allows the given buffer to be larger than the available data.

Returns:

The number of bytes added from bytes .

int Tes::IO::PacketBuffer::Emplace	(	Stream	stream,
		int	available
	)		[inline]

Emplace bytes from a stream.

This is equivalent to Emplace(byte[], int) except for the data source.

Parameters:

stream	The stream to read bytes from.
available	The number of bytes to read from stream .

Returns:

The number of bytes added from stream .

int Tes::IO::PacketBuffer::ExportTo

(

BinaryWriter

writer

)

[inline]

Exports the packet contents to the given

BinaryWriter

.

Parameters:

writer

The BinaryWriter to export available bytes to.

Returns:

The number of bytes written

Export does not validate the packet status, exporting available bytes as is.

Exceptions:

InvalidPacketStatusException

Thrown when the status is not PacketBufferStatus.Complete.

int Tes::IO::PacketBuffer::ExportTo

(

Stream

stream

)

[inline]

Exports the packet contents to the given

Stream

.

Parameters:

stream

The Stream to export available bytes to.

Returns:

The number of bytes written

Export does not validate the packet status, exporting available bytes as is.

Exceptions:

InvalidPacketStatusException

Thrown when the status is not PacketBufferStatus.Complete.

bool Tes::IO::PacketBuffer::FinalisePacket

(

bool

addCrc = true

)

[inline]

Finalise an output packet.

Parameters:

addCrc

True to calculate and add the CRC.

Finalises an output packet by updating the packet size, calculating the CRC and writing the CRC to the buffer. The buffer is ready for ExportTo(BinaryWriter)

bool Tes::IO::PacketBuffer::PeekBytes	(	int	offset,
		byte[]	bytes,
		int	byteCount
	)		[inline]

Peek at a number of bytes in the message content.

Parameters:

offset	Offset from the packet start to peek at.
bytes	The byte stream to write to.
byteCount	The number of bytes to read.

Returns:

True when offset the byteCount are both in range.

The read bytes are left in network Endian.

ushort Tes::IO::PacketBuffer::PeekUInt16

(

int

offset

)

[inline]

Peek at two bytes in the message content.

Parameters:

offset

Offset from the packet start to peek at.

Returns:

The peeked value or zero when offset is out of range.

Two bytes are read from the message at the given offset and converted from network to local Endian.

uint Tes::IO::PacketBuffer::PeekUInt32

(

int

offset

)

[inline]

Peek at four bytes in the message content.

Parameters:

offset

Offset from the packet start to peek at.

Returns:

The peeked value or zero when offset is out of range.

Four bytes are read from the message at the given offset and converted from network to local Endian.

ulong Tes::IO::PacketBuffer::PeekUInt64

(

int

offset

)

[inline]

Peek at four bytes in the message content.

Parameters:

offset

Offset from the packet start to peek at.

Returns:

The peeked value or zero when offset is out of range.

Four bytes are read from the message at the given offset and converted from network to local Endian.

PacketBuffer Tes::IO::PacketBuffer::PopPacket

(

out bool

crcOk

)

[inline]

Pops the next available packet from the internal buffer.

Parameters:

crcOk

Exposes the results of the CRC check. Always true when a valid packet is returned. Also true when no packet is available. Only false when a completed packet is available, but the CRC fails.

Returns:

The next available packet or null if not available or the CRC check fails.

A

PacketBuffer

accumulating packets using Append(byte[], int) may contain at least one completed packet. This method is used to extract each packet as a self contained

PacketBuffer

. When completed packets are available, this method returns each available completed packet as a single, self contained item.

The bytes making up the completed packet are removed from this packet buffer while excess bytes are preserved.

A null packet buffer may also be returned when there is enough data for a packet, but the CRC check fails. This case is detected when null is returned as crcOk is

false

(failed CRC) as opposed to null returned and crcOk

true

(no packet).

void Tes::IO::PacketBuffer::Reset	(	ushort	routingId,
		ushort	messageId
	)		[inline]

Reset the packet while maintaining the current header with a new routingId

Parameters:

routingId	The routing ID for the header.
messageId	The message ID for the router to handle.

void Tes::IO::PacketBuffer::WriteBytes	(	byte[]	bytes,
		bool	toNetworkEndian,
		int	offset = 0,
		int	length = 0
	)		[inline]

Write data into the packet.

Parameters:

bytes	Data to write. Bytes are converted to network Endian (Big Endian)
toNetworkEndian	When true , bytes are converted to network Endian (Big Endian), otherwise bytes are written as is.
offset	Offset from the start of bytes to start writing from.
length	The number of bytes to write. Zero for all bytes from offset to the end of bytes .

The buffer size is increased if required.

void Tes::IO::PacketBuffer::WriteHeader

(

PacketHeader

header

)

[inline]

Resets the buffer and writes a new header to the packet.

Parameters:

header

Intended for use in packet export only.

The Header is set to match header , ValidHeader becomes

true

and the status changes to PacketBufferStatus.Collating. The given header is immediately written to the packet buffer.

Message data may then be written to the buffer and the packet completed by calling FinalisePacket(bool), which fixes the packet size.

---

Property Documentation

byte [] Tes::IO::PacketBuffer::Data [get]

Direct access to the internal buffer bytes.

Intended to aid in serialisation of completed packets. For example:

          writer.Send(packet.Data, packet.Cursor, packet.Count)

Use with care.

int Tes::IO::PacketBuffer::DroppedByteCount [get, set]

Tracks the number of dropped bytes.

This value is adjusted when the header marker cannot be found an identifies how many bytes are removed from the packet before finding valid header marker. The value continually accumulates but may be cleared by users of the packet buffer.

PacketHeader Tes::IO::PacketBuffer::Header [get]

The current packet header.

Only relevant when ValidHeader is true.

bool Tes::IO::PacketBuffer::ValidHeader [get, set]

Is the header valid?

---

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

• PacketBuffer.cs