Packet Inspection

Functions for accessing information about an existing MIP packet. More...

Functions
void	mip::C::mip_packet_from_buffer (mip_packet_view *packet, const uint8_t *buffer, size_t length)
	Initializes a MIP packet from an existing buffer. More...
uint8_t	mip::C::mip_packet_descriptor_set (const mip_packet_view *packet)
	Returns the MIP descriptor set for this packet. More...
uint_least16_t	mip::C::mip_packet_total_length (const mip_packet_view *packet)
	Returns the total length of the packet, in bytes. More...
uint8_t	mip::C::mip_packet_payload_length (const mip_packet_view *packet)
	Returns the length of the payload (MIP fields). More...
const uint8_t *	mip::C::mip_packet_buffer (const mip_packet_view *packet)
	Returns a read-only pointer to the data buffer. More...
uint8_t *	mip::C::mip_packet_buffer_w (mip_packet_view *packet)
	Returns a writable pointer to the data buffer. More...
const uint8_t *	mip::C::mip_packet_data (const mip_packet_view *packet)
	Returns a pointer to the data buffer containing the packet. More...
const uint8_t *	mip::C::mip_packet_payload (const mip_packet_view *packet)
	Returns a pointer to the packet's payload (the first field). More...
uint8_t *	mip::C::mip_packet_payload_w (mip_packet_view *packet)
	Returns a writable pointer to the packet's payload (the first field). More...
uint16_t	mip::C::mip_packet_checksum_value (const mip_packet_view *packet)
	Returns the value of the checksum as written in the packet. More...
uint16_t	mip::C::mip_packet_compute_checksum (const mip_packet_view *packet)
	Computes the checksum of the MIP packet. More...
bool	mip::C::mip_packet_is_sane (const mip_packet_view *packet)
	Returns true if the packet buffer is not NULL and is at least the minimum size (MIP_PACKET_LENGTH_MIN). More...
bool	mip::C::mip_packet_is_valid (const mip_packet_view *packet)
	Returns true if the packet is valid. More...
bool	mip::C::mip_packet_is_empty (const mip_packet_view *packet)
	Returns true if the mip packet contains no payload. More...
uint_least16_t	mip::C::mip_packet_buffer_length (const mip_packet_view *packet)
	Returns the size of the buffer backing the MIP packet. More...
int	mip::C::mip_packet_remaining_space (const mip_packet_view *packet)
	Returns the remaining space available for more payload data. More...
bool	mip::C::mip_packet_is_data (const mip_packet_view *packet)
	Returns true if the packet is from a data descriptor set. More...

Detailed Description

Use these functions to get information about a MIP packet after it has been parsed. Generally, first the descriptor set would be inspected followed by iterating the fields using the MipFieldIteration functions.

With the exception of mip_packet_checksum_value() (and any function which calls it, e.g. mip_packet_is_valid()), these functions may also be used on packets which are under construction via the PacketBuilding functions.

Warning

Do not call the packet-building functions unless you know the input buffer is not const.

Function Documentation

mip_packet_from_buffer()

void mip::C::mip_packet_from_buffer	(	mip_packet_view *	packet,
		const uint8_t *	buffer,
		size_t	length
	)

Use this when receiving or parsing MIP packets.

The data in the buffer should be a valid or suspected MIP packet.

Parameters

packet
buffer	The data buffer containing the bytes for a MIP packet. Must be at least MIP_PACKET_LENGTH_MIN bytes in size.
length	The length of the data pointed to by buffer.

Note

The data does not need to be a valid MIP packet, for instance to use the mip_packet_is_sane() or mip_packet_is_valid() functions. However, if it is NOT a valid MIP packet, the result of calling any accessor function is unpredictable. In particular, if length is less than MIP_PACKET_LENGTH_MIN bytes, calling the accessor functions is undefined behavior.

mip_packet_descriptor_set()

uint8_t mip::C::mip_packet_descriptor_set

(

const mip_packet_view *

packet

)

mip_packet_total_length()

uint_least16_t mip::C::mip_packet_total_length

(

const mip_packet_view *

packet

)

Returns

The length of the packet. Always at least MIP_PACKET_LENGTH_MIN.

mip_packet_payload_length()

uint8_t mip::C::mip_packet_payload_length

(

const mip_packet_view *

packet

)

mip_packet_buffer()

const uint8_t * mip::C::mip_packet_buffer

(

const mip_packet_view *

packet

)

mip_packet_buffer_w()

uint8_t * mip::C::mip_packet_buffer_w

(

mip_packet_view *

packet

)

mip_packet_data()

const uint8_t * mip::C::mip_packet_data

(

const mip_packet_view *

packet

)

mip_packet_payload()

const uint8_t * mip::C::mip_packet_payload

(

const mip_packet_view *

packet

)

mip_packet_payload_w()

uint8_t * mip::C::mip_packet_payload_w

(

mip_packet_view *

packet

)

mip_packet_checksum_value()

uint16_t mip::C::mip_packet_checksum_value

(

const mip_packet_view *

packet

)

This function does not compute the checksum. To do so, use mip_packet_compute_checksum().

mip_packet_compute_checksum()

uint16_t mip::C::mip_packet_compute_checksum

(

const mip_packet_view *

packet

)

Returns

The computed checksum value.

mip_packet_is_sane()

bool mip::C::mip_packet_is_sane

(

const mip_packet_view *

packet

)

If the packet is not 'sane', then none of the mip_packet_* functions may be used to access it (to do so is undefined behavior). This should never occur in normal circumstances.

mip_packet_is_valid()

bool mip::C::mip_packet_is_valid

(

const mip_packet_view *

packet

)

A packet is valid if:

• mip_packet_is_sane() returns true,
• The descriptor set is not 0x00, and
• The checksum is valid.

mip_packet_is_empty()

bool mip::C::mip_packet_is_empty

(

const mip_packet_view *

packet

)

Parameters

packet

Returns

true if the packet has a payload length of 0.

mip_packet_buffer_length()

uint_least16_t mip::C::mip_packet_buffer_length

(

const mip_packet_view *

packet

)

Note

This is the entire buffer size and not the packet length.

mip_packet_remaining_space()

int mip::C::mip_packet_remaining_space

(

const mip_packet_view *

packet

)

This is equal to the buffer size less the total packet length.

Warning

The result may be negative if the packet length exceeds the actual buffer capacity. Such packets are not 'sane' (mip_packet_is_sane) and can only be produced by manipulating the buffered data directly.

mip_packet_is_data()

bool mip::C::mip_packet_is_data

(

const mip_packet_view *

packet

)

See also

is_data_descriptor_set

Returns

true if the packet contains data.

false if it contains commands or replies.