bonobo-moniker-util

## 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 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.

## 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

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