Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next 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:

- 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 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 Page | Home | Up | Next Page >>>
bonobo-context | BonoboObjectClient