Query and Activation

Query and Activation — Querying for components and Activating them

Synopsis


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


typedef     Bonobo_ImplementationID;
typedef     Bonobo_ActivationID;
typedef     Bonobo_ActivationFlags;
enum        Bonobo_ActivationResultType;
Bonobo_ServerInfoList* bonobo_activation_query
                                            (const char *requirements,
                                             char *const *selection_order,
                                             CORBA_Environment *ev);
CORBA_Object bonobo_activation_activate     (const char *requirements,
                                             char *const *selection_order,
                                             Bonobo_ActivationFlags flags,
                                             Bonobo_ActivationID *ret_aid,
                                             CORBA_Environment *ev);
CORBA_Object bonobo_activation_activate_from_id
                                            (const Bonobo_ActivationID aid,
                                             Bonobo_ActivationFlags flags,
                                             Bonobo_ActivationID *ret_aid,
                                             CORBA_Environment *ev);
void        (*BonoboActivationCallback)     (CORBA_Object activated_object,
                                             const char *error_reason,
                                             gpointer user_data);
void        bonobo_activation_activate_async
                                            (const char *requirements,
                                             char *const *selection_order,
                                             Bonobo_ActivationFlags flags,
                                             BonoboActivationCallback callback,
                                             gpointer user_data,
                                             CORBA_Environment *ev);
void        bonobo_activation_activate_from_id_async
                                            (const Bonobo_ActivationID aid,
                                             Bonobo_ActivationFlags flags,
                                             BonoboActivationCallback callback,
                                             gpointer user_data,
                                             CORBA_Environment *ev);
void        bonobo_activation_set_activation_env_value
                                            (const char *name,
                                             const char *value);

Description

This section describes how you can query for components and activate them.

Two set of functions are described: synchronous and asynchronous ones. The asynchronous version of the functions allow you to avoid blocking your application while the CORBA servers are started.

Details

Bonobo_ImplementationID

   typedef CORBA_string Bonobo_ImplementationID;


Bonobo_ActivationID

   typedef CORBA_string Bonobo_ActivationID;


Bonobo_ActivationFlags

   typedef CORBA_long Bonobo_ActivationFlags;


enum Bonobo_ActivationResultType

   typedef enum
   {
      Bonobo_ACTIVATION_RESULT_OBJECT,
      Bonobo_ACTIVATION_RESULT_SHLIB,
      Bonobo_ACTIVATION_RESULT_NONE
   } Bonobo_ActivationResultType;


bonobo_activation_query ()

Bonobo_ServerInfoList* bonobo_activation_query
                                            (const char *requirements,
                                             char *const *selection_order,
                                             CORBA_Environment *ev);

Executes the requirements query on the bonobo-activation-server. The result is sorted according to selection_order. selection_order can safely be NULL as well as ev. The returned list has to be freed with CORBA_free.

requirements : query string.
selection_order : sort criterion for returned list.
ev : a CORBA_Environment structure which will contain the CORBA exception status of the operation, or NULL
Returns : the list of servers matching the requirements.

bonobo_activation_activate ()

CORBA_Object bonobo_activation_activate     (const char *requirements,
                                             char *const *selection_order,
                                             Bonobo_ActivationFlags flags,
                                             Bonobo_ActivationID *ret_aid,
                                             CORBA_Environment *ev);

Activates a given object. ret_aid can be safely NULLed as well as ev and selection_order. flags can be set to zero if you do not what to use.

requirements : query string.
selection_order : sort criterion for returned list.
flags : how to activate the object.
ret_aid : AID of the activated object.
ev : CORBA_Environment structure which will contain the CORBA exception status of the operation.
Returns : the CORBA object reference of the activated object. This value can be CORBA_OBJECT_NIL: you are supposed to check ev for success.

bonobo_activation_activate_from_id ()

CORBA_Object bonobo_activation_activate_from_id
                                            (const Bonobo_ActivationID aid,
                                             Bonobo_ActivationFlags flags,
                                             Bonobo_ActivationID *ret_aid,
                                             CORBA_Environment *ev);

Activates the server corresponding to aid. ret_aid can be safely NULLed as well as ev. flags can be zero if you do not know what to do.

aid : AID or IID of the object to activate.
flags : activation flag.
ret_aid : AID of the activated server.
ev : CORBA_Environment structure which will contain the CORBA exception status of the operation.
Returns : a CORBA object reference to the newly activated server. Do not forget to check ev for failure!!

BonoboActivationCallback ()

void        (*BonoboActivationCallback)     (CORBA_Object activated_object,
                                             const char *error_reason,
                                             gpointer user_data);

This is the signature of the function which you must pass as a callback to the asynchrounous activation functions.

activated_object :
error_reason :
user_data :

bonobo_activation_activate_async ()

void        bonobo_activation_activate_async
                                            (const char *requirements,
                                             char *const *selection_order,
                                             Bonobo_ActivationFlags flags,
                                             BonoboActivationCallback callback,
                                             gpointer user_data,
                                             CORBA_Environment *ev);

This function will asynchronously try to activate a component given the requirements query string. When the component is activated or when the activation fails, it will call callback with the given user_data data as parameter. callback will be called with a CORBA_OBJECT_NIL object if the activation fails. If the activation fails, the callback will be given a human-readable string containing a description of the error. In case of sucess, the error string value is undefined.

selection_order can be safely NULLed as well as ev and user_data. flags can be set to 0 if you do not know what to use.

requirements : the bonobo-activation query string.
selection_order : preference array.
flags : activation flags.
callback : callback function.
user_data : data to be poassed to the callback function.
ev : exception structure.

bonobo_activation_activate_from_id_async ()

void        bonobo_activation_activate_from_id_async
                                            (const Bonobo_ActivationID aid,
                                             Bonobo_ActivationFlags flags,
                                             BonoboActivationCallback callback,
                                             gpointer user_data,
                                             CORBA_Environment *ev);

This function will asynchronously try to activate a component with the given aid. When the component is activated or when the activation fails, it will call callback with the given user_data data as parameter. callback will be called with a CORBA_OBJECT_NIL object if the activation fails. If the activation fails, the callback will be given a human-readable string containing a description of the error. In case of sucess, the error string value is undefined.

flags can be 0 if you do not know what to set it to and ev can be safely set to NULL.

aid : the AID or IID of the component to activate.
flags : activation flags.
callback : callback function.
user_data : data to be poassed to the callback function.
ev : exception structure.

bonobo_activation_set_activation_env_value ()

void        bonobo_activation_set_activation_env_value
                                            (const char *name,
                                             const char *value);

name :
value :