Query and Activation

## Query and Activation Query and Activation — Querying for components and Activating them |

## Synopsis

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

    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_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` : |