![]() | ![]() | ![]() | Bonobo Activation API Reference Manual | ![]() |
---|
Query and Activation — Querying for components and Activating them
#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);
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.
typedef enum { Bonobo_ACTIVATION_RESULT_OBJECT, Bonobo_ACTIVATION_RESULT_SHLIB, Bonobo_ACTIVATION_RESULT_NONE } Bonobo_ActivationResultType;
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. |
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. |
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!! |
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 : |
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. |
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. |
<< Initialization | Utilities >> |