6.3.2 Creating a Message List

A message list handle refers to a message list.

Data type: qsmm_msglist_t

This is a type for a message list handle. It is a pointer, so variables of this type can be NULL. The function qsmm_msglist_create allocates a new message list handle. The function qsmm_msglist_destroy frees an existing message list handle. You can pass an allocated message list handle to API functions taking an argument of qsmm_msglist_t type until freeing the handle.

Use the following function to create an empty message list for passing it to a function that can fill it with messages.

Function: int qsmm_msglist_create (qsmm_msglist_t *msglist_p)

This function creates an empty message list and stores its newly allocated handle in *msglist_p if msglist_p is not NULL. If msglist_p is NULL, the function destroys the created message list and reports success.

The function returns a non-negative value on success or negative error code QSMM_ERR_NOMEM if there was not enough memory to create a message list.

Use the following function to destroy a message list and all the messages it contains.

Function: void qsmm_msglist_destroy (qsmm_msglist_t msglist)

This function destroys a message list specified by a handle msglist. You must not use the message list handle after destroying the message list. If msglist is NULL, the function has no effect.