Next: Creating a Message List, Up: Messages and Message Lists [Contents][Index]
A message list contains message objects. A message handle refers to an individual message object.
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.
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.
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.
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.
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.
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.
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.
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: Creating a Message List, Up: Messages and Message Lists [Contents][Index]