![]() |
![]() |
![]() |
GNOME Data Access manual | ![]() |
---|
GdaParameterListGdaParameterList — Manages a list of GdaParameter objects which contain individual values |
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);
"param-changed" void user_function (GdaParameterList *gdaparameterlist, GObject *arg1, gpointer user_data); "public-data-changed" void user_function (GdaParameterList *gdaparameterlist, gpointer user_data);
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.
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;
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;
typedef struct { GSList *nodes; /* list of GdaParameterListNode, at least one entry */ GdaParameterListSource *nodes_source; /* if NULL, then @nodes contains exactly one entry */ } GdaParameterListGroup;
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;
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 |
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
|
guint gda_parameter_list_get_length (GdaParameterList *plist);
Get the number of GdaParameter objects in paramlist
plist : |
|
Returns : |
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 |
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 |
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
|
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 |
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
|
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
|
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
|
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
|
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 .
|
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
|
void gda_parameter_list_set_param_default_alias (GdaParameterList *paramlist, GdaParameter *param, GdaParameter *alias);
paramlist : |
|
param : |
|
alias : |
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 .
|
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. |
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. |
<< GdaParameter | GdaDataModel >> |