Message Pack

include/rid/message_pack.h Message pack handling per ASTM F3411-22a.

Example usage:

    rid_message_pack_t pack;
    rid_basic_id_t basic_id_1;
    rid_basic_id_t basic_id_2;
    rid_location_t location;
    rid_self_id_t self_id;
    rid_operator_id_t operator_id;
    rid_system_t system;

    rid_message_pack_init(&pack);

    rid_basic_id_init(&basic_id_1);
    rid_basic_id_init(&basic_id_2);
    rid_location_init(&location);
    rid_self_id_init(&self_id);
    rid_operator_id_init(&operator_id);
    rid_system_init(&system);

    rid_message_pack_add_message(&pack, &basic_id_1);
    rid_message_pack_add_message(&pack, &basic_id_2);
    rid_message_pack_add_message(&pack, &location);
    rid_message_pack_add_message(&pack, &self_id);
    rid_message_pack_add_message(&pack, &operator_id);
    rid_message_pack_add_message(&pack, &system);

    printf("%s:\n", rid_message_type_to_string(rid_message_get_type(&pack)));
    hexdump(&pack, rid_message_pack_size(&pack));

    uint8_t count = rid_message_pack_message_count(&pack);

    for (uint8_t i = 0; i < count; i++) {
        const rid_message_t *message = rid_message_pack_get_message_at(&pack, i);
        if (message) {
            printf("%s:\n", rid_message_type_to_string(rid_message_get_type(message)));
            hexdump(&message, sizeof(rid_message_t));
        }
    }

Structures and Types

Type	Name
struct	rid_message_pack_t Message Pack structure per ASTM F3411-22a.

Functions

Type	Name
int	rid_message_pack_add_message (rid_message_pack_t *pack, const void *message) Add a message to a Message Pack.
int	rid_message_pack_copy_message_at (const rid_message_pack_t *pack, uint8_t index, void *message) Copy a message at the specified index out of a Message Pack.
int	rid_message_pack_delete_message_at (rid_message_pack_t *pack, uint8_t index) Delete a message at the specified index.
int	rid_message_pack_find_message_index_by_type (const rid_message_pack_t *pack, rid_message_type_t type, uint8_t start_index, uint8_t *index) Find the index of the first message of the specified type starting at an index.
int	rid_message_pack_get_auth (const rid_message_pack_t *pack, rid_auth_t *auth) Get Auth message from a Message Pack.
const void *	rid_message_pack_get_message_at (const rid_message_pack_t *pack, uint8_t index) Get a pointer to a message at the specified index.
int	rid_message_pack_get_message_type_at (const rid_message_pack_t *pack, uint8_t index, rid_message_type_t *type) Get the message type at the specified index.
const void *	rid_message_pack_get_messages (const rid_message_pack_t *pack) Get a pointer to the messages array in a Message Pack.
int	rid_message_pack_init (rid_message_pack_t *pack) Initialize a Message Pack structure.
uint8_t	rid_message_pack_message_count (const rid_message_pack_t *pack) Get the message count from a Message Pack.
size_t	rid_message_pack_messages_size (const rid_message_pack_t *pack) Get the combined size of messages in a Message Pack in bytes.
int	rid_message_pack_set_auth (rid_message_pack_t *pack, const rid_auth_t *auth) Set Auth message in a Message Pack.
int	rid_message_pack_set_message_at (rid_message_pack_t *pack, uint8_t index, const void *message) Replace a message at the specified index.
size_t	rid_message_pack_size (const rid_message_pack_t *pack) Get the size of a Message Pack in bytes.
int	rid_message_pack_sort (rid_message_pack_t *pack) Sort messages in a Message Pack by message type.
int	rid_message_pack_to_json (const rid_message_pack_t *pack, char *buffer, size_t buffer_size, size_t *needed_size) Format a Message Pack as a JSON string.
int	rid_message_pack_validate (const rid_message_pack_t *pack) Validate a Message Pack structure.

Macros

Type	Name
define	RID_MESSAGE_PACK_HEADER_SIZE 3 Header size of a Message Pack in bytes.
define	RID_MESSAGE_PACK_MAX_MESSAGES 9 Maximum number of messages in a Message Pack.
define	RID_MESSAGE_PACK_MAX_SIZE 228 Maximum size of a Message Pack in bytes (header + 9 messages).
define	RID_MESSAGE_PACK_MIN_SIZE 28 Minimum size of a Message Pack in bytes (header + 1 message).

Structures and Types Documentation

struct rid_message_pack_t

Message Pack structure per ASTM F3411-22a.

Contains up to 9 concatenated messages of 25 bytes each.

Variables:

• uint8_t message_count

• uint8_t message_size

• uint8_t message_type

• uint8_t messages

• uint8_t protocol_version

Functions Documentation

function rid_message_pack_add_message

Add a message to a Message Pack.

int rid_message_pack_add_message (
    rid_message_pack_t *pack,
    const void *message
) 

Parameters:

• pack Pointer to the Message Pack structure.
• message Pointer to the message to add.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack or message is NULL.
• RID_ERROR_OUT_OF_RANGE if pack already contains RID_MESSAGE_PACK_MAX_MESSAGES.

function rid_message_pack_copy_message_at

Copy a message at the specified index out of a Message Pack.

int rid_message_pack_copy_message_at (
    const rid_message_pack_t *pack,
    uint8_t index,
    void *message
) 

Copies RID_MESSAGE_SIZE bytes from the Message Pack at the given index into the caller provided buffer. The destination must point to a struct matching the message type at the index.

Parameters:

• pack Pointer to the Message Pack structure.
• index Index of the message to copy.
• message Pointer to the destination buffer.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack or message is NULL.
• RID_ERROR_OUT_OF_RANGE if index is out of range.

function rid_message_pack_delete_message_at

Delete a message at the specified index.

int rid_message_pack_delete_message_at (
    rid_message_pack_t *pack,
    uint8_t index
) 

Messages after the deleted one are shifted down to fill the gap.

Parameters:

• pack Pointer to the Message Pack structure.
• index Index of the message to delete (0-based).

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack is NULL.
• RID_ERROR_OUT_OF_RANGE if index is out of range.

function rid_message_pack_find_message_index_by_type

Find the index of the first message of the specified type starting at an index.

int rid_message_pack_find_message_index_by_type (
    const rid_message_pack_t *pack,
    rid_message_type_t type,
    uint8_t start_index,
    uint8_t *index
) 

Parameters:

• pack Pointer to the Message Pack structure.
• type The message type to search for.
• start_index Index to start the search from.
• index Pointer to store the index of the first found message.

Return value:

• RID_SUCCESS on success, *index holds the matching index.
• RID_ERROR_NULL_POINTER if pack or index is NULL.
• RID_ERROR_OUT_OF_RANGE if start_index is past the last message.
• RID_ERROR_NOT_FOUND if no message of the given type is found.

function rid_message_pack_get_auth

Get Auth message from a Message Pack.

int rid_message_pack_get_auth (
    const rid_message_pack_t *pack,
    rid_auth_t *auth
) 

Searches the Message Pack for an Auth message and reconstructs it into the provided auth structure. Supports multi-page Auth messages.

Parameters:

• pack Pointer to the Message Pack structure.
• auth Pointer to the Auth structure to populate.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack or auth is NULL.
• RID_ERROR_NOT_FOUND if no Auth message is found in the pack.

function rid_message_pack_get_message_at

Get a pointer to a message at the specified index.

const void * rid_message_pack_get_message_at (
    const rid_message_pack_t *pack,
    uint8_t index
) 

Parameters:

• pack Pointer to the Message Pack structure.
• index Index of the message.

Returns:

Pointer to the message, or NULL if pack is NULL or index is out of range.

function rid_message_pack_get_message_type_at

Get the message type at the specified index.

int rid_message_pack_get_message_type_at (
    const rid_message_pack_t *pack,
    uint8_t index,
    rid_message_type_t *type
) 

Parameters:

• pack Pointer to the Message Pack structure.
• index Index of the message.
• type Pointer to store the message type.

Return value:

• RID_SUCCESS on success, *type holds the message type.
• RID_ERROR_NULL_POINTER if pack or type is NULL.
• RID_ERROR_OUT_OF_RANGE if index is out of range.

function rid_message_pack_get_messages

Get a pointer to the messages array in a Message Pack.

const void * rid_message_pack_get_messages (
    const rid_message_pack_t *pack
) 

Parameters:

• pack Pointer to the Message Pack structure.

Returns:

Pointer to the messages array, or NULL if pack is NULL.

function rid_message_pack_init

Initialize a Message Pack structure.

int rid_message_pack_init (
    rid_message_pack_t *pack
) 

Sets protocol version to RID_PROTOCOL_VERSION_2 and message type to RID_MESSAGE_TYPE_MESSAGE_PACK. The message_size is set to RID_MESSAGE_SIZE. All other fields are zeroed.

Parameters:

• pack Pointer to the Message Pack structure to initialize.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack is NULL.

function rid_message_pack_message_count

Get the message count from a Message Pack.

uint8_t rid_message_pack_message_count (
    const rid_message_pack_t *pack
) 

Parameters:

• pack Pointer to the Message Pack structure.

Returns:

The message count, or 0 if pack is NULL.

function rid_message_pack_messages_size

Get the combined size of messages in a Message Pack in bytes.

size_t rid_message_pack_messages_size (
    const rid_message_pack_t *pack
) 

Parameters:

• pack Pointer to the Message Pack structure.

Returns:

The combined messages size in bytes or 0 if pack is NULL.

function rid_message_pack_set_auth

Set Auth message in a Message Pack.

int rid_message_pack_set_auth (
    rid_message_pack_t *pack,
    const rid_auth_t *auth
) 

Deletes any existing Auth messages from the pack and adds the new Auth message. Supports multi-page Auth messages.

Parameters:

• pack Pointer to the Message Pack structure.
• auth Pointer to the Auth message to set.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack or auth is NULL.
• RID_ERROR_OUT_OF_RANGE if pack cannot accommodate the Auth message.

function rid_message_pack_set_message_at

Replace a message at the specified index.

int rid_message_pack_set_message_at (
    rid_message_pack_t *pack,
    uint8_t index,
    const void *message
) 

Parameters:

• pack Pointer to the Message Pack structure.
• index Index of the message to set.
• message Pointer to the new message.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack or message is NULL.
• RID_ERROR_OUT_OF_RANGE if index is out of range.

function rid_message_pack_size

Get the size of a Message Pack in bytes.

size_t rid_message_pack_size (
    const rid_message_pack_t *pack
) 

Parameters:

• pack Pointer to the Message Pack structure.

Returns:

The size in bytes or 0 if pack is NULL.

function rid_message_pack_sort

Sort messages in a Message Pack by message type.

int rid_message_pack_sort (
    rid_message_pack_t *pack
) 

Messages are sorted in ascending order by the message type. The sort preserves the relative order of messages with the same type.

Parameters:

• pack Pointer to the Message Pack structure.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack is NULL.

function rid_message_pack_to_json

Format a Message Pack as a JSON string.

int rid_message_pack_to_json (
    const rid_message_pack_t *pack,
    char *buffer,
    size_t buffer_size,
    size_t *needed_size
) 

Parameters:

• pack Pointer to the Message Pack structure.
• buffer Buffer to store the JSON string or NULL.
• buffer_size Size of the buffer.
• needed_size If non-NULL receives the required buffer size.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if pack is NULL or if bothbuffer andneeded_size are NULL.
• RID_ERROR_BUFFER_TOO_SMALL if buffer is too small.

function rid_message_pack_validate

Validate a Message Pack structure.

int rid_message_pack_validate (
    const rid_message_pack_t *pack
) 

Checks that all fields contain valid values according to ASTM F3411-22a.

Parameters:

• pack Pointer to the Message Pack structure to validate.

Return value:

• RID_SUCCESS if all fields are valid.
• RID_ERROR_NULL_POINTER if pack is NULL.
• RID_ERROR_INVALID_PROTOCOL_VERSION if protocol version is invalid.
• RID_ERROR_UNKNOWN_MESSAGE_TYPE if message type is not MESSAGE_PACK.
• RID_ERROR_INVALID_MESSAGE_SIZE if message_size is not 25.
• RID_ERROR_INVALID_MESSAGE_COUNT if message_count exceeds maximum.

Macros Documentation

define RID_MESSAGE_PACK_HEADER_SIZE

Header size of a Message Pack in bytes.

#define RID_MESSAGE_PACK_HEADER_SIZE 3

define RID_MESSAGE_PACK_MAX_MESSAGES

Maximum number of messages in a Message Pack.

#define RID_MESSAGE_PACK_MAX_MESSAGES 9

define RID_MESSAGE_PACK_MAX_SIZE

Maximum size of a Message Pack in bytes (header + 9 messages).

#define RID_MESSAGE_PACK_MAX_SIZE 228

define RID_MESSAGE_PACK_MIN_SIZE

Minimum size of a Message Pack in bytes (header + 1 message).

#define RID_MESSAGE_PACK_MIN_SIZE 28