bonobo-exception: Libbonobo Reference Manual

bonobo-exception

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

Functions

#define	bonobo_exception_set()
#define	bonobo_return_if_fail()
#define	bonobo_return_val_if_fail()
#define	BONOBO_EX()
#define	BONOBO_USER_EX()
#define	BONOBO_EX_REPOID()
#define	BONOBO_RET_EX()
#define	BONOBO_RET_VAL_EX()
char *	(*BonoboExceptionFn) ()
char *	bonobo_exception_get_text ()
char *	bonobo_exception_repoid_to_text ()
void	bonobo_exception_add_handler_str ()
void	bonobo_exception_add_handler_fn ()
void	bonobo_exception_general_error_set ()
const char *	bonobo_exception_general_error_get ()

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;
	}
	...
}

Functions

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

Parameters

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.

Parameters

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.

Parameters

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) != NULL && (ev)->_major != CORBA_NO_EXCEPTION)

This macro returns TRUE if ev flags an exception.

Parameters

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.

Parameters

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.

Parameters

a CORBA exception

BONOBO_RET_EX()

#define             BONOBO_RET_EX(ev)

returns if there is an exception flagged in ev.

Parameters

the exception environment

BONOBO_RET_VAL_EX()

#define             BONOBO_RET_VAL_EX(ev,v)

returns v if there is an exception flagged in ev

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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,
                                    ...);

bonobo_exception_general_error_get ()

const char *
bonobo_exception_general_error_get (CORBA_Environment *ev);