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