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


6.3.1 Creating Messages

A message list contains message objects. A message handle refers to an individual message object.

Data type: qsmm_msg_t

This is a type for a message handle. It is a pointer, so variables of this type can be NULL. The functions qsmm_msg_create_f and qsmm_msg_create_fv allocate a new message handle. The function qsmm_msg_destroy frees the handle of a message not added to a message list. If a message is in a message list, clearing or destroying the message list frees the handle of this message. You can pass an allocated message handle to API functions taking an argument of qsmm_msg_t type until freeing the handle.

When creating a message object, you specify its message category using the following enumeration.

Enumeration: qsmm_msg_e

This enumeration specifies the category of a message. That category affects labeling the message in its text representation. The function qsmm_get_msglist_sz_type retrieves the number of messages with a specific category contained in a message list. The enumeration consists of the following elements.

QSMM_MSG_GENERAL

An uncategorized message. No category label precedes a message text.

QSMM_MSG_NOTE

A note message. The label ‘note: ’ precedes a message text.

QSMM_MSG_WARNING

A warning message. The label ‘warning: ’ precedes a message text.

QSMM_MSG_ERROR

An error message. The label ‘error: ’ precedes a message text.

QSMM_MSG_COUNT

The last element of this enumeration equal to the number of supported message categories.

Use the following functions to create a message object with a specified message text.

Function: int qsmm_msg_create_f (qsmm_msg_t *msg_p, enum qsmm_msg_e msg_type, const char *fmt_p, ...)
Function: int qsmm_msg_create_fv (qsmm_msg_t *msg_p, enum qsmm_msg_e msg_type, const char *fmt_p, va_list ap)

These functions create a message with a category msg_type and store a newly allocated message handle in *msg_p if msg_p is not NULL. If msg_p is NULL, the functions destroy the created message and report success.

The function qsmm_msg_create_f formats a message text according to the argument fmt_p and subsequent arguments interpreted as in the function printf. The function qsmm_msg_create_fv formats a message text according to the arguments fmt_p and ap interpreted as in the function vprintf. If fmt_p is NULL, the functions create an empty message. In this case, the function qsmm_msg_create_fv ignores the argument ap.

The functions return a non-negative value on success or a negative error code on failure in creating a message. Currently, the functions can return the following error codes.

QSMM_ERR_INVAL

The argument msg_type is negative or greater than or equal to QSMM_MSG_COUNT.

QSMM_ERR_ILSEQ

Unable to convert the message text to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to create the message.

Use the following functions to append text to an already existing message.

Function: int qsmm_msg_append_f (qsmm_msg_t msg, int rez1, const char *fmt, ...)
Function: int qsmm_msg_append_fv (qsmm_msg_t msg, int rez1, const char *fmt, va_list ap)

These functions append a formatted text to a message msg. The argument rez1 is for future use and must be equal to 0.

The function qsmm_msg_append_f formats appended message text according to the argument fmt and subsequent arguments interpreted as in the function printf. The function qsmm_msg_append_fv formats appended message text according to the arguments fmt and ap interpreted as in the function vprintf.

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

QSMM_ERR_ILSEQ

Unable to convert the formatted text to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following function to create a copy of a message object.

Function: int qsmm_msg_clone (qsmm_msg_t src, qsmm_msg_t *dst_p)

This function creates a copy of a message src and stores the handle of this copy in *dst_p if dst_p is not NULL. If dst_p is NULL, the function destroys the created copy 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 copy.

Use the following function to destroy a message object.

Function: void qsmm_msg_destroy (qsmm_msg_t msg)

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

You must not use this function to destroy messages added to a message list. The function qsmm_msglist_clear or qsmm_msglist_destroy destroys those messages when clearing or destroying the message list.

Use the following function to get the category of a message.

Function: enum qsmm_msg_e qsmm_get_msg_type (qsmm_msg_t msg)

This function returns the category of a message msg. The function qsmm_msg_create_f or qsmm_msg_create_fv sets that category when creating the message.

A message can have a line number assigned. If the line number is positive, and the function qsmm_msg_str or qsmm_msglist_dump (see Printing Messages) knows a file name associated with the message, that function prepends this name and line number to a message text. By default, a created message does not have a line number assigned.

Function: int qsmm_set_msg_lineno (qsmm_msg_t msg, long lineno)

This function assigns line number lineno to a message msg.

If the function qsmm_msg_str or qsmm_msglist_dump knows a file name associated with the message, and lineno is non-negative, that function prints this name before a message text. If qsmm_msg_str or qsmm_msglist_dump knows the file name, and lineno is positive, that function prints line number lineno after this name and before a message text.

If lineno is 0, qsmm_msg_str or qsmm_msglist_dump does not print a line number before a message text. However, that function prints the file name there. Thus, special value 0 may indicate that the message pertains to the entire file. If lineno is -1, the function does not prepend the file name and line number to a message text.

The function qsmm_set_msg_lineno 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 lineno is less than -1.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


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