Next: , Previous: , Up: Messages and Message Lists   [Contents][Index]


6.3.2 Creating a Message List

A message list is referred to by a message list handle.

Data type: qsmm_msglist_t

This is a type for a message list handle. It is a pointer, so variables of this type can have the NULL value. The function qsmm_msglist_create allocates a new message list handle. The function qsmm_msglist_destroy frees an existing message list handle. After allocating a message list handle, it can be passed to API functions that take an argument of type qsmm_msglist_t until the handle is freed.

Use the following function to create an empty message list, e.g. to pass the list 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 NULL, then the function will have no effect.

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

To destroy a message list and all the messages it contains, the following function can be used.

Function: void qsmm_msglist_destroy (qsmm_msglist_t msglist)

This function destroys a message list specified by handle msglist. After the destruction, the handle must not be used. If msglist is NULL, then the function will have no effect.