Common Pipeline Library Reference Manual  6.1.1
Functions
Handling of multiple CPL errors

Functions

void cpl_errorstate_dump (cpl_errorstate self, cpl_boolean reverse, void(*dump_one)(unsigned, unsigned, unsigned))
 Dump the CPL error state.
void cpl_errorstate_dump_one (unsigned self, unsigned first, unsigned last)
 Dump a single CPL error.
void cpl_errorstate_dump_one_debug (unsigned self, unsigned first, unsigned last)
 Dump a single CPL error using cpl_msg_debug()
void cpl_errorstate_dump_one_info (unsigned self, unsigned first, unsigned last)
 Dump a single CPL error using cpl_msg_info()
void cpl_errorstate_dump_one_warning (unsigned self, unsigned first, unsigned last)
 Dump a single CPL error using cpl_msg_warning()
cpl_errorstate cpl_errorstate_get (void)
 Get the CPL errorstate.
cpl_boolean cpl_errorstate_is_equal (cpl_errorstate self)
 Detect a change in the CPL error state.
void cpl_errorstate_set (cpl_errorstate self)
 Set the CPL errorstate.

Detailed Description

This module provides functions for error detection and recovery and for producing an error traceback.

It is built on top of the cpl_error module.

Synopsis:
#include <cpl_errorstate.h>

Function Documentation

void cpl_errorstate_dump ( cpl_errorstate  self,
cpl_boolean  reverse,
void(*)(unsigned, unsigned, unsigned)  dump_one 
)

Dump the CPL error state.

Parameters:
selfDump errors more recent than self
reverseReverse the chronological order of the dump
dump_oneFunction that dumps a single CPL error, or NULL
Returns:
void
Note:
dump_one may be NULL, in that case cpl_errorstate_dump_one() is called. If there are no CPL errors to be dumped, (*dump_one)() is called once with all zeros, which allows the dump-function to report that there are no errors to dump. During calls to (*dump_one)() the CPL error system has been put into a special read-only mode that prevents any change of the CPL error state. This means that any calls from (*dump_one)() to cpl_error_reset(), cpl_error_set(), cpl_error_set_where() and cpl_errorstate_set() have no effect. Also calls from (*dump_one)() to cpl_errorstate_dump() have no effect.
See also:
cpl_errorstate_dump_one

Example of usage:

cpl_errorstate prev_state = cpl_errorstate_get();
// Call one or more CPL functions
if (cpl_errorstate_is_equal(prev_state)) {
// No error happened
} else {
// One or more errors happened
// Dump the error(s) in chronological order
cpl_errorstate_dump(prev_state, CPL_FALSE,
// Recover from the error(s)
cpl_errorstate_set(prev_state);
}
void cpl_errorstate_dump_one ( unsigned  self,
unsigned  first,
unsigned  last 
)

Dump a single CPL error.

Parameters:
selfThe number of the current error to be dumped
firstThe number of the first error to be dumped
lastThe number of the last error to be dumped
Returns:
void
Note:
This function is implemented using only exported CPL functions.
See also:
cpl_errorstate_dump

This function will dump a single CPL error, using the CPL error accessor functions. The error is numbered with the value of self.

The actual output is produced by cpl_msg_error().

first and last are provided in the API to allow for special messaging in the dump of the first and last errors.

Alternative functions for use with cpl_errorstate_dump() may use all accessor functions of the CPL error module and those functions of the CPL message module that produce messages. Additionally, the indentation functions of the CPL message module may be used, provided that the indentation is set back to its original state after the last error has been processed.

The body of cpl_errorstate_dump_one looks like this:

const cpl_boolean is_reverse = first > last ? CPL_TRUE : CPL_FALSE;
const unsigned newest = is_reverse ? first : last;
const unsigned oldest = is_reverse ? last : first;
const char * revmsg = is_reverse ? " in reverse order" : "";
assert( oldest <= self );
assert( newest >= self );
if (newest == 0) {
cpl_msg_info(cpl_func, "No error(s) to dump");
cx_assert( oldest == 0);
} else {
cx_assert( oldest > 0);
cx_assert( newest >= oldest);
if (self == first) {
if (oldest == 1) {
cpl_msg_error(cpl_func, "Dumping all %u error(s)%s:", newest,
revmsg);
} else {
cpl_msg_error(cpl_func, "Dumping the %u most recent error(s) out"
" of a total of %u errors%s:", newest - oldest + 1,
newest, revmsg);
}
}
cpl_msg_error(cpl_func, "[%u/%u] '%s' (%u) at %s", self, newest,
if (self == last) cpl_msg_indent_less();
}
void cpl_errorstate_dump_one_debug ( unsigned  self,
unsigned  first,
unsigned  last 
)

Dump a single CPL error using cpl_msg_debug()

Parameters:
selfThe number of the current error to be dumped
firstThe number of the first error to be dumped
lastThe number of the last error to be dumped
Returns:
void
See also:
cpl_errorstate_dump_one, cpl_msg_debug()
void cpl_errorstate_dump_one_info ( unsigned  self,
unsigned  first,
unsigned  last 
)

Dump a single CPL error using cpl_msg_info()

Parameters:
selfThe number of the current error to be dumped
firstThe number of the first error to be dumped
lastThe number of the last error to be dumped
Returns:
void
See also:
cpl_errorstate_dump_one, cpl_msg_info()
void cpl_errorstate_dump_one_warning ( unsigned  self,
unsigned  first,
unsigned  last 
)

Dump a single CPL error using cpl_msg_warning()

Parameters:
selfThe number of the current error to be dumped
firstThe number of the first error to be dumped
lastThe number of the last error to be dumped
Returns:
void
See also:
cpl_errorstate_dump_one, cpl_msg_warning()
cpl_errorstate cpl_errorstate_get ( void  )

Get the CPL errorstate.

Returns:
The CPL errorstate
Note:
The caller should not modify the returned value nor transfer it to another function/scope.

Example of usage:

cpl_errorstate prev_state = cpl_errorstate_get();
// (Call one or more CPL functions here)
if (cpl_errorstate_is_equal(prev_state)) {
// No error happened
} else {
// One or more errors happened
// Recover from the error(s)
cpl_errorstate_set(prev_state);
}
cpl_boolean cpl_errorstate_is_equal ( cpl_errorstate  self)

Detect a change in the CPL error state.

Parameters:
selfThe return value of a previous call to cpl_errorstate_get()
Returns:
CPL_TRUE iff the current error state is equal to self.
See also:
cpl_errorstate_get
void cpl_errorstate_set ( cpl_errorstate  self)

Set the CPL errorstate.

Parameters:
selfThe return value of a previous call to cpl_errorstate_get()
Returns:
void
See also:
cpl_errorstate_get
Note:
If a CPL error was created before the call to cpl_errorstate_get() that returned self and if more than CPL_ERROR_HISTORY_SIZE CPL errors was created after that, then the accessor functions of the CPL error object (cpl_error_get_code() etc.) will return wrong values. In this case cpl_error_get_code() is still guaranteed not to return CPL_ERROR_NONE. Moreover, the default value of CPL_ERROR_HISTORY_SIZE is guaranteed to be large enough to prevent this situation from arising due to a call of a CPL function.