![]() | ![]() | ![]() | Libmergeant Reference Manual | ![]() |
---|
MgContextMgContext — Manages all the MgParameter objects required to execute a query |
MgContext; 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);
"param-changed" void user_function (MgContext *mgcontext, GObject *arg1, gpointer user_data);
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.
typedef struct { /* 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 */ } MgContextNode;
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.
|
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 |
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
|
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 |
void mg_context_merge_context_params (MgContext *context, MgContext *context_to_merge);
Add to context
all the parameters of context_to_merge
.
gboolean mg_context_is_coherent (MgContext *context, GError **error);
context : | |
error : | |
Returns : |
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 |
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 |
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
|
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
|
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
|
void mg_context_set_param_default_alias (MgContext *context, MgParameter *param, MgParameter *alias);
context : | |
param : | |
alias : |
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 .
|
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. |
<< MgParameter | Interfaces >> |