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