manpagez: man pages & more
html files: libbonobo
Home | html | info | man

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

1
2
3
4
5
6
7
8
9
10
11
12
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.

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 :

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.