SearchTitlesPhrases

bonobo-moniker-util
Libbonobo Reference Manual
<<< Previous PageHomeUpNext Page >>>

bonobo-moniker-util

Name

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

object : 
ev : 
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

name : 
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

moniker : 
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.

See also bonobo_moniker_util_escape

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.

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 : 



<<< Previous PageHomeUpNext Page >>>
bonobo-moniker-contextbonobo-persist-client