camel-exception
3
CAMEL Library

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