MgContext

MgContext — Manages all the MgParameter objects required to execute a query

Synopsis




struct      MgContext;
struct      MgContextNode;
guint       mg_context_get_type             (void);
GObject*    mg_context_new                  (MgConf *conf,
                                             GSList *params);
GObject*    mg_context_new_copy             (MgContext *orig,
                                             gboolean copy_params,
                                             GHashTable *replacements);
void        mg_context_add_param            (MgContext *context,
                                             MgParameter *param);
void        mg_context_merge_context_params (MgContext *context,
                                             MgContext *context_to_merge);
gboolean    mg_context_is_coherent          (MgContext *context,
                                             GError **error);
gboolean    mg_context_is_valid             (MgContext *context);
gboolean    mg_context_needs_user_input     (MgContext *context);
MgParameter* mg_context_find_parameter_for_field
                                            (MgContext *context,
                                             MgQfield *for_field);
MgContextNode* mg_context_find_node_for_param
                                            (MgContext *context,
                                             MgParameter *param);
void        mg_context_set_param_default_value
                                            (MgContext *context,
                                             MgParameter *param,
                                             const GdaValue *value);
void        mg_context_set_param_default_alias
                                            (MgContext *context,
                                             MgParameter *param,
                                             MgParameter *alias);
const GdaValue* mg_context_get_param_default_value
                                            (MgContext *context,
                                             MgParameter *param);

Object Hierarchy


  GObject
   +----MgBase
         +----MgContext

Properties


  "prop"                 gpointer             : Read / Write

Signal Prototypes


"param-changed"
            void        user_function      (MgContext *mgcontext,
                                            GObject *arg1,
                                            gpointer user_data);

Description

Some queries require arguments before they can be executed. For such queries, the arguments are passed using MgParameter objects (the list of parameters can be obtained using mg_entity_get_parameters()). The MgContext object removes the hassle of managing these MgParameter objects. For a query, a MgContext can be obtained using the mg_entity_get_exec_context() function.

Each MgContext object then provides two lists to be used by the programmer: the 'parameters' list which is a simple copy of the parameters list given as argument to mg_context_new(), and the 'nodes' list which is a list of MgContextNode structures created by the MgContext object. These two lists should not be modified.

Details

struct MgContext

struct MgContext;


struct MgContextNode

struct MgContextNode {

	/* this MgContextNode is only for one parameter, free fill */
        MgParameter *param; 

	/* this MgContextNode is for one or more parameters, listed in 'params' and the params values
	   depend on the result of the execution of 'query' */
        MgQuery     *query; 
        GSList      *params;
	GHashTable  *params_pos_in_query; /* key=param value=column in query where its source field is */
};

The MgContext object creates a list of MgContextNode structures which in a way "sort" the MgParameter objects. Each MgParameter can either be a "free fill" parameter (which means any value is acceptable as long as it is of the requested data type), or can depend on a list of values provided by a single MgQfield object within a query.

Each MgContextNode structure groups one or more parameters:

  • exactly one MgParameter object if that parameter is a "free fill" parameter

  • a list of one or more MgParameter objects if all the parameters in the list are dependant on values of a common SELECT Query

MgParameter *parama pointer to the MgParameter if it is a "free fill" parameter
MgQuery *querya pointer to the MgQuery regulating the possible values of the parameters listed in the params attribute
GSList *paramsthe list of MgParameter objects which are regulated by the query query
GHashTable *params_pos_in_querya GHashTable which holds, for each parameter in params, the position in query's resultset of the values which are acceptable for the parameter.

mg_context_get_type ()

guint       mg_context_get_type             (void);

Returns :

mg_context_new ()

GObject*    mg_context_new                  (MgConf *conf,
                                             GSList *params);

Creates a new MgContext object, and populates it with the list given as argument. The list can then be freed as it gets copied. All the parameters in params are referenced counted and modified, so they should not be used anymore afterwards, and the params list gets copied (so it should be freed by the caller).

conf : a MgConf object
params : a list of MgParameter objects
Returns : a new MgContext object

mg_context_new_copy ()

GObject*    mg_context_new_copy             (MgContext *orig,
                                             gboolean copy_params,
                                             GHashTable *replacements);

Copy constructor. replacements is used and modified only if copy_params is TRUE.

orig : a MgContext to make a copy of
copy_params : TRUE to also make a copy of the MgParameter objects within orig
replacements : a place where to store the parameters and queries replacements, or NULL
Returns : a the new copy of orig

mg_context_add_param ()

void        mg_context_add_param            (MgContext *context,
                                             MgParameter *param);

Adds param to the list of parameters managed within context. <b>WARNING:</b> the context may decide not to use the param parameter, but to modify another parameter already present within the context. The publicly available lists from the context object may also be changed in the process.

context : a MgContext object
param : a MgParameter object

mg_context_merge_context_params ()

void        mg_context_merge_context_params (MgContext *context,
                                             MgContext *context_to_merge);

Add to context all the parameters of context_to_merge.

context : a MgContext object
context_to_merge : a MgContext object

mg_context_is_coherent ()

gboolean    mg_context_is_coherent          (MgContext *context,
                                             GError **error);

context :
error :
Returns :

mg_context_is_valid ()

gboolean    mg_context_is_valid             (MgContext *context);

Tells if all the context's parameters have valid data

context : a MgContext object
Returns : TRUE if the context is valid

mg_context_needs_user_input ()

gboolean    mg_context_needs_user_input     (MgContext *context);

Tells if the context needs the user to provide some values for some parameters. This is the case when either the context is invalid, or the context is valid and contains some MgParameter objects which are valid but are defined to require a user input.

Note: this function may return TRUE even though context is valid.

context : a MgContext object
Returns : TRUE if a user input is required for the context

mg_context_find_parameter_for_field ()

MgParameter* mg_context_find_parameter_for_field
                                            (MgContext *context,
                                             MgQfield *for_field);

Finds a MgParameter which is to be used by for_field

context : a MgContext object
for_field : a MgQfield object
Returns : a MgParameter or NULL

mg_context_find_node_for_param ()

MgContextNode* mg_context_find_node_for_param
                                            (MgContext *context,
                                             MgParameter *param);

Finds a MgContextNode which is for param

context : a MgContext object
param : a MgParameter object
Returns : a MgContextNode or NULL

mg_context_set_param_default_value ()

void        mg_context_set_param_default_value
                                            (MgContext *context,
                                             MgParameter *param,
                                             const GdaValue *value);

Stores value in context to make it possible for context's users to find a default value for param when one is required, instead of NULL.

context only provides a storage functionnality, the way the value obtained with mg_context_get_param_default_value() is used is up to context's user.

context : a MgContext object
param : a MgParameter object, managed by context
value : a GdaValue, of the same type as param, or NULL

mg_context_set_param_default_alias ()

void        mg_context_set_param_default_alias
                                            (MgContext *context,
                                             MgParameter *param,
                                             MgParameter *alias);

context :
param :
alias :

mg_context_get_param_default_value ()

const GdaValue* mg_context_get_param_default_value
                                            (MgContext *context,
                                             MgParameter *param);

Retreives a prefered default value to be used by context's users when necessary. The usage of such values is decided by context's users.

context only offers to store the value using mg_context_set_param_default_value() or to store a MgParameter reference from which to get a value using mg_context_set_param_default_alias().

context : a MgContext object
param : a MgParameter object, managed by context
Returns : a GdaValue, or NULL.

Properties

"prop" (gpointer : Read / Write)

Signals

The "param-changed" signal

void        user_function                  (MgContext *mgcontext,
                                            GObject *arg1,
                                            gpointer user_data);

mgcontext :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.