Query and Activation

Query and Activation — Querying for components and Activating them

Synopsis

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

typedef             MateComponent_ImplementationID;
typedef             MateComponent_ActivationID;
typedef             MateComponent_ActivationFlags;
                    MateComponent_ActivationResultType;
MateComponent_ServerInfoList * matecomponent_activation_query
                                                        (const char *requirements,
                                                         char *const *selection_order,
                                                         CORBA_Environment *ev);
CORBA_Object        matecomponent_activation_activate   (const char *requirements,
                                                         char *const *selection_order,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponent_ActivationID *ret_aid,
                                                         CORBA_Environment *ev);
CORBA_Object        matecomponent_activation_activate_from_id
                                                        (const MateComponent_ActivationID aid,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponent_ActivationID *ret_aid,
                                                         CORBA_Environment *ev);
void                (*MateComponentActivationCallback)  (CORBA_Object activated_object,
                                                         const char *error_reason,
                                                         gpointer user_data);
void                matecomponent_activation_activate_async
                                                        (const char *requirements,
                                                         char *const *selection_order,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponentActivationCallback callback,
                                                         gpointer user_data,
                                                         CORBA_Environment *ev);
void                matecomponent_activation_activate_from_id_async
                                                        (const MateComponent_ActivationID aid,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponentActivationCallback callback,
                                                         gpointer user_data,
                                                         CORBA_Environment *ev);
void                matecomponent_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

MateComponent_ImplementationID

typedef CORBA_string MateComponent_ImplementationID;


MateComponent_ActivationID

typedef CORBA_string MateComponent_ActivationID;


MateComponent_ActivationFlags

typedef CORBA_long MateComponent_ActivationFlags;


MateComponent_ActivationResultType

typedef struct {
 CORBA_unsigned_long _maximum, _length; MateComponent_ActivationEnvValue* _buffer; CORBA_boolean _release; } CORBA_sequence_MateComponent_ActivationEnvValue;
#endif
#if !defined(TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_0)
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_0 'M'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_1 'a'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_2 't'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_3 'e'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_4 'C'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_5 'o'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_6 'm'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_7 'p'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_8 'o'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_9 'n'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_10 'e'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_11 'n'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_12 't'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_13 '_'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_14 'A'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_15 'c'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_16 't'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_17 'i'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_18 'v'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_19 'a'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_20 't'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_21 'i'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_22 'o'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_23 'n'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_24 '_'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_25 't'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_26 'y'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_27 'p'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_28 'e'
#define TC_IMPL_TC_CORBA_sequence_MateComponent_ActivationEnvValue_29 's'
#ifdef MATECORBA_IDL_C_IMODULE_MateComponent_Activation_types
static
#else
extern
#endif
MATECORBA2_MAYBE_CONST struct CORBA_TypeCode_struct TC_CORBA_sequence_MateComponent_ActivationEnvValue_struct;
#define TC_CORBA_sequence_MateComponent_ActivationEnvValue ((CORBA_TypeCode)&TC_CORBA_sequence_MateComponent_ActivationEnvValue_struct)
#endif
#define CORBA_sequence_MateComponent_ActivationEnvValue__alloc() ((CORBA_sequence_MateComponent_ActivationEnvValue *)MateCORBA_small_alloc (TC_CORBA_sequence_MateComponent_ActivationEnvValue))
#define CORBA_sequence_MateComponent_ActivationEnvValue__freekids(m,d) MateCORBA_small_freekids (TC_CORBA_sequence_MateComponent_ActivationEnvValue,(m),(d))
#define CORBA_sequence_MateComponent_ActivationEnvValue_allocbuf(l) ((MateComponent_ActivationEnvValue*)MateCORBA_small_allocbuf (TC_CORBA_sequence_MateComponent_ActivationEnvValue, (l)))
#define CORBA_sequence_MateComponent_ActivationEnvValue_allocbuf(l) ((MateComponent_ActivationEnvValue*)MateCORBA_small_allocbuf (TC_CORBA_sequence_MateComponent_ActivationEnvValue, (l)))
#endif
#if !defined(_MateComponent_ActivationEnvironment_defined)
#define _MateComponent_ActivationEnvironment_defined 1
typedef CORBA_sequence_MateComponent_ActivationEnvValue MateComponent_ActivationEnvironment;
#define MateComponent_ActivationEnvironment_marshal(x,y,z) CORBA_sequence_MateComponent_ActivationEnvValue_marshal((x),(y),(z))
#define MateComponent_ActivationEnvironment_demarshal(x,y,z,i) CORBA_sequence_MateComponent_ActivationEnvValue_demarshal((x),(y),(z),(i))
#if !defined(TC_IMPL_TC_MateComponent_ActivationEnvironment_0)
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_0 'M'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_1 'a'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_2 't'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_3 'e'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_4 'C'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_5 'o'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_6 'm'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_7 'p'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_8 'o'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_9 'n'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_10 'e'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_11 'n'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_12 't'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_13 '_'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_14 'A'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_15 'c'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_16 't'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_17 'i'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_18 'v'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_19 'a'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_20 't'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_21 'i'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_22 'o'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_23 'n'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_24 '_'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_25 't'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_26 'y'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_27 'p'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_28 'e'
#define TC_IMPL_TC_MateComponent_ActivationEnvironment_29 's'
#ifdef MATECORBA_IDL_C_IMODULE_MateComponent_Activation_types
static
#else
extern
#endif
MATECORBA2_MAYBE_CONST struct CORBA_TypeCode_struct TC_MateComponent_ActivationEnvironment_struct;
#define TC_MateComponent_ActivationEnvironment ((CORBA_TypeCode)&TC_MateComponent_ActivationEnvironment_struct)
#endif
#define MateComponent_ActivationEnvironment__alloc() ((MateComponent_ActivationEnvironment *)MateCORBA_small_alloc (TC_CORBA_sequence_MateComponent_ActivationEnvValue))
#define MateComponent_ActivationEnvironment__freekids(m,d) MateCORBA_small_freekids (TC_CORBA_sequence_MateComponent_ActivationEnvValue,(m),(d))
#define MateComponent_ActivationEnvironment_allocbuf(l) ((MateComponent_ActivationEnvValue*)MateCORBA_small_allocbuf (TC_CORBA_sequence_MateComponent_ActivationEnvValue, (l)))
#endif
#if !defined(_MateComponent_ActivationResultType_defined)
#define _MateComponent_ActivationResultType_defined 1
typedef enum {
  MateComponent_ACTIVATION_RESULT_OBJECT,
  MateComponent_ACTIVATION_RESULT_SHLIB,
  MateComponent_ACTIVATION_RESULT_NONE
} MateComponent_ActivationResultType;


matecomponent_activation_query ()

MateComponent_ServerInfoList * matecomponent_activation_query
                                                        (const char *requirements,
                                                         char *const *selection_order,
                                                         CORBA_Environment *ev);

Executes the requirements query on the matecomponent-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.

matecomponent_activation_activate ()

CORBA_Object        matecomponent_activation_activate   (const char *requirements,
                                                         char *const *selection_order,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponent_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.

matecomponent_activation_activate_from_id ()

CORBA_Object        matecomponent_activation_activate_from_id
                                                        (const MateComponent_ActivationID aid,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponent_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!!

MateComponentActivationCallback ()

void                (*MateComponentActivationCallback)  (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.


matecomponent_activation_activate_async ()

void                matecomponent_activation_activate_async
                                                        (const char *requirements,
                                                         char *const *selection_order,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponentActivationCallback 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 matecomponent-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.

matecomponent_activation_activate_from_id_async ()

void                matecomponent_activation_activate_from_id_async
                                                        (const MateComponent_ActivationID aid,
                                                         MateComponent_ActivationFlags flags,
                                                         MateComponentActivationCallback 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.

matecomponent_activation_set_activation_env_value ()

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