## 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);

Returns : |

### 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);

`ex` : |
`id` : |
`desc` : |

### camel_exception_setv ()

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

`ex` : |
`id` : |
`format` : |
`...` : |

### 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` : |