Name
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 1. 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
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.
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.
BONOBO_EX()
| #define BONOBO_EX(ev)         ((ev) && (ev)->_major != CORBA_NO_EXCEPTION) | 
This macro returns TRUE if ev flags an exception.
BONOBO_USER_EX()
| #define     BONOBO_USER_EX(ev,id) | 
This macro returns TRUE if ev contains a user exception
of type id.
BONOBO_EX_REPOID()
| #define BONOBO_EX_REPOID(ev)  (ev)->_id | 
BONOBO_RET_EX()
| #define     BONOBO_RET_EX(ev) | 
returns if there is an exception flagged in ev.
BONOBO_RET_VAL_EX()
| #define     BONOBO_RET_VAL_EX(ev,v) | 
returns v if there is an exception flagged in ev
BonoboExceptionFn ()
| char*       (*BonoboExceptionFn)            (CORBA_Environment *ev,
                                             gpointer user_data); | 
The prototype for user registerable exception decoders.
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.
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.
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.
bonobo_exception_add_handler_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.
bonobo_exception_general_error_set ()
| void        bonobo_exception_general_error_set
                                            (CORBA_Environment *ev,
                                             CORBA_TypeCode opt_deriv,
                                             const char *format,
                                             ...); | 
bonobo_exception_general_error_get ()
| const char* bonobo_exception_general_error_get
                                            (CORBA_Environment *ev); |