cpl_error.h File Reference

#include "cpl_port.h"

Go to the source code of this file.

Defines
#define	CPLAssert(expr)
#define	VALIDATE_POINTER_ERR   CE_Failure
#define	VALIDATE_POINTER0(ptr, func)
#define	VALIDATE_POINTER1(ptr, func, rc)
#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
#define	CPLE_ObjectNull   10
Typedefs
typedef const char *void	CPLLoggingErrorHandler (CPLErr, int, const char *)
Enumerations
enum	CPLErr {   CE_None = 0, CE_Debug = 1, CE_Warning = 2, CE_Failure = 3,   CE_Fatal = 4 }
Functions
void	CPLError (CPLErr eErrClass, int err_no, const char *fmt,...) CPL_PRINT_FUNC_FORMAT(3
void void	CPLErrorV (CPLErr, int, const char *, va_list)
void	CPLErrorReset (void)
int	CPLGetLastErrorNo (void)
CPLErr	CPLGetLastErrorType (void)
const char *	CPLGetLastErrorMsg (void)
typedef	void (1 *CPLErrorHandler)(CPLErr
void	CPLDefaultErrorHandler (CPLErr, int, const char *)
void	CPLQuietErrorHandler (CPLErr, int, const char *)
CPLErrorHandler	CPLSetErrorHandler (CPLErrorHandler)
void	CPLPushErrorHandler (CPLErrorHandler)
void	CPLPopErrorHandler (void)
void	CPLDebug (const char *, const char *,...) CPL_PRINT_FUNC_FORMAT(2
void void	_CPLAssert (const char *, const char *, int)
Variables
typedef	int

---

Detailed Description

CPL error handling services.

---

Define Documentation

#define VALIDATE_POINTER0	(	ptr,
		func		)

Value:

do { if( NULL == ptr ) \
      { \
        CPLErr const ret = VALIDATE_POINTER_ERR; \
        CPLError( ret, CPLE_ObjectNull, \
           "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
         return; }} while(0)

#define VALIDATE_POINTER1	(	ptr,
		func,
		rc		)

Value:

do { if( NULL == ptr ) \
      { \
          CPLErr const ret = VALIDATE_POINTER_ERR; \
          CPLError( ret, CPLE_ObjectNull, \
           "Pointer \'%s\' is NULL in \'%s\'.\n", #ptr, (func)); \
        return (rc); }} while(0)

---

Function Documentation

void void _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.

void CPLErrorReset

(

void

)

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* CPLGetLastErrorMsg

(

void

)

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 CPLGetLastErrorNo

(

void

)

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.

CPLErr CPLGetLastErrorType

(

void

)

Fetch the last error type.

This is the error class, not the error number.

Returns:

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

void CPLPopErrorHandler

(

void

)

Pop error handler off stack.

Discards the current error handler on the error handler stack, and restores the one in use before the last CPLPushErrorHandler() call. This method has no effect if there are no error handlers on the current threads error handler stack.

void CPLPushErrorHandler

(

CPLErrorHandler

pfnErrorHandlerNew

)

Push a new CPLError handler.

This pushes a new error handler on the thread-local error handler stack. This handler will be used untill removed with CPLPopErrorHandler().

The CPLSetErrorHandler() docs have further information on how CPLError handlers work.

Parameters:

pfnErrorHandlerNew

new error handler function.

CPLErrorHandler CPLSetErrorHandler

(

CPLErrorHandler

pfnErrorHandlerNew

)

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 err_no, 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.

Note that error handlers set with CPLSetErrorHandler() apply to all threads in an application, while error handlers set with CPLPushErrorHandler are thread-local. However, any error handlers pushed with CPLPushErrorHandler (and not removed with CPLPopErrorHandler) take precidence over the global error handlers set with CPLSetErrorHandler(). Generally speaking CPLSetErrorHandler() would be used to set a desired global error handler, while CPLPushErrorHandler() would be used to install a temporary local error handler, such as CPLQuietErrorHandler() to suppress error reporting in a limited segment of code.

Parameters:

pfnErrorHandlerNew

new error handler function.

Returns:

returns the previously installed error handler.