camel-exception

## 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 gchar *desc);
    void                camel_exception_setv                (CamelException *ex,
                                                             ExceptionId id,
                                                             const gchar *format,
                                                             ...);
    void                camel_exception_xfer                (CamelException *ex_dst,
                                                             CamelException *ex_src);
    ExceptionId         camel_exception_get_id              (CamelException *ex);
    const gchar *       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;
    	gchar *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 gchar *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 gchar *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 gchar *       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` : |