MgContext

Name

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

Synopsis



#define     MG_CONTEXT_TYPE
#define     MG_CONTEXT                      (obj)
#define     IS_MG_CONTEXT                   (obj)
#define     MG_CONTEXT_CLASS                (klass)
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    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

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 MgParameters. A MgContext can be obtained using the mg_entity_get_exec_context() function.

Each MgObject 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

MG_CONTEXT_TYPE

#define MG_CONTEXT_TYPE          (mg_context_get_type())


MG_CONTEXT()

#define MG_CONTEXT(obj)          G_TYPE_CHECK_INSTANCE_CAST (obj, mg_context_get_type(), MgContext)

obj :


IS_MG_CONTEXT()

#define IS_MG_CONTEXT(obj)       G_TYPE_CHECK_INSTANCE_TYPE (obj, mg_context_get_type ())

obj :


MG_CONTEXT_CLASS()

#define MG_CONTEXT_CLASS(klass)  G_TYPE_CHECK_CLASS_CAST (klass, mg_context_get_type (), MgContextClass)

klass :


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 */
};


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 structure, 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 structure


mg_context_new_copy ()

GObject*    mg_context_new_copy             (MgContext *orig);

Copy constructor

orig :

a MgContext to make a copy of

Returns :

a the new copy of orig


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)