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