Registration

## Registration Registration — Registering CORBA objects to Bonobo Activation. |

## Synopsis

    #include <bonobo-activation/bonobo-activation.h>

    enum                Bonobo_RegistrationResult;
    void                bonobo_activation_unregister_active_server
                                                            (const char *iid,
                                                             CORBA_Object obj);
    void                bonobo_activation_registration_env_free
                                                            (GSList *reg_env);
    GSList *            bonobo_activation_registration_env_set
                                                            (GSList *reg_env,
                                                             const char *name,
                                                             const char *value);
    void                bonobo_activation_registration_env_set_global
                                                            (GSList *reg_env,
                                                             gboolean append_if_existing);
    Bonobo_RegistrationResult  bonobo_activation_register_active_server
                                                            (const char *iid,
                                                             CORBA_Object obj,
                                                             GSList *reg_env);
    const char *        bonobo_activation_iid_get           (void);
                        BonoboActivationPlugin;
                        BonoboActivationPluginObject;
    void                bonobo_activation_plugin_use        (PortableServer_Servant servant,
                                                             gpointer impl_ptr);
    void                bonobo_activation_plugin_unuse      (gpointer impl_ptr);

## Description

When writing a component which can be activated through Bonobo Activation by clients, you need to be register your component to Bonobo Activation once it is created.

## Details

### enum Bonobo_RegistrationResult

    typedef enum {
      Bonobo_ACTIVATION_REG_SUCCESS,
      Bonobo_ACTIVATION_REG_NOT_LISTED,
      Bonobo_ACTIVATION_REG_ALREADY_ACTIVE,
      Bonobo_ACTIVATION_REG_ERROR
    } Bonobo_RegistrationResult;

### bonobo_activation_unregister_active_server ()

    void                bonobo_activation_unregister_active_server
                                                            (const char *iid,
                                                             CORBA_Object obj);

Unregisters `obj` with `iid` with the local bonobo-activation-server daemon.

`iid` : | IID of the server to unregister.
`obj` : | CORBA::Object to unregister.

### bonobo_activation_registration_env_free ()

    void                bonobo_activation_registration_env_free
                                                            (GSList *reg_env);

Frees the registration environment list, `reg_env`.

`reg_env` : | a GSList pointer.

### bonobo_activation_registration_env_set ()

    GSList *            bonobo_activation_registration_env_set
                                                            (GSList *reg_env,
                                                             const char *name,
                                                             const char *value);

Sets the environment variable `name` to `value` in the registration environment list `reg_env`.

`reg_env` : | a GSList pointer.
`name` : | the name of the env variable (must not be `NULL`).
`value` : | the value of the env variable (may be `NULL`).
Returns : | the new start of `reg_env`.

### bonobo_activation_registration_env_set_global ()

    void                bonobo_activation_registration_env_set_global
                                                            (GSList *reg_env,
                                                             gboolean append_if_existing);

Sets the global registration environment list with the contents of `reg_env`. If `append_if_existing` is set to `FALSE`, the an existing global list will be overwritten.

`reg_env` : | a GSList pointer.
`append_if_existing` : | whether or not to append to the global list.

### bonobo_activation_register_active_server ()

    Bonobo_RegistrationResult  bonobo_activation_register_active_server
                                                            (const char *iid,
                                                             CORBA_Object obj,
                                                             GSList *reg_env);

Registers `obj` with `iid` with the local bonobo-activation-server daemon.

If `reg_env` is not `NULL`, `obj` will be registered in such a way that if a client who's environment differs from the environment specified in `reg_env`, then another attempt to activate `iid` will not result in a reference to `obj` being returned, but rather another instance of `iid` being activated.

So, for example, you can ensure that a seperate instance of the component is activated for each distinct X display (and screen) by:

    1
    2
    3
    4
    5
    display_name = gdk_display_get_name (gdk_display_get_default());
    reg_env = bonobo_activation_registration_env_set (
                               reg_env, "DISPLAY", display_name);
    bonobo_activation_register_active_server (iid, active_server, reg_env);
    bonobo_activation_registration_env_free (reg_env);

If `reg_env` is `NULL`, the global registration environment list will be used if it is set. See `bonobo_activation_registration_env_set_global()`.

`iid` : | IID of the server to register.
`obj` : | CORBA::Object to register.
`reg_env` : | the registration environment.
Returns : | status of the registration.

### bonobo_activation_iid_get ()

    const char *        bonobo_activation_iid_get           (void);

Returns : |

### BonoboActivationPlugin

    typedef struct {
    	const BonoboActivationPluginObject *plugin_object_list;
    	const char *description;
            gpointer dummy[8];
    } BonoboActivationPlugin;

Components which want to be activated as shared libraries must export an BonoboActivationPlugin structure of name Bonobo_Plugin_info. An exmaple of how to use it folows:

    static CORBA_Object
    hi_shlib_make_object (PortableServer_POA poa,
                          const char *iid,
                          gpointer impl_ptr,
                          CORBA_Environment *ev)
    {
            CORBA_Object object_ref;
            object_ref = impl_Hi__create (poa, ev);
            if (object_ref == CORBA_OBJECT_NIL
                || ev->_major != CORBA_NO_EXCEPTION) {
                    printf ("Server cannot get objref\n");
                    return CORBA_OBJECT_NIL;
            }
            bonobo_activation_plugin_use (poa, impl_ptr);
            return object_ref;
    }
    static const BonoboActivationPluginObject hi_plugin_list[] = {
            {
                    "OAFIID:Hi:20000923",
                    hi_shlib_make_object
            },
            {
                    NULL
      	}
    };
    const BonoboActivationPlugin Bonobo_Plugin_info = {
            hi_plugin_list,
            "Hi example"
    };

### BonoboActivationPluginObject

    typedef struct {
    	const char *iid;

    	/* This routine should call bonobo_activation_plugin_use(servant, impl_ptr),
             * as should all routines which activate CORBA objects
    	 * implemented by this shared library. This needs to be done
             * before making any CORBA calls on the object, or
    	 * passing that object around. First thing after servant creation
             * always works. :)
             */

            CORBA_Object (*activate) (PortableServer_POA poa,
                                      const char *iid,
                                      gpointer impl_ptr, /* This pointer should be stored by the implementation
                                                             * to be passed to bonobo_activation_plugin_unuse() in the
                                                             * implementation's destruction routine. */
    				  CORBA_Environment *ev);
            gpointer dummy[4];
    } BonoboActivationPluginObject;

### bonobo_activation_plugin_use ()

    void                bonobo_activation_plugin_use        (PortableServer_Servant servant,
                                                             gpointer impl_ptr);

You should call this routine to activate a shared library-based CORBA Object. It will be called by OAF if the component exports correctly an `BonoboActivationPlugin` structure named "Bonobo_Plugin_info".

`servant` : | The servant that was created
`impl_ptr` : | The impl_ptr that was passed to the original activation routine

### bonobo_activation_plugin_unuse ()

    void                bonobo_activation_plugin_unuse      (gpointer impl_ptr);

Side effects: May arrange for the shared library that the implementation is in to be unloaded.

When a shlib plugin for a CORBA object is destroying an implementation, it should call this function to make sure that the shared library is unloaded as needed.

`impl_ptr` : | The impl_ptr that was passed to the activation routine