Functions | |
cpl_error_code | cpl_msg_init (void) |
Initialise the messaging system. | |
void | cpl_msg_stop (void) |
Turn the messaging system off. | |
cpl_error_code | cpl_msg_set_log_level (cpl_msg_severity verbosity) |
Open and initialise a log file. | |
cpl_error_code | cpl_msg_stop_log (void) |
Close the current log file. | |
const char * | cpl_msg_get_log_name (void) |
Get the log file name. | |
cpl_error_code | cpl_msg_set_log_name (const char *name) |
Set the log file name. | |
void | cpl_msg_set_level (cpl_msg_severity verbosity) |
Set verbosity level of output to terminal. | |
cpl_msg_severity | cpl_msg_get_log_level (void) |
Get current log verbosity level. | |
cpl_msg_severity | cpl_msg_get_level (void) |
Get current terminal verbosity level. | |
void | cpl_msg_set_time_on (void) |
Attach a time tag to output messages. | |
void | cpl_msg_set_time_off (void) |
Disable the time tag in output messages. | |
void | cpl_msg_set_domain_on (void) |
Attach the domain tag to output messages. | |
void | cpl_msg_set_domain_off (void) |
Disable the domain tag in output messages. | |
void | cpl_msg_set_component_on (void) |
Attach the component tag to output messages. | |
void | cpl_msg_set_component_off (void) |
Disable the component tag in output messages. | |
void | cpl_msg_set_domain (const char *name) |
Set the domain name. | |
void | cpl_msg_set_width (int width) |
Set the maximum width of the displayed text. | |
void | cpl_msg_set_indentation (int step) |
Set the indentation step. | |
void | cpl_msg_indent (int level) |
Set the indentation level. | |
void | cpl_msg_indent_more (void) |
Increase the message indentation by one indentation step. | |
void | cpl_msg_indent_less (void) |
Decrease the message indentation by one indentation step. | |
void | cpl_msg_error (const char *component, const char *format,...) |
Display an error message. | |
void | cpl_msg_warning (const char *component, const char *format,...) |
Display a warning message. | |
void | cpl_msg_info (const char *component, const char *format,...) |
Display an information message. | |
void | cpl_msg_info_overwritable (const char *component, const char *format,...) |
Display an overwritable information message. | |
void | cpl_msg_debug (const char *component, const char *format,...) |
Display a debug message. | |
void | cpl_msg_progress (const char *component, int i, int iter, const char *format,...) |
Display a progress message predicting the time required in a loop. |
To activate and deactivate the messaging system, the functions cpl_msg_init()
and cpl_msg_stop()
need to be used. However, since they are called anyway by the functions cpl_init()
and cpl_end()
, there is generally no need to call them explicitly, and starting from CPL 2.1 they are deprecated. These functions would typically be called at the beginning and at the end of a program. An attempt to use an uninitialised messaging system would generate a warning message. More functions may also be used to configure the messaging system, and here is an example of a possible initialisation:
... cpl_msg_set_time_on(); cpl_msg_set_component_on(); cpl_msg_set_domain("Source detection"); cpl_msg_set_domain_on(); cpl_msg_set_level(CPL_MSG_ERROR); cpl_msg_set_log_level(CPL_MSG_DEBUG); ...
Three different tags may be attached to any message: time, domain, and component. The time tag is the time of printing of the message, and can optionally be turned on or off with the functions cpl_msg_set_time_on()
and cpl_msg_set_time_off()
. The domain tag is an identifier of the main program running (typically, a pipeline recipe), and can be optionally turned on or off with the functions cpl_msg_set_domain_on()
and cpl_msg_set_domain_off()
. Finally, the component tag is used to identify a component of the program running (typically, a function), and can be optionally turned on or off with the functions cpl_msg_set_component_on()
and cpl_msg_set_component_off()
. As a default, none of the above tags are attached to messages sent to terminal. However, all tags are always used in messages sent to the log file. A further tag, the severity tag, can never be turned off. This tag depends on the function used to print a message, that can be either cpl_msg_debug()
, cpl_msg_info()
, cpl_msg_warning()
, or cpl_msg_error()
. The time and severity tags are all prepended to any message, and are not affected by the message indentation controlled by the functions cpl_msg_indent()
, cpl_msg_indent_more()
, cpl_msg_indent_less()
, and cpl_msg_set_indentation()
.
#include <cpl_msg.h>
|
Display a debug message.
cpl_msg_error() . |
|
Display an error message.
printf() convention. Newline characters shouldn't generally be used, as the message would be split automatically according to the width specified with cpl_msg_set_width(). Inserting a newline character would enforce breaking a line of text even before the current row is filled. Newline characters at the end of the format string are not required. If component is a NULL pointer, it would be set to the string "<empty field>". If format is a NULL pointer, the message "<empty message>" would be printed. |
|
Get current terminal verbosity level.
|
|
Get current log verbosity level.
|
|
Get the log file name.
|
|
Set the indentation level.
cpl_msg_set_indentation() . Specifying a negative indentation level would set the indentation level to zero. |
|
Decrease the message indentation by one indentation step.
|
|
Increase the message indentation by one indentation step.
cpl_msg_indent() . |
|
Display an information message.
cpl_msg_error() . |
|
Display an overwritable information message.
cpl_msg_error() . The severity of the message issued by cpl_msg_info_overwritable() is the same as the severity of a message issued using cpl_msg_info() . The only difference with the cpl_msg_info() function is that the printed message would be overwritten by a new message issued using again cpl_msg_info_overwritable(), if no other meassages were issued with other messaging functions in between. This function would be used typically in loops, as in the following example: iter = 1000; for (i = 0 ; i < iter; i++) { cpl_msg_info_overwritable(fctid, "Median computation... %d out of %d", i, iter); <median computation would take place here> }
|
|
Initialise the messaging system.
This function needs to be called to activate the messaging system, typically at the beginning of a program. An attempt to use any messaging function before turning the system on would generate a warning message. The messaging system needs to be deactivated by calling the function
When |
|
Display a progress message predicting the time required in a loop.
iter = 1000; for (i = 0 ; i < iter; i++) { cpl_msg_progress(fctid, i, iter, "Median computation..."); my_time_consuming_operation(); } iter must be positive and should not change during the loop. i must have a value between 0 and iter - 1, and if this condition is not met this funtion returns with nothing done and no error set. i must be zero in the call during the 1st iteration and must monotonely increase while remaining less than iter. This means that each iteration may at most call this function once. Additionally, during the last iteration this function must be called with i = iter - 1. No prediction is displayed if the loop finishes in less than 10 seconds. If the loop does not finish within 10 seconds of the predicted time a new prediction is made and displayed. This function may not be used concurrently with cpl_tools_get_cputime(). |
|
Disable the component tag in output messages.
CPL_MSG_DEBUG . The component tag cannot be turned off in messages written to the log file. |
|
Attach the component tag to output messages.
cpl_msg_set_component_off() should be called. However, the component tag is always shown when the verbosity level is set to CPL_MSG_DEBUG . |
|
Set the domain name.
cpl_msg_set_domain_on() is called. If the domain tag is on and no domain tag was specified, the string "Undefined domain" (or something analogous) would be attached to all messages. To turn the domain tag off the function cpl_msg_set_domain_off() should be called. If name is a NULL pointer, nothing is done, and no error is set. |
|
Disable the domain tag in output messages.
|
|
Attach the domain tag to output messages.
cpl_msg_set_domain_off() must be called. |
|
Set the indentation step.
|
|
Set verbosity level of output to terminal.
CPL_MSG_INFO . |
|
Open and initialise a log file.
If the specified verbosity level is different from |
|
Set the log file name.
This function is used to set the log file name, and can only be called before the log is opened by |
|
Disable the time tag in output messages.
|
|
Attach a time tag to output messages.
cpl_msg_set_time_off() should be called. |
|
Set the maximum width of the displayed text.
|
|
Turn the messaging system off.
cpl_msg_init() needs to be called. However, since these functions are called anyway by the functions cpl_init() and cpl_end() , there is generally no need to call them explicitly, and starting from CPL 2.1 they are deprecated.
When |
|
Close the current log file.
cpl_msg_get_log_name() . An attempt to close a non existing log file would not generate an error condition. This routine may be called in case the logging should be terminated before the end of a program. Otherwise, the function cpl_msg_stop() would automatically close the log file when called at the end of the program. |
|
Display a warning message.
cpl_msg_error() . |