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


6.3.1 Creating Messages

Message objects that can be contained in a message list object are referred to by message handles.

Data type: qsmm_msg_t

This is a type for a message handle. It is a pointer, so variables of this type can have the NULL value. The functions qsmm_msg_create_f and qsmm_msg_create_fv allocate a new message handle. The handle of an existing message can be freed either explicitly by the function qsmm_msg_destroy if the message is not added to a message list or implicitly when clearing or destroying a message list that contains the message. After allocating a message handle, it can be passed to API functions that take an argument of type qsmm_msg_t until the handle is freed.

When creating a message object, its message category should be specified using the following enumeration.

Enumeration: qsmm_msg_e

This enumeration specifies the category of a message. Such a category affects how a message can be labeled when retrieving its text representation. Additionally, there exists an API function for retrieving the number of messages of a specific category contained in a message list object. The enumeration consists of the following elements.

QSMM_MSG_GENERAL

An uncategorized message. No category label is printed before a message text.

QSMM_MSG_NOTE

A note message. The label ‘note: ’ is printed before a message text.

QSMM_MSG_WARNING

A warning message. The label ‘warning: ’ is printed before a message text.

QSMM_MSG_ERROR

An error message. The label ‘error: ’ is printed before a message text.

QSMM_MSG_COUNT

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

To create a message object with a specified message text, the following functions can be used.

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 of category msg_type and store a newly allocated message handle in *msg_p. If msg_p is NULL, then the functions will immediately destroy the internally created message and report success.

The function qsmm_msg_create_f formats the text of the message according to argument fmt_p and subsequent arguments; the meaning of those arguments is the same as in the function printf. The function qsmm_msg_create_fv formats the text of the message according to arguments fmt_p and ap; the meaning of them is the same as in the function vprintf. If fmt_p is NULL, then the functions will create the empty message; in this case, the value of ap is ignored.

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

QSMM_ERR_INVAL

The value of msg_type is negative or greater than or equal to QSMM_MSG_COUNT.

QSMM_ERR_ILSEQ

The text of the message cannot be converted to a wide string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to create the message.

To create a copy of a message object, the following function can be used.

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

This function creates a copy of message src and stores its newly allocated message handle in *dst_p.

The function returns a non-negative value on success or a negative error code on failure in creating a message copy. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

Argument dst_p is NULL.

QSMM_ERR_NOMEM

There was not enough memory to create a copy of the message.

To destroy a message object, the following function can be used.

Function: void qsmm_msg_destroy (qsmm_msg_t msg)

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

The function must not be used to destroy messages added to a message list. Those messages are automatically destroyed when clearing the message list by the function qsmm_msglist_clear or destroying the message list by the function qsmm_msglist_destroy.

To get the category of a message, the following function can be used.

Function: enum qsmm_msg_e qsmm_get_msg_type (qsmm_msg_t msg)

This function returns the category of a message specified by handle msg. Such a category is assigned when creating a message.

To append a formatted string to a message, the following functions can be used.

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 string to a message specified by handle msg. Argument rez1 is reserved for future use and must be equal to 0.

The meaning of argument fmt and subsequent arguments of function qsmm_msg_append_f is the same as in the function printf. The meaning of arguments fmt and ap of function qsmm_msg_append_fv is the same as in the function vprintf.

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

QSMM_ERR_ILSEQ

The formatted string cannot be converted to a wide string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

There can be a line number assigned to a message. If the line number is positive and the name of an input file is specified when dumping the message list, then the name of that file and the line number will be printed before the text of the message. 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 message msg.

If the name of an input file is known to an API function that prints the message (see Printing Messages, for a description of such functions), and lineno is non-negative, then the name of the input file can be printed before the text of this message. If the name of an input file is known, and lineno is positive, then line number lineno can be printed after the name of the file and before the text of this message.

If lineno is 0, then no line number will be printed before the text of this message. However, the name of an input file can be printed there. Thus, special value 0 may indicate that the message pertains to the entire file. If lineno is -1, then it means that there is no line number actually assigned to the message, and the name of an input file will not be printed.

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

QSMM_ERR_INVAL

The value of 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]