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...

uint8_t *	mip::C::mip_packet_buffer (mip_packet_view *packet)
	Returns a writable pointer to the data buffer. More...

const uint8_t *	mip::C::mip_packet_pointer (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...

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_size (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

Functions for accessing information about an existing MIP packet.

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_buffer()

uint8_t * mip::C::mip_packet_buffer ( mip_packet_view * packet )

Returns a writable pointer to the data buffer.

◆ mip_packet_buffer_size()

uint_least16_t mip::C::mip_packet_buffer_size ( const mip_packet_view * packet )

Returns the size of the buffer backing the MIP packet.

Note: This is the BUFFER SIZE and not the packet length.

◆ mip_packet_checksum_value()

uint16_t mip::C::mip_packet_checksum_value ( const mip_packet_view * packet )

Returns the value of the checksum as written in the 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 )

Computes the checksum of the MIP packet.

Returns: The computed checksum value.

◆ mip_packet_descriptor_set()

uint8_t mip::C::mip_packet_descriptor_set ( const mip_packet_view * packet )

Returns the MIP descriptor set for this packet.

◆ mip_packet_from_buffer()

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.

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_is_data()

bool mip::C::mip_packet_is_data ( const mip_packet_view * packet )

Returns true if the packet is from a data descriptor set.

See also: is_data_descriptor_set

Returns: true if the packet contains data.; false if it contains commands or replies.

◆ mip_packet_is_empty()

bool mip::C::mip_packet_is_empty ( const mip_packet_view * packet )

Returns true if the mip packet contains no payload.

Parameters

packet

Returns: true if the packet has a payload length of 0.

◆ mip_packet_is_sane()

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).

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 )

Returns true if the packet is valid.

A packet is valid if:

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

◆ mip_packet_payload()

const uint8_t * mip::C::mip_packet_payload ( const mip_packet_view * packet )

Returns a pointer to the packet's payload (the first field).

◆ mip_packet_payload_length()

uint8_t mip::C::mip_packet_payload_length ( const mip_packet_view * packet )

Returns the length of the payload (MIP fields).

◆ mip_packet_pointer()

const uint8_t * mip::C::mip_packet_pointer ( const mip_packet_view * packet )

Returns a pointer to the data buffer containing the packet.

◆ mip_packet_remaining_space()

int mip::C::mip_packet_remaining_space ( const mip_packet_view * packet )

Returns the remaining space available for more payload data.

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_total_length()

uint_least16_t mip::C::mip_packet_total_length ( const mip_packet_view * packet )

Returns the total length of the packet, in bytes.

Returns: The length of the packet. Always at least MIP_PACKET_LENGTH_MIN.