Functions for building new MIP packets. More...
Functions | |
| bool | mip_packet_add_field (mip_packet *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_packet_alloc_field (mip_packet *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_packet_cancel_last_field (mip_packet *packet, uint8_t *payload_ptr) |
| Removes the last field from the packet after having allocated it. More... | |
| void | mip_packet_create (mip_packet *packet, uint8_t *buffer, size_t buffer_size, uint8_t descriptor_set) |
| Create a brand-new MIP packet in the given buffer. More... | |
| void | mip_packet_finalize (mip_packet *packet) |
| Prepares the packet for transmission by adding the checksum. More... | |
| int | mip_packet_realloc_last_field (mip_packet *packet, uint8_t *payload_ptr, uint8_t new_payload_length) |
| Changes the size of the last field in the packet. More... | |
| void | mip_packet_reset (mip_packet *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_packet_add_field | ( | mip_packet * | packet, |
| uint8_t | field_descriptor, | ||
| const uint8_t * | payload, | ||
| uint8_t | payload_length | ||
| ) |
Adds a pre-constructed MIP field to the packet.
- 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.
Definition at line 289 of file mip_packet.c.
◆ mip_packet_alloc_field()
| int mip_packet_alloc_field | ( | mip_packet * | packet, |
| uint8_t | field_descriptor, | ||
| uint8_t | payload_length, | ||
| uint8_t **const | payload_ptr_out | ||
| ) |
Allocate a MIP field within the packet and return the payload pointer.
- 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.
Definition at line 331 of file mip_packet.c.
◆ mip_packet_cancel_last_field()
| int mip_packet_cancel_last_field | ( | mip_packet * | 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_alloc_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.
Definition at line 414 of file mip_packet.c.
◆ mip_packet_create()
| void mip_packet_create | ( | mip_packet * | 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.
Definition at line 62 of file mip_packet.c.
◆ mip_packet_finalize()
| void mip_packet_finalize | ( | mip_packet * | 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.
Definition at line 443 of file mip_packet.c.
◆ mip_packet_realloc_last_field()
| int mip_packet_realloc_last_field | ( | mip_packet * | 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_alloc_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.
Definition at line 378 of file mip_packet.c.
◆ mip_packet_reset()
| void mip_packet_reset | ( | mip_packet * | 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.
Definition at line 461 of file mip_packet.c.