Bonobo API Reference Manual
<<< Previous PageHomeUpNext Page >>>

bonobo-moniker-util

Name

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

Synopsis



void        (*BonoboMonikerAsyncFn)         (Bonobo_Unknown object,
                                             CORBA_Environment *ev,
                                             gpointer user_data);
Bonobo_Unknown bonobo_get_object            (const CORBA_char *name,
                                             const char *interface_name,
                                             CORBA_Environment *ev);
Bonobo_Moniker bonobo_moniker_client_new_from_name
                                            (const CORBA_char *name,
                                             CORBA_Environment *ev);
CORBA_char* bonobo_moniker_client_get_name  (Bonobo_Moniker moniker,
                                             CORBA_Environment *ev);
Bonobo_Unknown bonobo_moniker_client_resolve_default
                                            (Bonobo_Moniker moniker,
                                             const char *interface_name,
                                             CORBA_Environment *ev);
BonoboObjectClient* bonobo_moniker_client_resolve_client_default
                                            (Bonobo_Moniker moniker,
                                             const char *interface_name,
                                             CORBA_Environment *ev);
Bonobo_Moniker bonobo_moniker_util_new_from_name_full
                                            (Bonobo_Moniker parent,
                                             const CORBA_char *name,
                                             CORBA_Environment *ev);
CORBA_char* bonobo_moniker_util_get_parent_name
                                            (Bonobo_Moniker moniker,
                                             CORBA_Environment *ev);
Bonobo_Unknown bonobo_moniker_util_qi_return
                                            (Bonobo_Unknown object,
                                             const CORBA_char *requested_interface,
                                             CORBA_Environment *ev);
int         bonobo_moniker_util_seek_std_separator
                                            (const CORBA_char *str,
                                             int min_idx);
void        bonobo_get_object_async         (const CORBA_char *name,
                                             const char *interface_name,
                                             CORBA_Environment *ev,
                                             guint timeout_msec,
                                             BonoboMonikerAsyncFn cb,
                                             gpointer user_data);
void        bonobo_moniker_client_new_from_name_async
                                            (const CORBA_char *name,
                                             CORBA_Environment *ev,
                                             guint timeout_msec,
                                             BonoboMonikerAsyncFn cb,
                                             gpointer user_data);
char*       bonobo_moniker_util_escape      (const char *string,
                                             int offset);
char*       bonobo_moniker_util_unescape    (const char *string,
                                             int num_chars);
gboolean    bonobo_moniker_client_equal     (Bonobo_Moniker moniker,
                                             const CORBA_char *name,
                                             CORBA_Environment *opt_ev);
void        bonobo_moniker_resolve_async    (Bonobo_Moniker moniker,
                                             Bonobo_ResolveOptions *options,
                                             const char *interface_name,
                                             CORBA_Environment *ev,
                                             guint timeout_msec,
                                             BonoboMonikerAsyncFn cb,
                                             gpointer user_data);
void        bonobo_moniker_resolve_async_default
                                            (Bonobo_Moniker moniker,
                                             const char *interface_name,
                                             CORBA_Environment *ev,
                                             guint timeout_msec,
                                             BonoboMonikerAsyncFn cb,
                                             gpointer user_data);

Description

The moniker utility functions provide two sets of functions:

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

BonoboMonikerAsyncFn ()

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

object : 
ev : 
user_data : 

bonobo_get_object ()

Bonobo_Unknown bonobo_get_object            (const CORBA_char *name,
                                             const char *interface_name,
                                             CORBA_Environment *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 display name of a moniker
interface_name : the name of the interface we want returned as the result
ev : a 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 *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 display name of a moniker
ev : a 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 *ev);

moniker : a moniker handle
ev : a corba exception environment
Returns : the display 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 *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
ev : a corba exception environment
Returns : the interfaces resolved to or CORBA_OBJECT_NIL

bonobo_moniker_client_resolve_client_default ()

BonoboObjectClient* bonobo_moniker_client_resolve_client_default
                                            (Bonobo_Moniker moniker,
                                             const char *interface_name,
                                             CORBA_Environment *ev);

See: bonobo_moniker_client_resolve_default; however this version returns a BonoboObjectClient wrapped reference.

moniker : the moniker
interface_name : the name of the interface we want returned as the result
ev : a corba exception environment
Returns : a BonoboObjectClient style reference.

bonobo_moniker_util_new_from_name_full ()

Bonobo_Moniker bonobo_moniker_util_new_from_name_full
                                            (Bonobo_Moniker parent,
                                             const CORBA_char *name,
                                             CORBA_Environment *ev);

This routine is used to continue building up the chain that forms a multi-part moniker. The parent is referenced as the parent and passed onto the next stage of parsing the 'name'. We eventually return a moniker handle which represents the end of a linked list of monikers each pointing to their parent:

file:/tmp/a.tar.gz <-- gzip: <-- tar: <-- [ this is returned ]

parent : A parent moniker to chain to or CORBA_OBJECT_NIL
name : the display name
ev : corba environment
Returns : The end node of a list of monikers representing name

bonobo_moniker_util_get_parent_name ()

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

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

moniker : the moniker
ev : a corba exception environment
Returns : the display 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_seek_std_separator ()

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

This looks for a standard separator in a moniker's display name string. Most monikers will want to use standard separators.

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 standard separator, or a pointer to the end of the string.

bonobo_get_object_async ()

void        bonobo_get_object_async         (const CORBA_char *name,
                                             const char *interface_name,
                                             CORBA_Environment *ev,
                                             guint timeout_msec,
                                             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
timeout_msec : the timeout in milliseconds
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,
                                             guint timeout_msec,
                                             BonoboMonikerAsyncFn cb,
                                             gpointer user_data);

An asynchronous version of new_from_name

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

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_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 display name eg. file:/demo/a.jpeg
opt_ev : optional CORBA_Environment or NULL.
Returns : TRUE if they are the same

bonobo_moniker_resolve_async ()

void        bonobo_moniker_resolve_async    (Bonobo_Moniker moniker,
                                             Bonobo_ResolveOptions *options,
                                             const char *interface_name,
                                             CORBA_Environment *ev,
                                             guint timeout_msec,
                                             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
timeout_msec : the timeout in milliseconds
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,
                                             guint timeout_msec,
                                             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
timeout_msec : the timeout in milliseconds
cb : the async callback that gets the response
user_data : user context data to pass to that callback



<<< Previous PageHomeUpNext Page >>>
bonobo-contextBonoboObjectClient