|  |  |  | Libbonobo Reference Manual |  | 
|---|
bonobo-moniker-util — Object activation and construction through monikers.
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);
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 3. 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.
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 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 | 
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_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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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_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 | 
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 | 
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. | 
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. | 
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. | 
void        bonobo_url_register             (char *oafiid,
                                             char *url,
                                             char *mime_type,
                                             Bonobo_Unknown object,
                                             CORBA_Environment *ev);
| oafiid : | |
| url : | |
| mime_type : | |
| object : | |
| ev : | 
void        bonobo_url_unregister           (char *oafiid,
                                             char *url,
                                             CORBA_Environment *ev);
| oafiid : | |
| url : | |
| ev : | 
| << BonoboMonikerSimple | BonoboMonikerExtender >> |