clipm_priv_error.h File Reference

#include <cpl.h>
#include <string.h>

Go to the source code of this file.

Functions
void	_clipm_priv_error_sprint_messages (char *outstr, const char *msg1, const char *msg2, size_t maxlen)
#define	_CLIPM_ERROR_SET_WHERE_()
#define	_CLIPM_ERROR_SET_MSG_(code, object, msg)
#define	CLIPM_TRY
	Beginning of a TRY-block.
#define	CLIPM_CATCH
	End of a TRY-block, beginning of a CATCH-block.
#define	CLIPM_ERROR_GET_NEW_SINCE_TRY(void)
	Return new CPL error code.
#define	CLIPM_ERROR_RECOVER_TRYSTATE(void)
	Recover the error state which was present during CLIPM_TRY (at the beginning of the try-block).
#define	CLIPM_ERROR_SET(code)
	Set a new error code.
#define	CLIPM_ERROR_SET_MSG(code, object, msg)
	Set a new error code together with a custom error message.
#define	CLIPM_ERROR_SET_MSG_IF_CODE(code, object, msg)
	Set a new custom error message if a certain error code is already set.
#define	CLIPM_ERROR_IS_SET(void)
	Return if a new CPL error is set.
#define	CLIPM_ERROR_IS_NONE(void)
	Return if no new CPL error is set.
#define	CLIPM_TRY_CHECK(condition, code, object, msg)
	Assure the condition is true, else set the respective error code, exit the TRY block, and set an error message using the object name (can be empty string) and a message.
#define	CLIPM_TRY_CHECK_AUTOMSG(condition, code)
	Assure the condition is true, else set the respective error code, exit the TRY block, and auto-generate an error message (re-using the condition).
#define	CLIPM_TRY_CHECK_ERROR_STATE(void)
	Check the CPL error state, and exit the try-block if not CPL_ERROR_NONE.
#define	CLIPM_TRY_ASSERT(condition)
	Assert that the given condition is fulfilled, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED.
#define	CLIPM_TRY_ASSERT_ERROR_STATE(void)
	Assert that the CPL error state is CPL_ERROR_NONE, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED.
#define	CLIPM_TRY_EXIT_WITH_ERROR(code)
	Set a new CPL error, and exit the try-block.
#define	CLIPM_TRY_EXIT_WITH_ERROR_MSG(code, object, msg)
	Set a new CPL error together with a custom error message, and exit the try-block.
#define	CLIPM_TRY_EXIT_IFN(condition)
	If condition == 0, then the try-block is exited.
#define	CLIPM_TRY_EXIT(void)
	The try-block is exited.
enum	_clipm_error_code_ { CLIPM_ERROR_UNEXPECTED = CPL_ERROR_EOL + 0 }
	Extension to CPL error codes. More...
typedef enum _clipm_error_code_	clipm_error_code
	Extension to CPL error codes.
const char	_CLIPM_MSG_ERR_UNEXPECTED []
	Internal error.
const char	_CLIPM_MSG_ERR_HANDLING []
	Internal error handling bug.
const char	CLIPM_MSG_ERR_2ROWXY []
	Location matrix must contain 2 rows.
const char	CLIPM_MSG_ERR_DIFFSIZES []
	Location matrices differ in size.
const char	CLIPM_MSG_ERR_DIFFTYPES []
	Location matrices differ in size.

Macro Definition Documentation

_CLIPM_ERROR_SET_MSG_

#define _CLIPM_ERROR_SET_MSG_	(		code,
			object,
			msg )

Value:

do { \
    char _clipm_error_msg[256]; \
    _clipm_priv_error_sprint_messages(      _clipm_error_msg, \
                                            object, \
                                            msg, \
                                            255); \
    cpl_error_set_message(                  __func__, \
                                            code, \
                                            "%s", _clipm_error_msg); \
    clipm_error_is_set_where = 1; \
} while (0)

_CLIPM_ERROR_SET_WHERE_

#define _CLIPM_ERROR_SET_WHERE_

(

)

Value:

do { \
    if (CLIPM_ERROR_IS_SET()) \
    { \
        const char      *_msg; \
        int             _n = 0; \
        \
        _msg = cpl_error_get_message(); \
        /* search the beginning of the last custom message */ \
        while (_msg[_n] != '\0' && _msg[_n] != ':') \
            _n++; \
        while (_msg[_n] == ':' || _msg[_n] == ' ') \
            _n++; \
        cpl_error_set_message(              __func__, \
                                            cpl_error_get_code(), \
                                            "%s", _msg+_n); \
        clipm_error_is_set_where = 1; \
    } \
} while (0)

CLIPM_CATCH

#define CLIPM_CATCH

End of a TRY-block, beginning of a CATCH-block.

Please refer to CLIPM_TRY.

CLIPM_ERROR_GET_NEW_SINCE_TRY

#define CLIPM_ERROR_GET_NEW_SINCE_TRY

(

void

)

Return new CPL error code.

Returns

If the CPL error state has changed since CLIPM_TRY, the latest error code is returned, otherwise CPL_ERROR_NONE.

• May be called outside TRY-block.

CLIPM_ERROR_IS_NONE

#define CLIPM_ERROR_IS_NONE

(

void

)

Return if no new CPL error is set.

Returns

If the CPL error state has changed since CLIPM_TRY, 0 returned, otherwise 1.

• May be called outside TRY-block.

CLIPM_ERROR_IS_SET

#define CLIPM_ERROR_IS_SET

(

void

)

Return if a new CPL error is set.

Returns

If the CPL error state has changed since CLIPM_TRY, 1 returned, otherwise 0.

• May be called outside TRY-block.

CLIPM_ERROR_RECOVER_TRYSTATE

#define CLIPM_ERROR_RECOVER_TRYSTATE

(

void

)

Recover the error state which was present during CLIPM_TRY (at the beginning of the try-block).

• May be called outside TRY-block.

CLIPM_ERROR_SET

#define CLIPM_ERROR_SET

(

code

)

Set a new error code.

• code must not be CPL_ERROR_NONE.
• May be called outside TRY-block.

CLIPM_ERROR_SET_MSG

#define CLIPM_ERROR_SET_MSG	(		code,
			object,
			msg )

Set a new error code together with a custom error message.

• code must not be CPL_ERROR_NONE.
• May be called outside TRY-block.

CLIPM_ERROR_SET_MSG_IF_CODE

#define CLIPM_ERROR_SET_MSG_IF_CODE	(		code,
			object,
			msg )

Set a new custom error message if a certain error code is already set.

• code must not be CPL_ERROR_NONE.
• May be called outside TRY-block.

CLIPM_TRY

#define CLIPM_TRY

Beginning of a TRY-block.

The macro CLIPM_TRY is to be used like a keyword in front of a deeper scope. This scope has to be followed by the macro CLIPM_CATCH. This means that CLIPM_TRY and CLIPM_CATCH build a frame around a code statement or a code scope, called the try-block.

The CLIPM_CATCH macro is to be followed by a statement or scope, which is only executed if a CPL error is set while reaching the CLIPM_CATCH macro, called the catch-block.

The try-block can be exited by using one of the macros below, for example with CLIPM_TRY_EXIT_WITH_ERROR(). In this case, a jump to CLIPM_CATCH is performed, and the catch-block executed if an error is set.

Note

The following constraints have to be fulfilled:

• A "return" or "goto" statement inside the try-block is forbidden, because leaving the try-block without processing the CLIPM_CATCH macro will mess up the error state information. In the catch-block (which comes after the CLIPM_CATCH macro), it is allowed.
• The macros require some variables, which are declared at the beginning of the CLIPM_TRY macro. Therefore it is not possible in ANSI-C to have code statements (except declarations) before the CLIPM_TRY macro. If it is required, this can be solved by putting a scope around the try-catch construct.
• Only one CLIPM_TRY - CLIPM_CATCH - construct can be inside one function.

Example 1:

cpl_error_code my_func()
{
    cpl_object      *obj = NULL;
    
    CLIPM_TRY
    {
        CLIPM_TRY_EXIT_IFN(
            obj = cpl_object_new());
        
        CLIPM_TRY_EXIT_IFN(
            cpl_function(obj) == CPL_ERROR_NONE);
        
        cpl_function(obj);
        CLIPM_TRY_CHECK_ERROR_STATE();
    }
    CLIPM_CATCH
    {
    }
 
    cpl_object_delete(obj);
    
    return CLIPM_ERROR_GET_NEW_SINCE_TRY;
}

Example 2:

cpl_object  *my_func()
{
    cpl_object      *obj = NULL;
    
    CLIPM_TRY
    {
        CLIPM_TRY_EXIT_IFN(
            obj = cpl_object_new());
        
        CLIPM_TRY_EXIT_IFN(
            cpl_function(obj) == CPL_ERROR_NONE);
        
        cpl_function(obj);
        CLIPM_TRY_CHECK_ERROR_STATE();
    }
    CLIPM_CATCH
    {
        cpl_object_delete(obj);
        obj = NULL;
    }
    
    return obj;
}

CLIPM_TRY_ASSERT

#define CLIPM_TRY_ASSERT

(

condition

)

Assert that the given condition is fulfilled, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED.

• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_ASSERT_ERROR_STATE

#define CLIPM_TRY_ASSERT_ERROR_STATE

(

void

)

Assert that the CPL error state is CPL_ERROR_NONE, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED.

• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_CHECK

#define CLIPM_TRY_CHECK	(		condition,
			code,
			object,
			msg )

Assure the condition is true, else set the respective error code, exit the TRY block, and set an error message using the object name (can be empty string) and a message.

Parameters

condition	Condition
code	Error code to be set
object	Object name (can be empty or NULL)
msg	Message (can be empty or NULL)

• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_CHECK_AUTOMSG

#define CLIPM_TRY_CHECK_AUTOMSG	(		condition,
			code )

Assure the condition is true, else set the respective error code, exit the TRY block, and auto-generate an error message (re-using the condition).

Parameters

condition	Condition
code	Error code to be set

• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_CHECK_ERROR_STATE

#define CLIPM_TRY_CHECK_ERROR_STATE

(

void

)

Check the CPL error state, and exit the try-block if not CPL_ERROR_NONE.

• Does not overwrite locally set messages.
• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_EXIT

#define CLIPM_TRY_EXIT

(

void

)

The try-block is exited.

• It is not necessary that a new error state is already set. In this case, the try-block is just exited.
• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_EXIT_IFN

#define CLIPM_TRY_EXIT_IFN

(

condition

)

If condition == 0, then the try-block is exited.

• It is assumed, that a new error state is already set if condition is 0, otherwise a custom bugreport message is set and the TRY-block is exited with error code CLIPM_ERROR_UNEXPECTED. If it is desired to instead eventually set an error here, consider using CLIPM_TRY_CHECK[_AUTOMSG] instead.
• Does not overwrite locally set messages.
• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_EXIT_WITH_ERROR

#define CLIPM_TRY_EXIT_WITH_ERROR

(

code

)

Set a new CPL error, and exit the try-block.

• code must not be CPL_ERROR_NONE!
• Only allowed in TRY-block, forbidden in CATCH-block!

CLIPM_TRY_EXIT_WITH_ERROR_MSG

#define CLIPM_TRY_EXIT_WITH_ERROR_MSG	(		code,
			object,
			msg )

Set a new CPL error together with a custom error message, and exit the try-block.

• code must not be CPL_ERROR_NONE!
• Overwrites any message!
• Only allowed in TRY-block, forbidden in CATCH-block!

Typedef Documentation

clipm_error_code

typedef enum _clipm_error_code_ clipm_error_code

Extension to CPL error codes.

Enumeration Type Documentation

_clipm_error_code_

enum _clipm_error_code_

Extension to CPL error codes.

Enumerator
CLIPM_ERROR_UNEXPECTED	Unexpected internal error

Function Documentation

_clipm_priv_error_sprint_messages()

void _clipm_priv_error_sprint_messages	(	char *	outstr,
		const char *	msg1,
		const char *	msg2,
		size_t	maxlen )

Variable Documentation

_CLIPM_MSG_ERR_HANDLING

const char _CLIPM_MSG_ERR_HANDLING[]

extern

Internal error handling bug.

_CLIPM_MSG_ERR_UNEXPECTED

const char _CLIPM_MSG_ERR_UNEXPECTED[]

extern

Internal error.

CLIPM_MSG_ERR_2ROWXY

const char CLIPM_MSG_ERR_2ROWXY[]

extern

Location matrix must contain 2 rows.

CLIPM_MSG_ERR_DIFFSIZES

const char CLIPM_MSG_ERR_DIFFSIZES[]

extern

Location matrices differ in size.

CLIPM_MSG_ERR_DIFFTYPES

const char CLIPM_MSG_ERR_DIFFTYPES[]

extern

Location matrices differ in size.