Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# bonobo-context

## Name

bonobo-context -- Extensible runtime service interface

## Synopsis

    void        bonobo_context_init             (void);
    void        bonobo_context_shutdown         (void);
    void        bonobo_context_add              (const CORBA_char *context_name,
                                                 Bonobo_Unknown context);
    Bonobo_Unknown bonobo_context_get           (const CORBA_char *context_name,
                                                 CORBA_Environment *opt_ev);
    BonoboObject* bonobo_context_running_get    (void);
    void        bonobo_running_context_auto_exit_unref
                                                (BonoboObject *object);

## Description

The bonobo-context code is designed to provide a way to expose CORBA contexts through a single C interface. This is so that language bindings can get away with wrapping a single function, and yet have access to the whole Bonobo service framework. Two examples of this are the MonikerContext and the RunningContext ( see Bonobo_Context.idl ).

Example 1. Getting and using the moniker context

    Bonobo_MonikerContext context;
    Bonobo_Unknown        object;

    context = bonobo_context_get ("Activation", NULL);

    if (context == CORBA_OBJECT_NIL)
    	g_error (_("Internal error, no activation context"));

    object = Bonobo_MonikerContext_getObject (
    	"file:/demo/a.jpeg", "Bonobo/Control", ev);
    ...

The list of contexts is open and may be expanded in the future, currently there are the following:

- Activation - Bonobo/MonikerContext

- Running - Bonobo/RunningContext

The running context is particularly useful for ensuring that server processes exit cleanly when all their objects and derived objects are dead. To do this we can simply do the following:

Example 2. How to get a factory to quit when it is idle

    static void
    last_unref_exit_cb (gpointer      context,
    		    BonoboObject *factory)
    {
            bonobo_object_unref (factory);
    	gtk_main_quit();
    }
    ...
    int main (int argc, char **argv)
    {
    	...
    	bonobo_running_context_ignore_object (BONOBO_OBJREF (object));

    	gtk_signal_connect (GTK_OBJECT (bonobo_context_running_get()),
    			    "last_unref", last_unref_exit_cb, factory);
    	...
    	bonobo_main();
    }

Since this is a commonly used thing there is a helper to make this easier:

Example 3. How to get a factory to quit when it is idle

    bonobo_running_context_auto_exit_unref (factory)

## Details

### bonobo_context_init ()

    void        bonobo_context_init             (void);

Sets up the context system, internal use only, called by bonobo_init.

### bonobo_context_shutdown ()

    void        bonobo_context_shutdown         (void);

Shuts down the context system, internal use only

### bonobo_context_add ()

    void        bonobo_context_add              (const CORBA_char *context_name,
                                                 Bonobo_Unknown context);

This function adds a new context to the context system

`context_name` : | the name to refer to the context by
`context` : | The Bonobo_Unknown; a ref. is taken on this.

### bonobo_context_get ()

    Bonobo_Unknown bonobo_context_get           (const CORBA_char *context_name,
                                                 CORBA_Environment *opt_ev);

The most useful context is named 'Activation' and returns the IDL:Bonobo/ActivationContext:1.0 interface.

`context_name` : | the name of the context
`opt_ev` : | optional Environment, or NULL
Returns : | a new reference to a global Bonobo context or CORBA_OBJECT_NIL

### bonobo_context_running_get ()

    BonoboObject* bonobo_context_running_get    (void);

Returns : |

### bonobo_running_context_auto_exit_unref ()

    void        bonobo_running_context_auto_exit_unref
                                                (BonoboObject *object);

`object` : |

<<< Previous Page | Home | Up | Next Page >>>
Object Activation and Lifecycle | bonobo-moniker-util