Packet Building

Functions for building new MIP packets. More...

Functions
void	mip::C::mip_packet_create (mip_packet_view *packet, uint8_t *buffer, size_t buffer_size, uint8_t descriptor_set)
	Create a brand-new MIP packet in the given buffer. More...
bool	mip::C::mip_packet_add_field (mip_packet_view *packet, uint8_t field_descriptor, const uint8_t *payload, uint8_t payload_length)
	Adds a pre-constructed MIP field to the packet. More...
int	mip::C::mip_packet_create_field (mip_packet_view *packet, uint8_t field_descriptor, uint8_t payload_length, uint8_t **payload_ptr_out)
	Allocate a MIP field within the packet and return the payload pointer. More...
int	mip::C::mip_packet_update_last_field_length (mip_packet_view *packet, uint8_t *payload_ptr, uint8_t new_payload_length)
	Changes the size of the last field in the packet. More...
int	mip::C::mip_packet_cancel_last_field (mip_packet_view *packet, uint8_t *payload_ptr)
	Removes the last field from the packet after having allocated it. More...
void	mip::C::mip_packet_finalize (mip_packet_view *packet)
	Prepares the packet for transmission by adding the checksum. More...
void	mip::C::mip_packet_reset (mip_packet_view *packet, uint8_t descriptor_set)
	Reinitialize the packet with the given descriptor set. More...

Detailed Description

Functions for building new MIP packets.

Use these functions to create a new packet, add fields, and write the checksum.

Function Documentation

mip_packet_add_field()

bool mip::C::mip_packet_add_field	(	mip_packet_view *	packet,
		uint8_t	field_descriptor,
		const uint8_t *	payload,
		uint8_t	payload_length
	)

Adds a pre-constructed MIP field to the packet.

                                            +--------------------+
                                            |  Payload Bytes     |
                              Len  Desc     +--------------------+
                               |    |        | copy
 Packet Buffer                 V    V        V
---------------+------------+-   -+-    -+--                  -+-
 ...   Header  |   Field    | Len | Desc |  Payload            |
---------------+------------+-----+------+---------------------+----------
                            |                                  |
                    End of last field   --------------->  End of new field

Parameters

packet
field_descriptor	The MIP field descriptor (e.g. command or data descriptor).
payload	A pointer to the field payload data (without the header). Can be NULL if payload_length is 0.
payload_length	The length of the payload data. Must be less than or equal to MIP_FIELD_PAYLOAD_LENGTH_MAX. Does not include the header.

Returns

true if the field was added, or false if there was not enough space.

mip_packet_cancel_last_field()

int mip::C::mip_packet_cancel_last_field	(	mip_packet_view *	packet,
		uint8_t *	payload_ptr
	)

Removes the last field from the packet after having allocated it.

Use only after allocating a field with mip_packet_create_field to cancel it. E.g. if it turns out that there isn't enough buffer space to write the payload.

Parameters

packet
payload_ptr	Pointer to the field payload. This must be the same value returned from alloc_field and must point to the last field.

Returns

The remaining space in the packet after removing the field.

mip_packet_create()

void mip::C::mip_packet_create	(	mip_packet_view *	packet,
		uint8_t *	buffer,
		size_t	buffer_size,
		uint8_t	descriptor_set
	)

Create a brand-new MIP packet in the given buffer.

Use this along with the packet building functions to create MIP packets.

Parameters

packet
buffer	This is where the packet bytes will be stored. Must be at least MIP_PACKET_LENGTH_MIN bytes in size.
buffer_size	The size of buffer, in bytes.
descriptor_set	The MIP descriptor set for the packet.

mip_packet_create_field()

int mip::C::mip_packet_create_field	(	mip_packet_view *	packet,
		uint8_t	field_descriptor,
		uint8_t	payload_length,
		uint8_t **	payload_ptr_out
	)

Allocate a MIP field within the packet and return the payload pointer.

                              Len   Desc  .---> Payload ptr out
                               |     |    |
 Packet Buffer                 V     V    |
---------------+------------+-   -+-    -+---------------------+----------
 ...   Header  |   Field    | Len | Desc | (unwritten payload) |
---------------+------------+-----+------+---------------------+----------
                            |                                  |
                    End of last field   --------------->  End of new field

Parameters

packet
field_descriptor	The MIP field descriptor (e.g. command or data descriptor).
payload_length	The requested length of the field payload (not including the header). If the size is not known ahead of time, pass 0 and inspect the return value to see how much payload data can be written. Then call mip_packet_realloc_field() with the used size and same payload pointer.
payload_ptr_out	A pointer to a pointer to the field payload. This will receive the payload pointer into which data should be written.

Returns

The amount of space remaining after allocating this field. If this is negative, the field could not be allocated and the payload must not be written.

mip_packet_finalize()

void mip::C::mip_packet_finalize

(

mip_packet_view *

packet

)

Prepares the packet for transmission by adding the checksum.

This does not increase the total packet length since the checksum is always implicitly included.

                                                         Checksum
                                                           VVVV
---------------+------------+------------+-----//-----+--        --+----
 ...   Header  |   Field    |   Field    |     ...    |  (empty)   |
---------------+------------+------------+-----//-----+------------+----
                                                      |            |
                                           End of last field       |
                                                              Total Length

mip_packet_reset()

void mip::C::mip_packet_reset	(	mip_packet_view *	packet,
		uint8_t	descriptor_set
	)

Reinitialize the packet with the given descriptor set.

This clears out all of the fields but keeps the same buffer.

Parameters

packet
descriptor_set	New descriptor set.

mip_packet_update_last_field_length()

int mip::C::mip_packet_update_last_field_length	(	mip_packet_view *	packet,
		uint8_t *	payload_ptr,
		uint8_t	new_payload_length
	)

Changes the size of the last field in the packet.

Use this in conjunction with mip_packet_create_field() when the size of the field is not known in advance. Pass a payload size of 0 to alloc_field and check that the returned available space is sufficient, then write the payload and call this function with the actual space used.

Parameters

packet
payload_ptr	Pointer to the field payload. This must be the same value returned from alloc_field and must point to the last field.
new_payload_length	Length of payload written. Generally it is an error for this to exceed the actual amount of space available in the packet. In this case, the packet is left with just the empty field and the return value will be negative.

Returns

The space remaining in the packet after changing the field size. This will be negative if the new length did not fit.