## bonobo-exception bonobo-exception — maps CORBA exceptions to user readable text, + helper macros |

## Synopsis

    #define             bonobo_exception_set                (opt_ev,repo_id)
    #define             bonobo_return_if_fail               (expr,opt_ev)
    #define             bonobo_return_val_if_fail           (expr,val,opt_ev)
    #define             BONOBO_EX                           (ev)
    #define             BONOBO_USER_EX                      (ev,id)
    #define             BONOBO_EX_REPOID                    (ev)
    #define             BONOBO_RET_EX                       (ev)
    #define             BONOBO_RET_VAL_EX                   (ev,v)
    char*               (*BonoboExceptionFn)                (CORBA_Environment *ev,
                                                             gpointer user_data);
    char*               bonobo_exception_get_text           (CORBA_Environment *ev);
    char*               bonobo_exception_repoid_to_text     (const char *repo_id);
    void                bonobo_exception_add_handler_str    (const char *repo_id,
                                                             const char *str);
    void                bonobo_exception_add_handler_fn     (const char *repo_id,
                                                             BonoboExceptionFn fn,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy_fn);
    void                bonobo_exception_general_error_set  (CORBA_Environment *ev,
                                                             CORBA_TypeCode opt_deriv,
                                                             const char *format,
                                                             ...);
    const char*         bonobo_exception_general_error_get  (CORBA_Environment *ev);

## Description

This module contains some useful helper functions that can be used to set various exceptions inside your CORBA methods. It also contains code to map between complex CORBA_Environment exceptions and helpful strings suitable for display to the user.

Typically to test for exceptions the BONOBO_EX macro is used thus:

Example 4. Bonobo exception trapping and reporting

    int
    do_something (CORBA_Environment *ev)
    {
    	...

    	retval = Foo_Baa_method (object, ev);

    	if (BONOBO_EX (ev)) {
    		if (BONOBO_USER_EX (ev, ex_CosNaming_NamingContext_NotFound)) {
    		        g_warning ("Not found");
    		} else {
    		        char *str;

    			g_warning ("Exception '%s' occured",
    				(str = bonobo_exception_get_text (ev)));
    			g_free (str);
    		}
    		return -1;
    	}
    	...
    }

## Details

### bonobo_exception_set()

    #define             bonobo_exception_set(opt_ev,repo_id)

This macro sets the stateless user exception with `repo_id` on `opt_ev` or warns if `opt_ev` == NULL

`opt_ev` : | an optional corba exception environment.
`repo_id` : | repoid of the exception to set.

### bonobo_return_if_fail()

    #define             bonobo_return_if_fail(expr,opt_ev)

this macro is used for bonobo preconditons on argument types, usualy inside skels if `expr` is FALSE a warning is printed and `opt_ev` is set to ex_Bonobo_BadArg.

`expr` : | an expression that should be true
`opt_ev` : | an optional corba exception environment.

### bonobo_return_val_if_fail()

    #define             bonobo_return_val_if_fail(expr,val,opt_ev)

this macro is used for bonobo preconditons on argument types, usualy inside skels if `expr` is FALSE a warning is printed and `opt_ev` is set to ex_Bonobo_BadArg.

`expr` : | an expression that should be true
`val` : | a value to return on failure.
`opt_ev` : | an optional corba exception environment.

### BONOBO_EX()

    #define BONOBO_EX(ev)         ((ev) && (ev)->_major != CORBA_NO_EXCEPTION)

This macro returns TRUE if `ev` flags an exception.

`ev` : | the exception environment

### BONOBO_USER_EX()

    #define             BONOBO_USER_EX(ev,id)

This macro returns TRUE if `ev` contains a user exception of type `id`.

`ev` : | the exception environment
`id` : | the repo_id of the exception

### BONOBO_EX_REPOID()

    #define BONOBO_EX_REPOID(ev)  (ev)->_id

Returns the repoid string of exception `ev`.

`ev` : | a CORBA exception

### BONOBO_RET_EX()

    #define             BONOBO_RET_EX(ev)

returns if there is an exception flagged in `ev`.

`ev` : | the exception environment

### BONOBO_RET_VAL_EX()

    #define             BONOBO_RET_VAL_EX(ev,v)

returns `v` if there is an exception flagged in `ev`

`ev` : | the exception environment
`v` : | the value to return

### BonoboExceptionFn ()

    char*               (*BonoboExceptionFn)                (CORBA_Environment *ev,
                                                             gpointer user_data);

The prototype for user registerable exception decoders.

`ev` : | the exception environment
`user_data` : | user data to be passed to the function
Returns : | a g_malloc'd copy of a translated user readable error string.

### bonobo_exception_get_text ()

    char*               bonobo_exception_get_text           (CORBA_Environment *ev);

Returns a user readable description of the exception. First checks `ev` against builtin Bonobo exceptions, then falls back to exception names added through bonobo_exception_add_handler_str or bonobo_exception_add_handler_fn.

`ev` : | the corba environment.
Returns : | A g_malloc'd description, which the caller must free. NULL is never returned.

### bonobo_exception_repoid_to_text ()

    char*               bonobo_exception_repoid_to_text     (const char *repo_id);

This maps builtin bonobo exceptions that the system knows about to user readable strings.

`repo_id` : | exception repository id
Returns : | a user string or NULL for an unknown repo_id

### bonobo_exception_add_handler_str ()

    void                bonobo_exception_add_handler_str    (const char *repo_id,
                                                             const char *str);

This routine adds a simple string mapping for an exception with repository id `repo_id`, such that when we call bonobo_exception_get_text on an exception of id `repo_id` we get `str` back.

`repo_id` : | exception repository id
`str` : | the user readable, translated exception text.

### bonobo_exception_add_handler_fn ()

    void                bonobo_exception_add_handler_fn     (const char *repo_id,
                                                             BonoboExceptionFn fn,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy_fn);

This routine adds a method mapping for an exception with repository id `repo_id`, such that when we call bonobo_exception_get_text on an exception of id `repo_id` the `fn` is called and passed `user_data`. When the handler is removed the `destroy_fn` is called on its `user_data`.

`repo_id` : | exception repository id
`fn` : | function to make exception human readable
`user_data` : | the user data
`destroy_fn` : | user data destroy function or NULL.

### bonobo_exception_general_error_set ()

    void                bonobo_exception_general_error_set  (CORBA_Environment *ev,
                                                             CORBA_TypeCode opt_deriv,
                                                             const char *format,
                                                             ...);

`ev` : |
`opt_deriv` : |
`format` : |
`...` : |

### bonobo_exception_general_error_get ()

    const char*         bonobo_exception_general_error_get  (CORBA_Environment *ev);

`ev` : |
Returns : |