Main Page | Modules | Alphabetical List | Class List | Directories | Class Members

Error handling


Defines

#define cpl_error_set_where(function)
 Set function name, source file and line number where a CPL error occurred.
#define cpl_error_set(function, code)
 Set CPL error code, function name, source file and line number where an error occurred.

Typedefs

typedef enum _cpl_error_code_ cpl_error_code
 The cpl_error_code type definition.

Enumerations

enum  _cpl_error_code_ {
  CPL_ERROR_NONE = 0,
  CPL_ERROR_UNSPECIFIED = 1,
  CPL_ERROR_DUPLICATING_STREAM,
  CPL_ERROR_ASSIGNING_STREAM,
  CPL_ERROR_FILE_IO,
  CPL_ERROR_BAD_FILE_FORMAT,
  CPL_ERROR_FILE_ALREADY_OPEN,
  CPL_ERROR_FILE_NOT_CREATED,
  CPL_ERROR_FILE_NOT_FOUND,
  CPL_ERROR_DATA_NOT_FOUND,
  CPL_ERROR_ACCESS_OUT_OF_RANGE,
  CPL_ERROR_NULL_INPUT,
  CPL_ERROR_INCOMPATIBLE_INPUT,
  CPL_ERROR_ILLEGAL_INPUT,
  CPL_ERROR_ILLEGAL_OUTPUT,
  CPL_ERROR_UNSUPPORTED_MODE,
  CPL_ERROR_SINGULAR_MATRIX,
  CPL_ERROR_DIVISION_BY_ZERO,
  CPL_ERROR_TYPE_MISMATCH,
  CPL_ERROR_INVALID_TYPE,
  CPL_ERROR_CONTINUE,
  CPL_ERROR_EOL
}
 Available error codes. More...

Functions

void cpl_error_reset (void)
 Reset the cpl_error_code.
cpl_error_code cpl_error_set_code (cpl_error_code code)
 Set the cpl_error_code to the specified value.
cpl_error_code cpl_error_get_code (void)
 Get the last cpl_error_code set.
const char * cpl_error_get_message (void)
 Get standard message of last occurred CPL error.
const char * cpl_error_get_function (void)
 Get the function name where the last CPL error occurred.
const char * cpl_error_get_where (void)
 Get function name, source file and line number where the last CPL error occurred.
const char * cpl_error_get_file (void)
 Get the source code file name where the last CPL error occurred.
unsigned cpl_error_get_line (void)
 Get the line number where the last CPL error occurred.

Detailed Description

This module provides functions to maintain the cpl_error_code set by any CPL function, similarly to what is done with the errno variable of the standard C library. The following guidelines are respected:

A cpl_error_code equal to the enumeration constant CPL_ERROR_NONE would indicate no error condition. Note, however, that the cpl_error_code is only set when an error occurs, and it is not reset by successful function calls. For this reason it may be appropriate in some cases to reset the cpl_error_code using the function cpl_error_reset(). The cpl_error_code set by a CPL function can be obtained by calling the function cpl_error_get_code(), but functions of type cpl_error_code would not only return this code directly, but would also return CPL_ERROR_NONE in case of success. Other CPL functions return zero on success, or a non-zero value to indicate a change of the cpl_error_code, while CPL functions returning a pointer would flag an error by returning a NULL.

To each cpl_error_code is associated a standard error message, that can be obtained by calling the function cpl_error_get_message(). Conventionally, no CPL function will ever display any error message, leaving to the caller the decision of how to handle a given error condition. A call to the function cpl_error_get_function() would return the name of the function where the error occurred, and the functions cpl_error_get_file() and cpl_error_get_line() would also return the name of the source file containing the function code, and the line number where the error occurred. The function cpl_error_get_where() would gather all this items together, in a colon-separated string.

Synopsis:
   #include <cpl_error.h>

Define Documentation

#define cpl_error_set function,
code   ) 
 

Set CPL error code, function name, source file and line number where an error occurred.

Parameters:
function Character string with function name
code Error code
Returns:
The specified error code.
Set CPL error code, function name, source file and line number where an error occurred.

#define cpl_error_set_where function   ) 
 

Set function name, source file and line number where a CPL error occurred.

Parameters:
function Character string with function name
Returns:
Nothing.
Set function name, source file and line number where a CPL error occurred. If no error was previously set, the error is set to CPL_ERROR_UNSPECIFIED.


Typedef Documentation

typedef enum _cpl_error_code_ cpl_error_code
 

The cpl_error_code type definition.


Enumeration Type Documentation

enum _cpl_error_code_
 

Available error codes.

Enumeration values:
CPL_ERROR_NONE  No error condition
CPL_ERROR_UNSPECIFIED  An unspecified error. FIXME: Do not set to 1 and verify correctness
CPL_ERROR_DUPLICATING_STREAM  Could not duplicate output stream
CPL_ERROR_ASSIGNING_STREAM  Could not associate a stream with a file descriptor
CPL_ERROR_FILE_IO  Permission denied
CPL_ERROR_BAD_FILE_FORMAT  Input file had not the expected format
CPL_ERROR_FILE_ALREADY_OPEN  Attempted to open a file twice
CPL_ERROR_FILE_NOT_CREATED  Could not create a file
CPL_ERROR_FILE_NOT_FOUND  A specified file or directory was not found
CPL_ERROR_DATA_NOT_FOUND  Data searched within a valid object were not found
CPL_ERROR_ACCESS_OUT_OF_RANGE  Data were accessed beyond boundaries
CPL_ERROR_NULL_INPUT  A NULL pointer was found where a valid pointer was expected
CPL_ERROR_INCOMPATIBLE_INPUT  Data that had to be processed together did not match
CPL_ERROR_ILLEGAL_INPUT  Illegal values were detected
CPL_ERROR_ILLEGAL_OUTPUT  A given operation would have generated an illegal object
CPL_ERROR_UNSUPPORTED_MODE  The requested functionality is not supported
CPL_ERROR_SINGULAR_MATRIX  Could not invert a matrix
CPL_ERROR_DIVISION_BY_ZERO  Attempted to divide a number by zero
CPL_ERROR_TYPE_MISMATCH  Data were not of the expected type
CPL_ERROR_INVALID_TYPE  Data type was unsupported or invalid
CPL_ERROR_CONTINUE  An iterative process did not converge
CPL_ERROR_EOL  To permit extensibility of error handling. It is a coding error to use this within CPL itself!


Function Documentation

cpl_error_code cpl_error_get_code void   ) 
 

Get the last cpl_error_code set.

Returns:
cpl_error_code of last occurred CPL error.
Get cpl_error_code of last occurred error.

const char* cpl_error_get_file void   ) 
 

Get the source code file name where the last CPL error occurred.

Returns:
Name of source file name where the last CPL error occurred.
Get the source code file name where the last CPL error occurred. If the macro __FILE__ is undefined an empty string is returned.

const char* cpl_error_get_function void   ) 
 

Get the function name where the last CPL error occurred.

Returns:
Identifier string of the function name where the last CPL error occurred.
Get the function name where the last CPL error occurred.

unsigned cpl_error_get_line void   ) 
 

Get the line number where the last CPL error occurred.

Returns:
Line number of the source file where the last CPL error occurred.
Get the line number of the source file where the last CPL error occurred. If the macro __LINE__ is undefined 0 is returned.

const char* cpl_error_get_message void   ) 
 

Get standard message of last occurred CPL error.

Returns:
Standard message of last occurred CPL error.
Get current standard error message. If the cpl_error_code is equal to CPL_ERROR_NONE, an empty string is returned.

const char* cpl_error_get_where void   ) 
 

Get function name, source file and line number where the last CPL error occurred.

Returns:
String containing function name, source file and line number separated by colons (:).
Get where the last CPL error occurred in the form function_name:source_file:line_number

void cpl_error_reset void   ) 
 

Reset the cpl_error_code.

Returns:
Nothing.
This function initialises the cpl_error_code to CPL_ERROR_NONE.

cpl_error_code cpl_error_set_code cpl_error_code  code  ) 
 

Set the cpl_error_code to the specified value.

Parameters:
code A cpl_error_code
Returns:
The specified cpl_error_code.
Set the cpl_error_code to the specified code.


Generated on Mon Sep 26 14:38:17 2005 for Common Pipeline Library Reference Manual by  doxygen 1.4.1