manpagez: man pages & more
html files: libbonobo
Home | html | info | man

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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) != NULL && (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 :

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.