bonobo-exception

Bonobo API Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

bonobo-exception

Name

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

Synopsis



#define     BONOBO_EX                       (ev)
#define     BONOBO_USER_EX                  (ev,id)
#define     BONOBO_RET_EX                   (ev)
#define     BONOBO_RET_VAL_EX               (ev,v)
char*       (*BonoboExceptionFn)            (CORBA_Environment *ev,
                                             gpointer user_data);
#define     bonobo_return_if_fail           (expr,opt_ev)
#define     bonobo_return_val_if_fail       (expr,val,opt_ev)
#define     bonobo_exception_set            (opt_ev,repo_id)
char*       bonobo_exception_get_text       (CORBA_Environment *ev);
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);
char*       bonobo_exception_repoid_to_text (const char *repo_id);

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_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_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_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_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_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_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_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

<<< Previous Page	Home	Up	Next Page >>>
BonoboGenericFactory		Properties