cornelluniversity::vetserial::base_command Class Reference

A pure virtual abstraction which serves as the basis of the vet serial protocol command structure. This handles packet management, dissecting incoming packets or creating new ones as needed. How the packets are assembled is determined in the pure virtual function execute() which must be over-ridden by any class inheriting from base_command. More...

#include <vetprot.h>

Inheritance diagram for cornelluniversity::vetserial::base_command:

List of all members.

Public Member Functions
	base_command (const cmnd_id cid)
	constructor The object must be initialized with a COMMAND_ID
	base_command (const uint8_ *in_pkt, uint32_ nbytes)
virtual	~base_command (void)
	Destructor; frees any dynamic memory that was used in during the objects life cycle (two internal buffers).
const uint8_ *	packet (void) const
	Internal packet buffer accessor. The intrnal buffer is where new packets are managed.
const int	packet_size (void) const
	Accessor for the internall managed buffer byte count (i.e. packet size).
void	command_id (const cmnd_id cid)
const cmnd_id	command_id (void) const
const uint8_	flags (void) const
	Accessor to the packet flags byte (the full bit field).
void	set_flag (const uint8_ f)
	mutator for the packet flags byte; enables one or more flags by ORing in the supplied parameter into the current value.
void	clr_flag (const flag_t f)
	Toggles off a single bit in the flags bit field.
bool	flag_enabled (const flag_t f) const
	Determines if a single flag within the flags byte is enabled or not.
void	error_code (const err_code id)
	mutator for the packet error code byte; Sets the byte to a supplied ERROR_CODE defined value.
const err_code	error_code (void) const
	accessor to the packet error code byte.
void	data_id (const uint8_ id)
	mutator for the internally stored data-id field. This fields value is arbitrary and supplied to support debugging and more advanced packet tracking schemes. The value of the Id is limited to 8-bit values.
const unsigned char	data_id (void) const
	accessor to the internally stored data-id field.
void	payload_size (const uint16_ sz)
	mutator for the internally stored payload size field. The payload size is the size of the packet minus header and trailer.
const uint16_	payload_size (void) const
	accessor of the internally stored payload size field. The payload size is the size of the packet minus header and trailer.
bool	verify_crc16 (const uint8_ *full_packet, const uint32_ nbytes)
	validates the accuracy of a supplied packet against its included CRC(s) pass the FULL packet, the routine will determine what validations to perform. In the case of just a header being present, this routine will return after that check. If the packet also has a data payload, then this routine will return only after validating both CRCs. Both must be valid for the routine to return true.
const bool	failed_tail_crc (void) const
	When a bad CRC is detected, we will often need to discern between a failed header checksum and a failed tail checksum. if the header fails, there is nothing we can do as we cannot rely on the packets flags to give us guidance. However, if there is a tail and it fails, then the header flags need to be honored.
virtual void	serialize (void)=0
	pure virtual function that must be over-ridden in all objects inheriting from base_command. This function should be developed to implement the assembly of packets for the command in question. The end result should be to have a fully formed packet in buffer_ (for outgoing)
virtual void	deserialize (void)=0
	pure virtual function that must be over-ridden in all objects inheriting from base_command. This function should be developed to implement the dissembly of packets for the command in question. The end result is the parsing of an incoming packet into its appropriate members.
Static Public Attributes
static const unsigned int	PKT_HEADER_SZ
static const unsigned int	PKT_TAIL_SZ
static const unsigned int	PKT_MAX_SZ
Protected Member Functions
uint16_	crc16 (const uint8_ *indata, const uint32_ nbytes)
	generates the CCITT CRC 16 polynomial X^16 + X^12 + X^5 + 1
void	header (void)
	When called, this will reinitialize the internal buffers, essentially wiping out any previous data. The 10-byte packet header is then rebuilt based on the current values stored in the objects private members. The header is left in the buffer for you to use or append additional data. Exceptions: cornelluniversity::vetexcept  data out-of-bounds std::bad_alloc  standard memory allocation failure.
void	tail (const uint8_ *payload, const uint32_ payload_sz=0)
	Appends a protocol defined trailer to the end of the packet currently in the interal buffer. This routine does not question the contents of the buffer, it simply appends three additional bytes. Two of those bytes are the CRC checksum for the data payload, so you'll have to pass those (payload) bytes into this routine.
Protected Attributes
uint8_ *	buffer_
uint8_ *	packet_
uint32_	buffersz_
uint32_	pktsz_

---

Detailed Description

A pure virtual abstraction which serves as the basis of the vet serial protocol command structure. This handles packet management, dissecting incoming packets or creating new ones as needed. How the packets are assembled is determined in the pure virtual function execute() which must be over-ridden by any class inheriting from base_command.

---

Constructor & Destructor Documentation

cornelluniversity::vetserial::base_command::base_command

(

const cmnd_id

cid

)

constructor The object must be initialized with a COMMAND_ID

Parameters:

cid

- the COMMAND_ID defined command being initialized

See also:

COMMAND_ID

base_command(const uint8_ * in_pkt, uint32_ nbytes)

cornelluniversity::vetserial::base_command::base_command	(	const uint8_ *	in_pkt,
		uint32_	nbytes
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Constructor overloaded for receiving packets rather than creating one

Parameters:

	in_pkt	- pointer to a unisigned char array that comprises an in-coming protocol conforming packet
	nbytes	- the size of the packet in bytes

Exceptions:

	cornelluniversity::vetexcept	data out-of-bounds
	cornelluniversity::vetexcept	NULLPTR encountered where data is required
	std::bad_alloc	standard memory allocation failure

See also:

base_command(const cmnd_id cid)

virtual cornelluniversity::vetserial::base_command::~base_command

(

void

)

[virtual]

Destructor; frees any dynamic memory that was used in during the objects life cycle (two internal buffers).

---

Member Function Documentation

void cornelluniversity::vetserial::base_command::clr_flag

(

const flag_t

f

)

[inline]

Toggles off a single bit in the flags bit field.

Parameters:

f

- FLAG_TYPE defined value of the bit to be disabled

See also:

FLAG_TYPE

const cmnd_id cornelluniversity::vetserial::base_command::command_id

(

void

)

const [inline]

void cornelluniversity::vetserial::base_command::command_id

(

const cmnd_id

cid

)

[inline]

uint16_ cornelluniversity::vetserial::base_command::crc16	(	const uint8_ *	indata,
		const uint32_	nbytes
	)			[protected]

generates the CCITT CRC 16 polynomial X^16 + X^12 + X^5 + 1

Parameters:

	indata	- pointer to an unsigned char based c-style string
	nbytes	- int size of the indata array

Returns:

unsigned short - 16 bit integer making up the CRC of the supplied byte string

Exceptions:

cornelluniversity::vetexcept

NULLPTR encountered where data is required

const unsigned char cornelluniversity::vetserial::base_command::data_id

(

void

)

const [inline]

accessor to the internally stored data-id field.

Returns:

unsigned char - the 8 bit integer currently stored in the packet

See also:

void data_id(const uint8_ id)

void cornelluniversity::vetserial::base_command::data_id

(

const uint8_

id

)

[inline]

mutator for the internally stored data-id field. This fields value is arbitrary and supplied to support debugging and more advanced packet tracking schemes. The value of the Id is limited to 8-bit values.

Parameters:

id

- 8 bit integer to be stored in the packet

virtual void cornelluniversity::vetserial::base_command::deserialize

(

void

)

[pure virtual]

pure virtual function that must be over-ridden in all objects inheriting from base_command. This function should be developed to implement the dissembly of packets for the command in question. The end result is the parsing of an incoming packet into its appropriate members.

Implemented in cornelluniversity::vetserial::control_request, cornelluniversity::vetserial::status_request, cornelluniversity::vetserial::status_response, cornelluniversity::vetserial::mp3_play_request, cornelluniversity::vetserial::mp3_stop_request, cornelluniversity::vetserial::pubsub_message, and cornelluniversity::vetserial::cpr_compression_state.

const err_code cornelluniversity::vetserial::base_command::error_code

(

void

)

const [inline]

accessor to the packet error code byte.

Returns:

ERROR_CODE - a defined error id

See also:

ERROR_CODE

void cornelluniversity::vetserial::base_command::error_code

(

const err_code

id

)

[inline]

mutator for the packet error code byte; Sets the byte to a supplied ERROR_CODE defined value.

Parameters:

id

- ERROR_CODE defined error id

See also:

ERROR_CODE

const bool cornelluniversity::vetserial::base_command::failed_tail_crc

(

void

)

const [inline]

When a bad CRC is detected, we will often need to discern between a failed header checksum and a failed tail checksum. if the header fails, there is nothing we can do as we cannot rely on the packets flags to give us guidance. However, if there is a tail and it fails, then the header flags need to be honored.

bool cornelluniversity::vetserial::base_command::flag_enabled

(

const flag_t

f

)

const [inline]

Determines if a single flag within the flags byte is enabled or not.

Parameters:

f

- FLAG_TYPE defined value of the bit to interrogate

Returns:

bool - true if enabled, false otherwise

See also:

FLAG_TYPE

const uint8_ cornelluniversity::vetserial::base_command::flags

(

void

)

const [inline]

Accessor to the packet flags byte (the full bit field).

Returns:

const unsigned char - flags bit field

void cornelluniversity::vetserial::base_command::header

(

void

)

[protected]

When called, this will reinitialize the internal buffers, essentially wiping out any previous data. The 10-byte packet header is then rebuilt based on the current values stored in the objects private members. The header is left in the buffer for you to use or append additional data.

Exceptions:

	cornelluniversity::vetexcept	data out-of-bounds
	std::bad_alloc	standard memory allocation failure.

const uint8_* cornelluniversity::vetserial::base_command::packet

(

void

)

const [inline]

Internal packet buffer accessor. The intrnal buffer is where new packets are managed.

Returns:

unsigned char * - complete packet ready for delivery

const int cornelluniversity::vetserial::base_command::packet_size

(

void

)

const [inline]

Accessor for the internall managed buffer byte count (i.e. packet size).

Returns:

const int number of bytes in the currently stored out-going packet

const uint16_ cornelluniversity::vetserial::base_command::payload_size

(

void

)

const [inline]

accessor of the internally stored payload size field. The payload size is the size of the packet minus header and trailer.

Returns:

unsigned short - 16 bit integer indicating the byte size of the packets data payload

void cornelluniversity::vetserial::base_command::payload_size

(

const uint16_

sz

)

[inline]

mutator for the internally stored payload size field. The payload size is the size of the packet minus header and trailer.

Parameters:

sz

- 16 bit integer indicating the byte size of the packets data payload

virtual void cornelluniversity::vetserial::base_command::serialize

(

void

)

[pure virtual]

pure virtual function that must be over-ridden in all objects inheriting from base_command. This function should be developed to implement the assembly of packets for the command in question. The end result should be to have a fully formed packet in buffer_ (for outgoing)

Implemented in cornelluniversity::vetserial::control_request, cornelluniversity::vetserial::status_request, cornelluniversity::vetserial::status_response, cornelluniversity::vetserial::mp3_play_request, cornelluniversity::vetserial::mp3_stop_request, cornelluniversity::vetserial::pubsub_message, and cornelluniversity::vetserial::cpr_compression_state.

void cornelluniversity::vetserial::base_command::set_flag

(

const uint8_

f

)

[inline]

mutator for the packet flags byte; enables one or more flags by ORing in the supplied parameter into the current value.

Parameters:

f

- unsigned char flag(s) to be enabled

void cornelluniversity::vetserial::base_command::tail	(	const uint8_ *	payload,
		const uint32_	payload_sz = 0
	)			[protected]

Appends a protocol defined trailer to the end of the packet currently in the interal buffer. This routine does not question the contents of the buffer, it simply appends three additional bytes. Two of those bytes are the CRC checksum for the data payload, so you'll have to pass those (payload) bytes into this routine.

Parameters:

	payload	- pointer to an unsigned char based c-style string that comprises the data payload (and oly the payload, no part of the header should be included)
	payload_sz	- (optional) int size of the payload array. Because this value is stored internally for header purposes, you can ignore the second argument and the value in the appropriate private member will be used instead.

Exceptions:

	cornelluniversity::vetexcept	data out-of-bounds
	cornelluniversity::vetexcept	NULLPTR encountered where data is required

Warning:

there must be three (3) bytes of free space in the buffer

bool cornelluniversity::vetserial::base_command::verify_crc16	(	const uint8_ *	full_packet,
		const uint32_	nbytes
	)

validates the accuracy of a supplied packet against its included CRC(s) pass the FULL packet, the routine will determine what validations to perform. In the case of just a header being present, this routine will return after that check. If the packet also has a data payload, then this routine will return only after validating both CRCs. Both must be valid for the routine to return true.

Parameters:

	indata	- pointer to an unsigned char based c-style string
	nbytes	- int size of the indata array

Returns:

bool - true is CRC is valid, false otherwise

Exceptions:

	cornelluniversity::vetexcept	data out-of-bounds
	cornelluniversity::vetexcept	NULLPTR encountered where data is required
	std::bad_alloc	standard memory allocation failure

---

Member Data Documentation

uint8_* cornelluniversity::vetserial::base_command::buffer_ [protected]

internal memory for building new packets

uint32_ cornelluniversity::vetserial::base_command::buffersz_ [protected]

byte count of any built packet

uint8_* cornelluniversity::vetserial::base_command::packet_ [protected]

raw data storage for imported packets

const unsigned int cornelluniversity::vetserial::base_command::PKT_HEADER_SZ [static]

byte count of a packet's header structure

const unsigned int cornelluniversity::vetserial::base_command::PKT_MAX_SZ [static]

miximum allowable byte count of any complete packet

const unsigned int cornelluniversity::vetserial::base_command::PKT_TAIL_SZ [static]

byte count of a packet's tail (trailer) structure

uint32_ cornelluniversity::vetserial::base_command::pktsz_ [protected]

byte count of any imported packet

---

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

• /users/dtb26/GITROOT/vs-vetserial-poc/src/vetprot.h

---