A utility class for writing payload data to a PacketHeader. More...

#include <3espacketwriter.h>

Inheritance diagram for tes::PacketWriter:

Public Member Functions
	PacketWriter (PacketHeader &packet, uint16_t maxPayloadSize, uint16_t routingId=0, uint16_t messageId=0)
	Creates a `PacketWriter` to write to the given `packet`. More...

	PacketWriter (uint8_t *buffer, uint16_t bufferSize, uint16_t routingId=0, uint16_t messageId=0)
	Creates a `PacketWriter` to write to the given byte buffer. More...

	PacketWriter (const PacketWriter &other)
	Copy constructor. More...

	~PacketWriter ()
	Destructor, ensuring the CRC is calculated.

PacketWriter &	operator= (const PacketWriter &other)
	Assignment operator. More...

void	reset (uint16_t routingId, uint16_t messageId)
	Resets the packet, clearing out all variable data including the payload, crc and routing id. More...

void	reset ()

void	setRoutingId (uint16_t routingId)

PacketHeader &	packet () const

const uint8_t *	data () const

uint8_t *	payload ()

void	invalidateCrc ()

uint16_t	bytesRemaining () const
	Returns the number of bytes remaining available in the payload. More...

uint16_t	maxPayloadSize () const
	Returns the size of the payload buffer. More...

bool	finalise ()
	Finalises the packet for sending, calculating the CRC. More...

CrcType	calculateCrc ()
	Calculates the CRC and writes it to the `PacketHeader` crc member. More...

size_t	writeElement (const uint8_t *bytes, size_t elementSize)
	Writes a single data element from the current position. More...

size_t	writeArray (const uint8_t *bytes, size_t elementSize, size_t elementCount)
	Writes an array of data items from the current position. More...

size_t	writeRaw (const uint8_t *bytes, size_t byteCount)
	Writes raw bytes from the packet at the current position up to `byteCount`. More...

template<typename T >
size_t	writeElement (const T &element)
	Writes a single data item from the packet. More...

template<typename T >
size_t	writeArray (const T *elements, size_t elementCount)

template<typename T >
PacketWriter &	operator>> (T &val)

Public Member Functions inherited from tes::PacketStream< PacketHeader >
	PacketStream (PacketHeader &packet)
	Create a stream to read from beginning at `packet`. More...

uint32_t	marker () const
	Fetch the marker bytes in local endian. More...

uint16_t	versionMajor () const
	Fetch the major version bytes in local endian. More...

uint16_t	versionMinor () const
	Fetch the minor version bytes in local endian. More...

uint16_t	payloadSize () const
	Fetch the payload size bytes in local endian. More...

uint16_t	packetSize () const
	Returns the size of the packet plus payload, giving the full data packet size including the CRC. More...

uint16_t	routingId () const
	Fetch the routing ID bytes in local endian. More...

uint16_t	messageId () const
	Fetch the message ID bytes in local endian. More...

CrcType	crc () const
	Fetch the CRC bytes in local endian. More...

CrcType *	crcPtr ()
	Fetch a pointer to the CRC bytes. More...

const CrcType *	crcPtr () const

uint16_t	status () const
	Report the `Status` bits. More...

bool	isEop () const
	At end of packet/stream? More...

bool	isOk () const
	Status OK? More...

bool	isFail () const
	Fail bit set? More...

bool	isReadOnly () const
	Read only stream? More...

bool	isCrcValid () const
	CRC validated? More...

PacketHeader &	packet () const
	Access the head of the packet buffer, for direct `PacketHeader` access. More...

uint16_t	tell () const
	Tell the current stream position. More...

bool	seek (int offset, SeekPos pos=Begin)
	Seek to the indicated position. More...

const uint8_t *	payload () const
	Direct payload pointer access. More...

Protected Member Functions
uint8_t *	payloadWritePtr ()

void	incrementPayloadSize (size_t inc)

Protected Attributes
uint16_t	_bufferSize

Protected Attributes inherited from tes::PacketStream< PacketHeader >
PacketHeader &	_packet
	Packet header and buffer start address.

uint16_t	_status
	`Status` bits.

uint16_t	_payloadPosition
	Payload cursor.

Additional Inherited Members
Public Types inherited from tes::PacketStream< PacketHeader >
enum	SeekPos
	Control values for seeking.

enum	Status
	Status bits.

typedef uint16_t	CrcType
	Defies the packet CRC type.

Detailed Description

A utility class for writing payload data to a PacketHeader.

This keeps the PacketHeader payloadSize member up to date and ensures the CRC is calculated, either via calculateCrc() explicitly on on destruction.

The payload buffer size must be specified in the constructor, and data writes are limited by this value. The packet is assumed to be structured such that the packet header is located at the start of the buffer, followed immediately by space for the payload.

Two construction options are available, one where the PacketHeader details are already initialised, except for the payloadSize and crc. The given packet is assumed to be the start of the data buffer. The second constructor accepts a raw byte pointer, which marks the start of the buffer, and the size of the buffer. The buffer size must be large enough for the @ PacketHeader. Remaining space is available for the payload.

Bug:: Use the payloadOffset in various calculations herein. It was added after this class was written, but is currently only supported as being zero, so it's not an issue yet.

Constructor & Destructor Documentation

◆ PacketWriter() [1/3]

tes::PacketWriter::PacketWriter	(	PacketHeader &	packet,
		uint16_t	maxPayloadSize,
		uint16_t	routingId = `0`,
		uint16_t	messageId = `0`
	)

Creates a PacketWriter to write to the given packet.

This marks the start of the packet buffer.

The packet members are initialised, but payloadSize and crc are left at zero to be calculated later. The routingId maybe given now or set with setRoutingId().

Parameters

packet	The packet to write to.
maxPayloadSize	Specifies the space available for the payload (bytes). This is in excess of the packet size, not the total buffer size.

◆ PacketWriter() [2/3]

tes::PacketWriter::PacketWriter	(	uint8_t *	buffer,
		uint16_t	bufferSize,
		uint16_t	routingId = `0`,
		uint16_t	messageId = `0`
	)

Creates a PacketWriter to write to the given byte buffer.

The buffer size must be at least sizeof(PacketHeader), larger if any payload is required. If not, then the isFail() will be true and all write operations will fail.

The routingId maybe given now or set with setRoutingId().

Parameters

buffer	The packet data buffer.
bufferSize	The total number of bytes available for the `PacketHeader` and its paylaod. Must be at least `sizeof(PacketHeader)`, or all writing will fail.
routingId	Optionlly sets the `routingId` member of the packet.

◆ PacketWriter() [3/3]

tes::PacketWriter::PacketWriter ( const PacketWriter & other )

Copy constructor.

Simple as neither writer owns the underlying memory. Both point to the same underlying memory, but only one should be used.

Parameters

other The packet to copy.

Member Function Documentation

◆ bytesRemaining()

uint16_t tes::PacketWriter::bytesRemaining ( ) const

Returns the number of bytes remaining available in the payload.

This is calculated as the maxPayloadSize() - payloadSize().

Returns: Number of bytes remaining available for write.

◆ calculateCrc()

CrcType tes::PacketWriter::calculateCrc ( )

Calculates the CRC and writes it to the PacketHeader crc member.

The current CRC value is returned when isCrcValid() is true. The CRC will not be calculate when isFail() is true and the result is undefined.

Returns: The Calculated CRC, or undifined when isFail().

◆ finalise()

bool tes::PacketWriter::finalise ( )

Finalises the packet for sending, calculating the CRC.

Returns: True if the packet is valid and ready for sending.

Referenced by tes::sendMessage().

◆ maxPayloadSize()

uint16_t tes::PacketWriter::maxPayloadSize ( ) const

Returns the size of the payload buffer.

This is the maximum number of bytes which can be written to the payload.

Returns: The payload buffer size (bytes).

◆ operator=()

PacketWriter& tes::PacketWriter::operator= ( const PacketWriter & other )

Assignment operator.

Simple as neither writer owns the underlying memory. Both point to the same underlying memory, but only one should be used.

Parameters

other The packet to copy.

◆ reset() [1/2]

void tes::PacketWriter::reset	(	uint16_t	routingId,
		uint16_t	messageId
	)

Resets the packet, clearing out all variable data including the payload, crc and routing id.

Allows preparation for writing new data to the same payload buffer.

Parameters

routingId Optional specification for the routingId after reset.

Referenced by tes::sendMessage().

◆ reset() [2/2]

void tes::PacketWriter::reset ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References reset().

Referenced by reset().

◆ writeArray()

size_t tes::PacketWriter::writeArray	(	const uint8_t *	bytes,
		size_t	elementSize,
		size_t	elementCount
	)

Writes an array of data items from the current position.

This makes the same assumptions as writeElement() and performs an endian swap per array element. Elements in the array are assumed to be contiguous in both source and destination locations.

The writer position is advanced by the number of bytes write. Does not set the Fail bit on failure.

Parameters

bytes	Location to write from.
elementSize	Size of a single array element to write.
elementCount	The number of elements to attempt to write.

Returns: On success returns the number of elements written, not bytes.

Referenced by tes::ServerInfoMessage::write(), tes::ObjectAttributes::write(), and writeElement().

◆ writeElement() [1/2]

size_t tes::PacketWriter::writeElement	(	const uint8_t *	bytes,
		size_t	elementSize
	)

Writes a single data element from the current position.

This assumes that a single data element of size elementSize is being write and may require an endian swap to the current platform endian.

The writer position is advanced by elementSize. Does not set the Fail bit on failure.

Parameters

bytes	Location to write from.
elementSize	Size of the data item being write at `bytes`.

Returns: elementSize on success, 0 otherwise.

Referenced by tes::MeshCreateMessage::write(), tes::ServerInfoMessage::write(), tes::MeshDestroyMessage::write(), tes::ControlMessage::write(), tes::MeshComponentMessage::write(), tes::Material::write(), tes::CategoryNameMessage::write(), tes::MeshFinaliseMessage::write(), tes::CollatedPacketMessage::write(), tes::ObjectAttributes::write(), tes::CreateMessage::write(), tes::DataMessage::write(), tes::UpdateMessage::write(), and tes::DestroyMessage::write().

◆ writeElement() [2/2]

template<typename T >

size_t tes::PacketWriter::writeElement ( const T & element )

inline

Writes a single data item from the packet.

This writes a number of bytes equal to sizeof(T) performing an endian swap if necessary.

Parameters

[out] element Set to the data write.

Returns: sizeof(T) on success, zero on failure.

References writeArray().

◆ writeRaw()

size_t tes::PacketWriter::writeRaw	(	const uint8_t *	bytes,
		size_t	byteCount
	)

Writes raw bytes from the packet at the current position up to byteCount.

No endian swap is performed on the data write.

The writer position is advanced by byteCount. Does not set the Fail bit on failure.

Parameters

bytes Location to write into. byteCount Number of bytes to write.

Returns: The number of bytes write. This may be less than byteCount if there are insufficient data available.

Referenced by tes::CategoryNameMessage::write().

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

3espacketwriter.h

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PacketWriter() [1/3]

◆ PacketWriter() [2/3]

◆ PacketWriter() [3/3]

Member Function Documentation

◆ bytesRemaining()

◆ calculateCrc()

◆ finalise()

◆ maxPayloadSize()

◆ operator=()

◆ reset() [1/2]

◆ reset() [2/2]

◆ writeArray()

◆ writeElement() [1/2]

◆ writeElement() [2/2]

◆ writeRaw()