---

6.3.3 Adding Messages to a Message List ¶

Use the following function to add a message to a message list.

Function: int qsmm_msglist_add_msg (qsmm_msglist_t msglist, qsmm_msg_t msg) ¶

This function adds a message msg to a message list msglist. The message list becomes the owner of the message. You must not add a message to multiple message lists.

After adding a message to a message list, you must not explicitly destroy the message by the function qsmm_msg_destroy. The function qsmm_msglist_clear or qsmm_msglist_destroy destroys the message automatically when clearing or destroying the message list.

The function qsmm_msglist_add_msg returns a non-negative value on success or negative error code QSMM_ERR_NOMEM if there was not enough memory to perform the operation.

Use the following function to append to a message list copies of all messages contained in another message list.

Function: int qsmm_msglist_extend (qsmm_msglist_t dst, qsmm_msglist_t src) ¶

This function appends to the end of a message list dst copies of all messages contained in a message list src, in the same order.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument src or dst is NULL, or src is equal to dst.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following function to clear a message list.

Function: void qsmm_msglist_clear (qsmm_msglist_t msglist) ¶

This function removes all messages from a message list msglist and destroys them.

Use the following function to get the total number of messages contained in a message list.

Function: size_t qsmm_get_msglist_sz (qsmm_msglist_t msglist) ¶

This function returns the total number of messages contained in a message list msglist.

Use the following function to get the number of messages belonging to a specific category contained in a message list.

Function: int qsmm_get_msglist_sz_type (qsmm_msglist_t msglist, enum qsmm_msg_e msg_type, size_t *sz_p) ¶

This function retrieves the number of messages belonging to a category msg_type contained in a message list msglist. If sz_p is not NULL, the function sets *sz_p to that number of messages.

If the message list contains at least one message belonging to the category, the function returns a positive value. If the message list does not contain messages belonging to the category, the function returns 0. If msg_type is negative or greater than or equal to QSMM_MSG_COUNT, the function returns negative error code QSMM_ERR_INVAL .

Use the following function to get a message contained in a message list.

Function: qsmm_msg_t qsmm_get_msglist_msg (qsmm_msglist_t msglist, size_t idx) ¶

This function returns the handle of a message contained in a message list msglist at index idx. If idx is greater than or equal to the total number of messages held in the message list, the function returns NULL.