bonobo-moniker-util

bonobo-moniker-util — Object activation and construction through monikers.

Synopsis

Bonobo_Unknown      bonobo_get_object                   (const CORBA_char *name,
                                                         const char *interface_name,
                                                         CORBA_Environment *opt_ev);
Bonobo_Moniker      bonobo_moniker_client_new_from_name (const CORBA_char *name,
                                                         CORBA_Environment *opt_ev);
CORBA_char *        bonobo_moniker_client_get_name      (Bonobo_Moniker moniker,
                                                         CORBA_Environment *opt_ev);
Bonobo_Unknown      bonobo_moniker_client_resolve_default
                                                        (Bonobo_Moniker moniker,
                                                         const char *interface_name,
                                                         CORBA_Environment *opt_ev);
gboolean            bonobo_moniker_client_equal         (Bonobo_Moniker moniker,
                                                         const CORBA_char *name,
                                                         CORBA_Environment *opt_ev);
void                (*BonoboMonikerAsyncFn)             (Bonobo_Unknown object,
                                                         CORBA_Environment *ev,
                                                         gpointer user_data);
void                bonobo_get_object_async             (const CORBA_char *name,
                                                         const char *interface_name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);
void                bonobo_moniker_client_new_from_name_async
                                                        (const CORBA_char *name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);
void                bonobo_moniker_resolve_async        (Bonobo_Moniker moniker,
                                                         Bonobo_ResolveOptions *options,
                                                         const char *interface_name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);
void                bonobo_moniker_resolve_async_default
                                                        (Bonobo_Moniker moniker,
                                                         const char *interface_name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);
CORBA_char *        bonobo_moniker_util_get_parent_name (Bonobo_Moniker moniker,
                                                         CORBA_Environment *opt_ev);
Bonobo_Unknown      bonobo_moniker_util_qi_return       (Bonobo_Unknown object,
                                                         const CORBA_char *requested_interface,
                                                         CORBA_Environment *ev);
const char *        bonobo_moniker_util_parse_name      (const char *name,
                                                         int *plen);
int                 bonobo_moniker_util_seek_std_separator
                                                        (const CORBA_char *str,
                                                         int min_idx);
char *              bonobo_moniker_util_escape          (const char *string,
                                                         int offset);
char *              bonobo_moniker_util_unescape        (const char *string,
                                                         int num_chars);
void                bonobo_url_register                 (char *oafiid,
                                                         char *url,
                                                         char *mime_type,
                                                         Bonobo_Unknown object,
                                                         CORBA_Environment *ev);
void                bonobo_url_unregister               (char *oafiid,
                                                         char *url,
                                                         CORBA_Environment *ev);
Bonobo_Unknown      bonobo_url_lookup                   (char *oafiid,
                                                         char *url,
                                                         CORBA_Environment *ev);

Description

The moniker utility functions provide two sets of functions:

Helper functions for constructing and resolving monikers, and a simple get_object method that constructs and resolves against an interface in a single pass. Also, asynchronous versions of these methods are provided using the BonoboAsync code.
Helper functions for the implementation of new custom monikers are also provided here, along with a lot of the grunt code neccessary for moniker implementation, particularly constructing the chained list of sub-monikers that comprises a complex moniker.

The most useful function to get a feel for what monikers can do is the bonobo_get_object method. This is used to create a moniker and resolve it against a given interface like this:

Example 17. GetObject example

GtkWidget *
moniker_resolve_demo (void)
{
    Bonobo_Control control;
    CORBA_Environment ev;
    CORBA_exception_init (&ev);
    control = bonobo_get_object ("file:/demo/a.jpeg",
                                     "Bonobo/Control", NULL);
    if (control == CORBA_OBJECT_NIL)
        g_error ("Failed to get object file:/demo/a.jpeg");
    return bonobo_widget_new_control (control);
}

This also makes a control out of the widget.

It is worth noting that when resolving monikers a contracted version of the interface name may be used, ommitting the 'IDL:' prefix and / or the ':0' suffix.

Details

bonobo_get_object ()

Bonobo_Unknown      bonobo_get_object                   (const CORBA_char *name,
                                                         const char *interface_name,
                                                         CORBA_Environment *opt_ev);

This encapsulates both the parse stage and resolve process of using a moniker, providing a simple VisualBasic like mechanism for using the object name space.

`name` :	the name of a moniker
`interface_name` :	the name of the interface we want returned as the result
`opt_ev` :	an optional corba exception environment
Returns :	the requested interface or CORBA_OBJECT_NIL

bonobo_moniker_client_new_from_name ()

Bonobo_Moniker      bonobo_moniker_client_new_from_name (const CORBA_char *name,
                                                         CORBA_Environment *opt_ev);

This routine tries to parse a Moniker in string form

eg. file:/tmp/a.tar.gzgzip:tar:

into a CORBA_Object representation of this that can later be resolved against an interface.

`name` :	the name of a moniker
`opt_ev` :	an optional corba exception environment
Returns :	a new Moniker handle

bonobo_moniker_client_get_name ()

CORBA_char *        bonobo_moniker_client_get_name      (Bonobo_Moniker moniker,
                                                         CORBA_Environment *opt_ev);

`moniker` :	a moniker handle
`opt_ev` :	a corba exception environment
Returns :	the name of the moniker.

bonobo_moniker_client_resolve_default ()

Bonobo_Unknown      bonobo_moniker_client_resolve_default
                                                        (Bonobo_Moniker moniker,
                                                         const char *interface_name,
                                                         CORBA_Environment *opt_ev);

This resolves the moniker object against the given interface, with a default set of resolve options.

`moniker` :	a moniker
`interface_name` :	the name of the interface we want returned as the result
`opt_ev` :	an optional corba exception environment
Returns :	the interfaces resolved to or CORBA_OBJECT_NIL

bonobo_moniker_client_equal ()

gboolean            bonobo_moniker_client_equal         (Bonobo_Moniker moniker,
                                                         const CORBA_char *name,
                                                         CORBA_Environment *opt_ev);

Compare a full moniker with the given name

`moniker` :	The moniker
`name` :	a moniker name eg. file:/demo/a.jpeg
`opt_ev` :	optional CORBA_Environment or NULL.
Returns :	TRUE if they are the same

BonoboMonikerAsyncFn ()

void                (*BonoboMonikerAsyncFn)             (Bonobo_Unknown object,
                                                         CORBA_Environment *ev,
                                                         gpointer user_data);

Callback function, invoked when bonobo_get_object_async() completes its work.

`object` :	the newly-activated object, or `CORBA_OBJECT_NIL` if an exception occurred
`ev` :	CORBA environment that may contain an exception if an activation error occurred
`user_data` :	user data

bonobo_get_object_async ()

void                bonobo_get_object_async             (const CORBA_char *name,
                                                         const char *interface_name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);

An async version of bonobo_get_object

`interface_name` :	the name of the interface we want returned as the result
`ev` :	a corba exception environment
`cb` :	the async callback that gets the response
`user_data` :	user context data to pass to that callback

bonobo_moniker_client_new_from_name_async ()

void                bonobo_moniker_client_new_from_name_async
                                                        (const CORBA_char *name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);

An asynchronous version of new_from_name

`name` :	the name
`ev` :	a corba exception environment
`cb` :	the async callback that gets the response
`user_data` :	user context data to pass to that callback

bonobo_moniker_resolve_async ()

void                bonobo_moniker_resolve_async        (Bonobo_Moniker moniker,
                                                         Bonobo_ResolveOptions *options,
                                                         const char *interface_name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);

An async version of bonobo_moniker_client_resolve

`moniker` :	the moniker to resolve
`options` :	resolve options
`interface_name` :	the name of the interface we want returned as the result
`ev` :	a corba exception environment
`cb` :	the async callback that gets the response
`user_data` :	user context data to pass to that callback

bonobo_moniker_resolve_async_default ()

void                bonobo_moniker_resolve_async_default
                                                        (Bonobo_Moniker moniker,
                                                         const char *interface_name,
                                                         CORBA_Environment *ev,
                                                         BonoboMonikerAsyncFn cb,
                                                         gpointer user_data);

An async version of bonobo_moniker_client_resolve_default

`interface_name` :	the name of the interface we want returned as the result
`ev` :	a corba exception environment
`cb` :	the async callback that gets the response
`user_data` :	user context data to pass to that callback

bonobo_moniker_util_get_parent_name ()

CORBA_char *        bonobo_moniker_util_get_parent_name (Bonobo_Moniker moniker,
                                                         CORBA_Environment *opt_ev);

This gets the name of the parent moniker ( recursively all of the parents of this moniker ).

`moniker` :	the moniker
`opt_ev` :	an optional corba exception environment
Returns :	the name; use CORBA_free to release it.

bonobo_moniker_util_qi_return ()

Bonobo_Unknown      bonobo_moniker_util_qi_return       (Bonobo_Unknown object,
                                                         const CORBA_char *requested_interface,
                                                         CORBA_Environment *ev);

A helper function to share code from the end of a resolve implementation; this ensures that the returned object is of the correct interface by doing a queryInterface on the object.

`object` :	the unknown to query
`requested_interface` :	the desired interface
`ev` :	a corba exception environment
Returns :	an handle to the requested interface

bonobo_moniker_util_parse_name ()

const char *        bonobo_moniker_util_parse_name      (const char *name,
                                                         int *plen);

This routine finds the rightmost moniker name. For example it will return "cache:" if you pass in "file:/tmp.txtcache:". It will also store the length of the parent string in plen (13 for the above example)

`name` :	a moniker name
`plen` :	an optional pointer to store the parent length
Returns :	the name of the rightmost moniker

bonobo_moniker_util_seek_std_separator ()

int                 bonobo_moniker_util_seek_std_separator
                                                        (const CORBA_char *str,
                                                         int min_idx);

This looks for a moniker separator in a moniker's name string.

bonobo_moniker_util_escape ()

char *              bonobo_moniker_util_escape          (const char *string,
                                                         int offset);

Escapes possible separator characters inside a moniker these include '!' and '#', the '\' escaping character is used.

`string` :	an unescaped string
`offset` :	an offset of characters to ignore
Returns :	an escaped sub-string.

bonobo_moniker_util_unescape ()

char *              bonobo_moniker_util_unescape        (const char *string,
                                                         int num_chars);

This routine strips num_chars: from the start of string, discards the rest, and proceeds to un-escape characters escaped with '\'.

`string` :	a string
`num_chars` :	the number of chars to process.
Returns :	the unescaped sub string.

bonobo_url_register ()

void                bonobo_url_register                 (char *oafiid,
                                                         char *url,
                                                         char *mime_type,
                                                         Bonobo_Unknown object,
                                                         CORBA_Environment *ev);

`oafiid` :
`url` :
`mime_type` :
`object` :
`ev` :

bonobo_url_unregister ()

void                bonobo_url_unregister               (char *oafiid,
                                                         char *url,
                                                         CORBA_Environment *ev);

`oafiid` :
`url` :
`ev` :

bonobo_url_lookup ()

Bonobo_Unknown      bonobo_url_lookup                   (char *oafiid,
                                                         char *url,
                                                         CORBA_Environment *ev);

`oafiid` :
`url` :
`ev` :
Returns :

`str` :	the string to scan
`min_idx` :	the minimum offset at which a separator can be found.
Returns :	the position of the separator, or a pointer to the end of the string.

			Libbonobo Reference Manual
Top \| Description