## 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 *`param` | a pointer to the MgParameter if it is a "free fill" parameter
MgQuery *`query` | a pointer to the MgQuery regulating the possible values of the parameters listed in the `params` attribute
GSList *`params` | the list of MgParameter objects which are regulated by the `query` query
GHashTable *`params_pos_in_query` | a 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.