Registration

Name

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);
Bonobo_RegistrationResult bonobo_activation_active_server_register
                                            (const char *registration_id,
                                             CORBA_Object obj);
void        bonobo_activation_active_server_unregister
                                            (const char *iid,
                                             CORBA_Object obj);
char*       bonobo_activation_make_registration_id
                                            (const char *iid,
                                             const char *display);
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);
GSList*     bonobo_activation_registration_env_get_global
                                            (void);
Bonobo_RegistrationResult bonobo_activation_register_active_server
                                            (const char *iid,
                                             CORBA_Object obj,
                                             GSList *reg_env);
void        bonobo_activation_register_client
                                            (Bonobo_ActivationContext context,
                                             CORBA_Environment *ev);
const char* bonobo_activation_iid_get       (void);
typedef     BonoboActivationPlugin;
typedef     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_active_server_register ()

Bonobo_RegistrationResult bonobo_activation_active_server_register
                                            (const char *registration_id,
                                             CORBA_Object obj);

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

This function is now deprecated and should no longer be used. bonobo_activation_register_active_server() should now be used.

registration_id :

IID of the server to register.

obj :

CORBA::Object to register.

Returns :

status of the registration.


bonobo_activation_active_server_unregister ()

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

iid :

obj :


bonobo_activation_make_registration_id ()

char*       bonobo_activation_make_registration_id
                                            (const char *iid,
                                             const char *display);

Creates bonobo-activation registration ID suitable for use with bonobo_activation_active_server_register(). If display is the name of an X display, then using this registration ID will ensure that the server will only be used by clients using the same X display.

This method is now deprecated. Instead you can achieve the same effect by:

  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);

iid :

IID of the server to unregister.

display :

the X display name with which you wish to register.

Returns :

newly allocated registration id.


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_registration_env_get_global ()

GSList*     bonobo_activation_registration_env_get_global
                                            (void);

Returns :


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:

  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_register_client ()

void        bonobo_activation_register_client
                                            (Bonobo_ActivationContext context,
                                             CORBA_Environment *ev);

context :

ev :


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