|  |  |  | Libbonobo Reference Manual |  | 
|---|---|---|---|---|
#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);
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;
	}
	...
}
     
#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. | 
#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. | 
#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. | 
#define BONOBO_EX(ev) ((ev) && (ev)->_major != CORBA_NO_EXCEPTION)
This macro returns TRUE if ev flags an exception.
| ev: | the exception environment | 
#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 | 
#define BONOBO_EX_REPOID(ev) (ev)->_id
Returns the repoid string of exception ev.
| ev: | a CORBA exception | 
#define BONOBO_RET_EX(ev)
returns if there is an exception flagged in ev.
| ev: | the exception environment | 
#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 | 
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. | 
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. | 
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 | 
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. | 
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. | 
void        bonobo_exception_general_error_set
                                            (CORBA_Environment *ev,
                                             CORBA_TypeCode opt_deriv,
                                             const char *format,
                                             ...);
| ev: | |
| opt_deriv: | |
| format: | |
| ...: |