camel-exception

camel-exception —

Synopsis




enum        ExceptionId;
struct      CamelException;
#define     CAMEL_EXCEPTION_INITIALISER
CamelException* camel_exception_new         (void);
void        camel_exception_free            (CamelException *ex);
void        camel_exception_init            (CamelException *ex);
void        camel_exception_clear           (CamelException *ex);
void        camel_exception_set             (CamelException *ex,
                                             ExceptionId id,
                                             const char *desc);
void        camel_exception_setv            (CamelException *ex,
                                             ExceptionId id,
                                             const char *format,
                                             ...);
void        camel_exception_xfer            (CamelException *ex_dst,
                                             CamelException *ex_src);
ExceptionId camel_exception_get_id          (CamelException *ex);
const char* camel_exception_get_description (CamelException *ex);
#define     camel_exception_is_set          (ex)

Description

Details

enum ExceptionId

typedef enum {
#include "camel-exception-list.def"

} ExceptionId;


struct CamelException

struct CamelException {
	/* do not access the fields directly */
	ExceptionId id;
	char *desc;
};


CAMEL_EXCEPTION_INITIALISER

#define CAMEL_EXCEPTION_INITIALISER { 0, NULL }


camel_exception_new ()

CamelException* camel_exception_new         (void);

Create and returns a new exception object.

Returns : the newly allocated exception object

camel_exception_free ()

void        camel_exception_free            (CamelException *ex);

Free an exception object. If the exception is NULL, nothing is done, the routine simply returns.

ex : a CamelException

camel_exception_init ()

void        camel_exception_init            (CamelException *ex);

Init an exception. This routine is mainly useful when using a statically allocated exception.

ex : a CamelException

camel_exception_clear ()

void        camel_exception_clear           (CamelException *ex);

Clear an exception, that is, set the exception ID to CAMEL_EXCEPTION_NONE and free the description text. If the exception is NULL, this funtion just returns.

ex : a CamelException

camel_exception_set ()

void        camel_exception_set             (CamelException *ex,
                                             ExceptionId id,
                                             const char *desc);

Set the value of an exception. The exception id is a unique number representing the exception. The textual description is a small text explaining what happened and provoked the exception.

When ex is NULL, nothing is done, this routine simply returns.

ex : a CamelException
id : exception id
desc : textual description of the exception

camel_exception_setv ()

void        camel_exception_setv            (CamelException *ex,
                                             ExceptionId id,
                                             const char *format,
                                             ...);

Set the value of an exception. The exception id is a unique number representing the exception. The textual description is a small text explaining what happened and provoked the exception. In this version, the string is created from the format string and the variable argument list.

It is safe to say: camel_exception_setv (ex, ..., camel_exception_get_description (ex), ...);

When ex is NULL, nothing is done, this routine simply returns.

ex : a CamelException
id : exception id
format : format of the description string. The format string is used as in printf().
... :

camel_exception_xfer ()

void        camel_exception_xfer            (CamelException *ex_dst,
                                             CamelException *ex_src);

Transfer the content of an exception from an exception object to another. The destination exception receives the id and the description text of the source exception.

ex_dst : Destination exception object
ex_src : Source exception object

camel_exception_get_id ()

ExceptionId camel_exception_get_id          (CamelException *ex);

Get the id of an exception.

ex : a CamelException
Returns : the exception id (CAMEL_EXCEPTION_NONE will be returned if ex is NULL or unset)

camel_exception_get_description ()

const char* camel_exception_get_description (CamelException *ex);

Get the exception description text.

ex : a CamelException
Returns : the exception description text (NULL will be returned if ex is NULL or unset)

camel_exception_is_set()

#define camel_exception_is_set(ex) (camel_exception_get_id (ex) != CAMEL_EXCEPTION_NONE)

ex :