Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members   Related Pages  

cpl_error.h File Reference

#include "cpl_port.h"

Go to the source code of this file.

Defines

#define CPLAssert(expr)
#define CPLE_None   0
#define CPLE_AppDefined   1
#define CPLE_OutOfMemory   2
#define CPLE_FileIO   3
#define CPLE_OpenFailed   4
#define CPLE_IllegalArg   5
#define CPLE_NotSupported   6
#define CPLE_AssertionFailed   7
#define CPLE_NoWriteAccess   8
#define CPLE_UserInterrupt   9

Typedefs

typedef void (* CPLErrorHandler )(CPLErr, int, const char*)

Enumerations

enum  CPLErr {
  CE_None = 0, CE_Debug = 1, CE_Warning = 2, CE_Failure = 3,
  CE_Fatal = 4
}

Functions

void CPL_DLL CPLError (CPLErr eErrClass, int err_no, const char *fmt, ...)
void CPL_DLL CPLErrorV (CPLErr, int, const char *, va_list )
void CPL_DLL CPLErrorReset ()
int CPL_DLL CPLGetLastErrorNo ()
const char CPL_DLL* CPLGetLastErrorMsg ()
CPLErrorHandler CPL_DLL CPLSetErrorHandler (CPLErrorHandler)
void CPL_DLL CPLPushErrorHandler ( CPLErrorHandler )
void CPL_DLL CPLPopErrorHandler ()
void CPL_DLL CPLDefaultErrorHandler ( CPLErr, int, const char * )
void CPL_DLL CPLQuietErrorHandler ( CPLErr, int, const char * )
void CPL_DLL CPLDebug ( const char *, const char *, ... )
void CPL_DLL _CPLAssert ( const char *, const char *, int )


Detailed Description

CPL error handling services.


Function Documentation

void CPL_DLL CPLDebug ( const char * pszCategory,
const char * pszFormat,
... )
 

Display a debugging message.

The category argument is used in conjunction with the CPL_DEBUG environment variable to establish if the message should be displayed. If the CPL_DEBUG environment variable is not set, no debug messages are emitted (use CPLError(CE_Warning,...) to ensure messages are displayed). If CPL_DEBUG is set, but is an empty string or the word "ON" then all debug messages are shown. Otherwise only messages whose category appears somewhere within the CPL_DEBUG value are displayed (as determinted by strstr()).

Categories are usually an identifier for the subsystem producing the error. For instance "GDAL" might be used for the GDAL core, and "TIFF" for messages from the TIFF translator.

Parameters:
pszCategory   name of the debugging message category.
pszFormat   printf() style format string for message to display. Remaining arguments are assumed to be for format.

void CPL_DLL CPLError ( CPLErr eErrClass,
int err_no,
const char * fmt,
... )
 

Report an error.

This function reports an error in a manner that can be hooked and reported appropriate by different applications.

The effect of this function can be altered by applications by installing a custom error handling using CPLSetErrorHandler().

The eErrClass argument can have the value CE_Warning indicating that the message is an informational warning, CE_Failure indicating that the action failed, but that normal recover mechanisms will be used or CE_Fatal meaning that a fatal error has occured, and that CPLError() should not return.

The default behaviour of CPLError() is to report errors to stderr, and to abort() after reporting a CE_Fatal error. It is expected that some applications will want to supress error reporting, and will want to install a C++ exception, or longjmp() approach to no local fatal error recovery.

Regardless of how application error handlers or the default error handler choose to handle an error, the error number, and message will be stored for recovery with CPLGetLastErrorNo() and CPLGetLastErrorMsg().

Parameters:
eErrClass   one of CE_Warning, CE_Failure or CE_Fatal.
err_no   the error number (CPLE_*) from cpl_error.h.
fmt   a printf() style format string. Any additional arguments will be treated as arguments to fill in this format in a manner similar to printf().

void CPL_DLL CPLErrorReset ( )
 

Erase any traces of previous errors.

This is normally used to ensure that an error which has been recovered from does not appear to be still in play with high level functions.

const char CPL_DLL* CPLGetLastErrorMsg ( )
 

Get the last error message.

Fetches the last error message posted with CPLError(), that hasn't been cleared by CPLErrorReset(). The returned pointer is to an internal string that should not be altered or freed.

Returns:
the last error message, or NULL if there is no posted error message.

int CPL_DLL CPLGetLastErrorNo ( )
 

Fetch the last error number.

This is the error number, not the error class.

Returns:
the error number of the last error to occur, or CPLE_None (0) if there are no posted errors.

void CPL_DLL CPLPopErrorHandler ( )
 

Restore old CPLError handler.

Discards the current error handler, and restore the one in use before the last CPLPushErrorHandler() call.

void CPL_DLL CPLPushErrorHandler ( CPLErrorHandler pfnErrorHandler )
 

Assign new CPLError handler.

The old handler is "pushed down" onto a stack and can be easily restored with CPLPopErrorHandler(). Otherwise this works similarly to CPLSetErrorHandler() which contains more details on how error handlers work.

Parameters:
pfnErrorHandler   new error handler function.

CPLErrorHandler CPL_DLL CPLSetErrorHandler ( CPLErrorHandler pfnErrorHandler )
 

Install custom error handler.

Allow the library's user to specify his own error handler function. A valid error handler is a C function with the following prototype:

     void MyErrorHandler(CPLErr eErrClass, int errno, const char *msg)
 

Pass NULL to come back to the default behavior. The default behaviour (CPLDefaultErrorHandler()) is to write the message to stderr.

The msg will be a partially formatted error message not containing the "ERROR d:" portion emitted by the default handler. Message formatting is handled by CPLError() before calling the handler. If the error handler function is passed a CE_Fatal class error and returns, then CPLError() will call abort(). Applications wanting to interrupt this fatal behaviour will have to use longjmp(), or a C++ exception to indirectly exit the function.

Another standard error handler is CPLQuietErrorHandler() which doesn't make any attempt to report the passed error or warning messages but will process debug messages via CPLDefaultErrorHandler.

Parameters:
pfnErrorHandler   new error handler function.
Returns:
returns the previously installed error handler.

void CPL_DLL _CPLAssert ( const char * pszExpression,
const char * pszFile,
int iLine )
 

Report failure of a logical assertion.

Applications would normally use the CPLAssert() macro which expands into code calling _CPLAssert() only if the condition fails. _CPLAssert() will generate a CE_Fatal error call to CPLError(), indicating the file name, and line number of the failed assertion, as well as containing the assertion itself.

There is no reason for application code to call _CPLAssert() directly.


doxygen1.2.3-20001105 Dimitri van Heesch, © 1997-2000