GdaParameterList

## GdaParameterList GdaParameterList — Manages a list of GdaParameter objects which contain individual values |

## Synopsis

                GdaParameterList;
    enum        GdaParameterListParamHint;
                GdaParameterListNode;
                GdaParameterListGroup;
                GdaParameterListSource;
    GdaParameterList* gda_parameter_list_new    (GSList *params);
    GdaParameterList* gda_parameter_list_new_from_spec
                                                (GdaDict *dict,
                                                 const gchar *xml_spec,
                                                 GError **error);
    guint       gda_parameter_list_get_length   (GdaParameterList *plist);
    gchar*      gda_parameter_list_get_spec     (GdaParameterList *paramlist);
    void        gda_parameter_list_add_param    (GdaParameterList *paramlist,
                                                 GdaParameter *param);
    gboolean    gda_parameter_list_is_coherent  (GdaParameterList *paramlist,
                                                 GError **error);
    gboolean    gda_parameter_list_is_valid     (GdaParameterList *paramlist);
    GdaParameter* gda_parameter_list_find_param (GdaParameterList *paramlist,
                                                 const gchar *param_name);
    GdaParameter* gda_parameter_list_find_param_for_user
                                                (GdaParameterList *paramlist,
                                                 GdaObject *user);
    GdaParameterListNode* gda_parameter_list_find_node_for_param
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param);
    GdaParameterListSource* gda_parameter_list_find_source_for_param
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param);
    GdaParameterListSource* gda_parameter_list_find_source
                                                (GdaParameterList *paramlist,
                                                 GdaDataModel *model);
    void        gda_parameter_list_set_param_default_value
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param,
                                                 const GdaValue *value);
    void        gda_parameter_list_set_param_default_alias
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param,
                                                 GdaParameter *alias);
    const GdaValue* gda_parameter_list_get_param_default_value
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaParameterList
                   +----GdaDataModelIter

## Signal Prototypes

    "param-changed"
                void        user_function      (GdaParameterList *gdaparameterlist,
                                                GObject *arg1,
                                                gpointer user_data);
    "public-data-changed"
                void        user_function      (GdaParameterList *gdaparameterlist,
                                                gpointer user_data);

## Description

A GdaParameterList is in a way only a better than GList list of GdaParameter objects: it handles a list of GdaParameter objects (accessible directly using paramlist->parameters) but also creates other lists such as:

- a list of GdaParameterListNode structures (the nodes_list attribute): for each parameter a such structure is created to show in a signle place all the information about each parameter: the GdaDataModel which may restrict the list of values along with the column number in it, and any hint for the parameter (a value made of GdaParameterListParamHint flags)

- a list of GdaParameterListSource structures (the sources_list attribute): each GdaParameterListSource structure is complementary to the GdaParameterListNode structures listed in its "nodes" attribute: there is one such structure for each GdaDataModel which may restrict values of one or more parameters.

- a list of GdaParameterListGroup structures (the groups_list attribute): there is one such structure for each _independant_ parameter (parameters which are constrained by the same data model all appear in the same GdaParameterListGroup structure)

Some queries require arguments before they can be executed. For such queries, the arguments are passed using GdaParameter objects (the list of parameters can be obtained using `gda_entity_get_parameters()`). The GdaParameterList object removes the hassle of managing these GdaParameter objects. For a query, a GdaParameterList can be obtained using the `gda_entity_get_exec_context()` function.

## Details

### GdaParameterList

    typedef struct _GdaParameterList GdaParameterList;

### enum GdaParameterListParamHint

    typedef enum {
    	GDA_PARAMETER_LIST_PARAM_READ_ONLY = 1 << 0, /* param should not be affected by user modifications */
    	GDA_PARAMETER_LIST_PARAM_HIDE      = 1 << 1  /* param should not be shown to the user */
    } GdaParameterListParamHint;

### GdaParameterListNode

    typedef struct {
    	GdaParameter   *param;         /* Can't be NULL */
    	GdaDataModel   *source_model;  /* may be NULL if @param is free-fill */
    	gint            source_column; /* unused is @source_model is NULL */
    	guint           hint;
    } GdaParameterListNode;

### GdaParameterListGroup

    typedef struct {
    	GSList                 *nodes;        /* list of GdaParameterListNode, at least one entry */
    	GdaParameterListSource *nodes_source; /* if NULL, then @nodes contains exactly one entry */
    } GdaParameterListGroup;

### GdaParameterListSource

    typedef struct {
    	GdaDataModel   *data_model;   /* Can't be NULL */
    	GSList         *nodes;        /* list of #GdaParameterListNode for which source_model == @data_model */

    	/* displayed columns in 'data_model' */
            gint            shown_n_cols;
            gint           *shown_cols_index;

            /* columns used as a reference (corresponding to PK values) in 'data_model' */
            gint            ref_n_cols;
            gint           *ref_cols_index;
    } GdaParameterListSource;

### gda_parameter_list_new ()

    GdaParameterList* gda_parameter_list_new    (GSList *params);

Creates a new GdaParameterList 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).

`params` : | a list of GdaParameter objects
Returns : | a new GdaParameterList object

### gda_parameter_list_new_from_spec ()

    GdaParameterList* gda_parameter_list_new_from_spec
                                                (GdaDict *dict,
                                                 const gchar *xml_spec,
                                                 GError **error);

Creates a new GdaParameterList object from the `xml_spec` specifications

`dict` : | a GdaDict object, or `NULL`
`xml_spec` : | a string
`error` : | a place to store the error, or `NULL`
Returns : | a new object, or `NULL` if an error occured

### gda_parameter_list_get_length ()

    guint       gda_parameter_list_get_length   (GdaParameterList *plist);

Get the number of GdaParameter objects in `paramlist`

`plist` : |
Returns : |

### gda_parameter_list_get_spec ()

    gchar*      gda_parameter_list_get_spec     (GdaParameterList *paramlist);

Get the specification as an XML string. See the `gda_parameter_list_new_from_spec()` form more information about the XML specification string format.

`paramlist` : | a GdaParameterList object
Returns : | a new string

### gda_parameter_list_add_param ()

    void        gda_parameter_list_add_param    (GdaParameterList *paramlist,
                                                 GdaParameter *param);

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

`paramlist` : | a GdaParameterList object
`param` : | a GdaParameter object

### gda_parameter_list_is_coherent ()

    gboolean    gda_parameter_list_is_coherent  (GdaParameterList *paramlist,
                                                 GError **error);

Checks that `paramlist` has a coherent public data structure

`paramlist` : | a GdaParameterList object
`error` : |
Returns : | TRUE if `paramlist` is coherent

### gda_parameter_list_is_valid ()

    gboolean    gda_parameter_list_is_valid     (GdaParameterList *paramlist);

Tells if all the paramlist's parameters have valid data

`paramlist` : | a GdaParameterList object
Returns : | TRUE if the paramlist is valid

### gda_parameter_list_find_param ()

    GdaParameter* gda_parameter_list_find_param (GdaParameterList *paramlist,
                                                 const gchar *param_name);

Finds a GdaParameter using its name

`paramlist` : | a GdaParameterList object
`param_name` : | the name of the requested parameter
Returns : | a GdaParameter or `NULL`

### gda_parameter_list_find_param_for_user ()

    GdaParameter* gda_parameter_list_find_param_for_user
                                                (GdaParameterList *paramlist,
                                                 GdaObject *user);

Finds a GdaParameter which is to be used by `user`

`paramlist` : | a GdaParameterList object
`user` : | a GdaObject object
Returns : | a GdaParameter or `NULL`

### gda_parameter_list_find_node_for_param ()

    GdaParameterListNode* gda_parameter_list_find_node_for_param
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param);

Finds a GdaParameterListNode holding information for `param`, don't modify the returned structure

`paramlist` : | a GdaParameterList object
`param` : | a GdaParameter object
Returns : | a GdaParameterListNode or `NULL`

### gda_parameter_list_find_source_for_param ()

    GdaParameterListSource* gda_parameter_list_find_source_for_param
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param);

Finds a GdaParameterListSource which contains the GdaDataModel restricting the possible values of `param`, don't modify the returned structure.

`paramlist` : | a GdaParameterList object
`param` : | a GdaParameter object
Returns : | a GdaParameterListSource or `NULL`

### gda_parameter_list_find_source ()

    GdaParameterListSource* gda_parameter_list_find_source
                                                (GdaParameterList *paramlist,
                                                 GdaDataModel *model);

Finds the GdaParameterListSource structure used in `paramlist` for which `model` is a the data model, don't modify the returned structure

`paramlist` : | a GdaParameterList object
`model` : | a GdaDataModel object
Returns : | a GdaParameterListSource pointer or `NULL`.

### gda_parameter_list_set_param_default_value ()

    void        gda_parameter_list_set_param_default_value
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param,
                                                 const GdaValue *value);

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

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

`paramlist` : | a GdaParameterList object
`param` : | a GdaParameter object, managed by `paramlist`
`value` : | a GdaValue, of the same type as `param`, or `NULL`

### gda_parameter_list_set_param_default_alias ()

    void        gda_parameter_list_set_param_default_alias
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param,
                                                 GdaParameter *alias);

`paramlist` : |
`param` : |
`alias` : |

### gda_parameter_list_get_param_default_value ()

    const GdaValue* gda_parameter_list_get_param_default_value
                                                (GdaParameterList *paramlist,
                                                 GdaParameter *param);

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

`paramlist` only offers to store the value using `gda_parameter_list_set_param_default_value()` or to store a GdaParameter reference from which to get a value using `gda_parameter_list_set_param_default_alias()`.

`paramlist` : | a GdaParameterList object
`param` : | a GdaParameter object, managed by `paramlist`
Returns : | a GdaValue, or `NULL`.

## Signals

### The "param-changed" signal

    void        user_function                  (GdaParameterList *gdaparameterlist,
                                                GObject *arg1,
                                                gpointer user_data);

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

### The "public-data-changed" signal

    void        user_function                  (GdaParameterList *gdaparameterlist,
                                                gpointer user_data);

`gdaparameterlist` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.