![]() |
![]() |
![]() |
Libgnomedb Reference Manual | ![]() |
---|---|---|---|---|
GnomeDbQuery; enum GnomeDbQueryType; GType gnome_db_query_get_type (void); GObject* gnome_db_query_new (GnomeDbDict *dict); GObject* gnome_db_query_new_from_sql (GnomeDbDict *dict, const gchar *sql, GError **error); GObject* gnome_db_query_new_copy (GnomeDbQuery *orig, GHashTable *replacements); void gnome_db_query_set_query_type (GnomeDbQuery *query, GnomeDbQueryType type); GnomeDbQueryType gnome_db_query_get_query_type (GnomeDbQuery *query); const gchar* gnome_db_query_get_query_type_string (GnomeDbQuery *query); gboolean gnome_db_query_is_select_query (GnomeDbQuery *query); gboolean gnome_db_query_is_modif_query (GnomeDbQuery *query); GnomeDbQuery* gnome_db_query_get_parent_query (GnomeDbQuery *query); gboolean gnome_db_query_is_equal_to (GnomeDbQuery *query, GnomeDbQuery *compare_to); GSList* gnome_db_query_get_all_fields (GnomeDbQuery *query); GnomeDbQfield* gnome_db_query_get_first_field_for_target (GnomeDbQuery *query, GnomeDbTarget *target); GnomeDbQfield* gnome_db_query_get_field_by_sql_naming (GnomeDbQuery *query, const gchar *sql_naming); GSList* gnome_db_query_get_fields_by_target (GnomeDbQuery *query, GnomeDbTarget *target, gboolean visible_fields_only); GnomeDbQfield* gnome_db_query_get_field_by_ref_field (GnomeDbQuery *query, GnomeDbTarget *target, GnomeDbField *ref_field, GnomeDbFieldState field_state); void gnome_db_query_set_sql_text (GnomeDbQuery *query, const gchar *sql, GError **error); const gchar* gnome_db_query_get_sql_text (GnomeDbQuery *query); GSList* gnome_db_query_get_sub_queries (GnomeDbQuery *query); void gnome_db_query_add_sub_query (GnomeDbQuery *query, GnomeDbQuery *sub_query); void gnome_db_query_del_sub_query (GnomeDbQuery *query, GnomeDbQuery *sub_query); const GSList* gnome_db_query_get_param_sources (GnomeDbQuery *query); void gnome_db_query_add_param_source (GnomeDbQuery *query, GnomeDbQuery *param_source); void gnome_db_query_del_param_source (GnomeDbQuery *query, GnomeDbQuery *param_source); gboolean gnome_db_query_add_target (GnomeDbQuery *query, GnomeDbTarget *target, GError **error); void gnome_db_query_del_target (GnomeDbQuery *query, GnomeDbTarget *target); GSList* gnome_db_query_get_targets (GnomeDbQuery *query); GnomeDbTarget* gnome_db_query_get_target_by_xml_id (GnomeDbQuery *query, const gchar *xml_id); GnomeDbTarget* gnome_db_query_get_target_by_alias (GnomeDbQuery *query, const gchar *alias_or_name); GSList* gnome_db_query_get_target_pkfields (GnomeDbQuery *query, GnomeDbTarget *target); GSList* gnome_db_query_get_joins (GnomeDbQuery *query); GnomeDbJoin* gnome_db_query_get_join_by_targets (GnomeDbQuery *query, GnomeDbTarget *target1, GnomeDbTarget *target2); gboolean gnome_db_query_add_join (GnomeDbQuery *query, GnomeDbJoin *join); void gnome_db_query_del_join (GnomeDbQuery *query, GnomeDbJoin *join); void gnome_db_query_set_condition (GnomeDbQuery *query, GnomeDbCondition *cond); GnomeDbCondition* gnome_db_query_get_condition (GnomeDbQuery *query); GSList* gnome_db_query_get_main_conditions (GnomeDbQuery *query); void gnome_db_query_append_condition (GnomeDbQuery *query, GnomeDbCondition *cond, gboolean append_as_and); void gnome_db_query_set_order_by_field (GnomeDbQuery *query, GnomeDbQfield *field, gint order, gboolean ascendant); gint gnome_db_query_get_order_by_field (GnomeDbQuery *query, GnomeDbQfield *field, gboolean *ascendant); GSList* gnome_db_query_expand_all_field (GnomeDbQuery *query, GnomeDbTarget *target); void gnome_db_query_order_fields_using_join_conds (GnomeDbQuery *query); GnomeDbQfield* gnome_db_query_add_field_from_sql (GnomeDbQuery *query, const gchar *field, GError **error);
GnomeDbQuery implements GnomeDbXmlStorage, GnomeDbRenderer, GnomeDbReferer and GnomeDbEntity.
"auto-clean" gboolean : Read / Write "cond-serial" guint : Read "field-serial" guint : Read "really-all-fields" gpointer : Read "target-serial" guint : Read
"condition-changed" void user_function (GnomeDbQuery *dbquery, gpointer user_data) : Run first "join-added" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "join-removed" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "join-updated" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "sub-query-added" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "sub-query-removed" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "sub-query-updated" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "target-added" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "target-removed" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "target-updated" void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first "type-changed" void user_function (GnomeDbQuery *dbquery, gpointer user_data) : Run first
Any query (which can be of any type, see the GnomeDbQueryType enum) can be represented by a GnomeDbQuery object. Also a query may require some parameters to be provided before in can be executed; each parameter is then represented by a GnomeDbParameter object, and parameters required for a query are organised within a GnomeDbDataSet object.
It implements the GnomeDbEntity, GnomeDbXmlStorage, GnomeDbReferer and GnomeDbRenderer interfaces.
typedef enum { GNOME_DB_QUERY_TYPE_SELECT, GNOME_DB_QUERY_TYPE_INSERT, GNOME_DB_QUERY_TYPE_UPDATE, GNOME_DB_QUERY_TYPE_DELETE, GNOME_DB_QUERY_TYPE_UNION, GNOME_DB_QUERY_TYPE_INTERSECT, GNOME_DB_QUERY_TYPE_EXCEPT, GNOME_DB_QUERY_TYPE_NON_PARSED_SQL } GnomeDbQueryType;
GObject* gnome_db_query_new (GnomeDbDict *dict);
Creates a new GnomeDbQuery object
dict : |
a GnomeDbDict object |
Returns : | the new object |
GObject* gnome_db_query_new_from_sql (GnomeDbDict *dict, const gchar *sql, GError **error);
Creates a new GnomeDbQuery object and fills its structure by parsing the sql
. If the parsing failed,
then the returned query is of type GNOME_DB_QUERY_TYPE_NON_PARSED_SQL.
To be parsed successfully, the expected SQL must respect the SQL standard; some extensions have been added to be able to define variables within the SQL statement. See the introduction to the GnomeDbQuery for more information.
The error
is set only if the SQL statement parsing produced an error; there is always a new GnomeDbQuery
object which is returned.
dict : |
a GnomeDbDict object |
sql : |
an SQL statement |
error : |
location to store error, or NULL
|
Returns : | a new GnomeDbQuery |
GObject* gnome_db_query_new_copy (GnomeDbQuery *orig, GHashTable *replacements);
Copy constructor
orig : |
a GnomeDbQuery to make a copy of |
replacements : |
a hash table to store replacements, or NULL
|
Returns : | a the new copy of orig
|
void gnome_db_query_set_query_type (GnomeDbQuery *query, GnomeDbQueryType type);
Sets the type of query
query : |
a GnomeDbQuery object |
type : |
the new type of query |
GnomeDbQueryType gnome_db_query_get_query_type (GnomeDbQuery *query);
Get the type of a query
query : |
a GnomeDbQuery object |
Returns : | the type of query
|
const gchar* gnome_db_query_get_query_type_string (GnomeDbQuery *query);
Get the type of a query as a human readable string
query : |
a GnomeDbQuery object |
Returns : | a string for the type of query
|
gboolean gnome_db_query_is_select_query (GnomeDbQuery *query);
Tells if query
is a SELECTION query (a simple SELECT, UNION, INTERSECT or EXCEPT); pure SQL
queries are not handled and will always return FALSE.
query : |
a # GnomeDbQuery object |
Returns : | TRUE if query is a selection query
|
gboolean gnome_db_query_is_modif_query (GnomeDbQuery *query);
Tells if query
is a modification query (a simple UPDATE, DELETE, INSERT).; pure SQL
queries are not handled and will always return FALSE.
query : |
a # GnomeDbQuery object |
Returns : | TRUE if query is a modification query
|
GnomeDbQuery* gnome_db_query_get_parent_query (GnomeDbQuery *query);
Get the parent query of query
query : |
a GnomeDbQuery object |
Returns : | the parent query, or NULL if query does not have any parent
|
gboolean gnome_db_query_is_equal_to (GnomeDbQuery *query, GnomeDbQuery *compare_to);
Compares query
and compare_to
from the point of view of the result of the execution
of the two queries.
query : |
a GnomeDbQuery object |
compare_to : |
a GnomeDbQuery object |
Returns : | TRUE is query and compare_to represent the same query
|
GSList* gnome_db_query_get_all_fields (GnomeDbQuery *query);
Fetch a list of all the fields of query
: the ones which are visible, and
the ones which are not visible and are not internal query fields.
query : |
a GnomeDbQuery object |
Returns : | a new list of fields |
GnomeDbQfield* gnome_db_query_get_first_field_for_target (GnomeDbQuery *query, GnomeDbTarget *target);
Finds the first occurence of a GnomeDbQfField object whose target is target
in query
query : |
a GnomeDbQuery object |
target : |
|
Returns : | the requested field, or NULL
|
GnomeDbQfield* gnome_db_query_get_field_by_sql_naming (GnomeDbQuery *query, const gchar *sql_naming);
query : |
a GnomeDbQuery object |
sql_naming : |
|
Returns : |
GSList* gnome_db_query_get_fields_by_target (GnomeDbQuery *query, GnomeDbTarget *target, gboolean visible_fields_only);
Get a list of all the GnomeDbQfield objects in query
which depent on the existance of
target
.
query : |
a GnomeDbQuery object |
target : |
a GnomeDbTarget object representing a target in query
|
visible_fields_only : |
|
Returns : | a new list of GnomeDbQfield objects |
GnomeDbQfield* gnome_db_query_get_field_by_ref_field (GnomeDbQuery *query, GnomeDbTarget *target, GnomeDbField *ref_field, GnomeDbFieldState field_state);
Finds the first GnomeDbQfield object in query
which represents ref_field
.
The returned object will be a GnomeDbQfField object which represents ref_field
.
If target
is specified, then the returned field will be linked to that GnomeDbTarget object.
query : |
a GnomeDbQuery object |
target : |
a GnomeDbTarget, or NULL
|
ref_field : |
a GnomeDbField object |
field_state : |
tells about the status of the requested field |
Returns : | a GnomeDbQfField object or NULL
|
void gnome_db_query_set_sql_text (GnomeDbQuery *query, const gchar *sql, GError **error);
Defines query
's contents from an SQL statement. The SQL text is parsed and the internal query structured
is built from that; the query type is also set. If the SQL text cannot be parsed, then the internal structure
of the query is emptied and the query type is set to GNOME_DB_QUERY_TYPE_NON_PARSED_SQL.
To be parsed successfully, the expected SQL must respect the SQL standard; some extensions have been added to be able to define variables within the SQL statement. See the introduction to the GnomeDbQuery for more information.
query : |
a # GnomeDbQuery object |
sql : |
the SQL statement |
error : |
location to store parsing error, or NULL
|
const gchar* gnome_db_query_get_sql_text (GnomeDbQuery *query);
Obtain a new string representing the SQL version of the query.
WARNING: the returned SQL statement may contain some extensions which allow for the definition of variables (see the introduction to the GnomeDbQuery for more information). As such the returned SQL cannot be executed as it may provoque errors. To get an executable statement, use the GnomeDbRenderer interface's methods.
query : |
a GnomeDbQuery object |
Returns : | the new string |
GSList* gnome_db_query_get_sub_queries (GnomeDbQuery *query);
Get a list of all the sub-queries managed by query
query : |
a GnomeDbQuery object |
Returns : | a new list of the sub-queries |
void gnome_db_query_add_sub_query (GnomeDbQuery *query, GnomeDbQuery *sub_query);
Add sub_query
to query
. Sub queries are managed by their parent query, and as such they
are destroyed when their parent query is destroyed.
query : |
a GnomeDbQuery object |
sub_query : |
a GnomeDbQuery object |
void gnome_db_query_del_sub_query (GnomeDbQuery *query, GnomeDbQuery *sub_query);
Removes sub_query
from query
. sub_query
MUST be present within query
.
query : |
a GnomeDbQuery object |
sub_query : |
a GnomeDbQuery object |
const GSList* gnome_db_query_get_param_sources (GnomeDbQuery *query);
Get a list of the parameter source queries that are references as such by query
.
query : |
a GnomeDbQuery object |
Returns : | the list of GnomeDbQuery objects |
void gnome_db_query_add_param_source (GnomeDbQuery *query, GnomeDbQuery *param_source);
Tells query
that param_source
is a query which potentially will constraint the possible values
of one or more of query
's parameters. This implies that query
keeps a reference on param_source
.
query : |
a GnomeDbQuery object |
param_source : |
a GnomeDbQuery object |
void gnome_db_query_del_param_source (GnomeDbQuery *query, GnomeDbQuery *param_source);
Tells query
that it should no longer take care of param_source
.
The parameters which depend on param_source
will still depend on it, though.
query : |
a GnomeDbQuery object |
param_source : |
a GnomeDbQuery object |
gboolean gnome_db_query_add_target (GnomeDbQuery *query, GnomeDbTarget *target, GError **error);
Adds a target to query
. A target represents a entity (it can actually be a table,
a view, or another query) which query
will use.
For a SELECT query, the targets appear after the FROM clause. The targets can be joined two by two using GnomeDbJoin objects
For UPDATE, DELETE or INSERT queries, there can be only ONE GnomeDbTarget object which is the one where the data modifications are performed.
For UNION and INTERSECT queries, there is no possible GnomeDbTarget object.
query : |
a GnomeDbQuery object |
target : |
a GnomeDbTarget to add to query
|
error : |
location to store error, or NULL
|
Returns : | TRUE if no error occurred |
void gnome_db_query_del_target (GnomeDbQuery *query, GnomeDbTarget *target);
Removes target
from query
. target
MUST be present within query
. Warning:
All the joins and fields which depended on target
are also removed.
query : |
a GnomeDbQuery object |
target : |
a GnomeDbTarget object |
GSList* gnome_db_query_get_targets (GnomeDbQuery *query);
Get a list of all the targets used in query
query : |
a GnomeDbQuery object |
Returns : | a new list of the targets |
GnomeDbTarget* gnome_db_query_get_target_by_xml_id (GnomeDbQuery *query, const gchar *xml_id);
Get a pointer to a GnomeDbTarget (which must be within query
) using
its XML Id
query : |
a GnomeDbQuery object |
xml_id : |
the XML Id of the requested GnomeDbTarget object |
Returns : | the GnomeDbTarget object, or NULL if not found |
GnomeDbTarget* gnome_db_query_get_target_by_alias (GnomeDbQuery *query, const gchar *alias_or_name);
Get a pointer to a GnomeDbTarget (which must be within query
) using
its alias (if not found then alias_or_name
is interpreted as the target name)
query : |
a GnomeDbQuery object |
alias_or_name : |
the alias or name |
Returns : | the GnomeDbTarget object, or NULL if not found |
GSList* gnome_db_query_get_target_pkfields (GnomeDbQuery *query, GnomeDbTarget *target);
Makes a list of the GnomeDbQfield objects which represent primary key fields of
the entity represented by target
.
If the entity represented by target
does not have any primary key, or if the
primary key's fields are not present in query
, then the returned value is NULL
.
query : |
a GnomeDbQuery object |
target : |
a GnomeDbTarget object |
Returns : | a new GSList, or NULL .
|
GSList* gnome_db_query_get_joins (GnomeDbQuery *query);
Get a list of all the joins used in query
query : |
a GnomeDbQuery object |
Returns : | a new list of the joins |
GnomeDbJoin* gnome_db_query_get_join_by_targets (GnomeDbQuery *query, GnomeDbTarget *target1, GnomeDbTarget *target2);
Find a join in query
which joins the target1
and target2
targets
query : |
a GnomeDbQuery object |
target1 : |
a GnomeDbTarget object |
target2 : |
a GnomeDbTarget object |
Returns : | the GnomeDbJoin object, or NULL
|
gboolean gnome_db_query_add_join (GnomeDbQuery *query, GnomeDbJoin *join);
Add a join to query
. A join is defined by the two GnomeDbTarget objects it joins and by
a join condition which MUST ONLY make use of fields of the two entities represented by the
targets.
For any given couple of GnomeDbTarget objects, there can exist ONLY ONE GnomeDbJoin which joins the two.
query : |
a GnomeDbQuery object |
join : |
a GnomeDbJoin object |
Returns : | TRUE on success, and FALSE otherwise |
void gnome_db_query_del_join (GnomeDbQuery *query, GnomeDbJoin *join);
Removes join
from query
. join
MUST be present within query
.
query : |
a GnomeDbQuery object |
join : |
a GnomeDbJoin object |
void gnome_db_query_set_condition (GnomeDbQuery *query, GnomeDbCondition *cond);
Sets the query's associated condition; if there was already a query condition, then the old one is trashed first.
Pass NULL
as the cond
argument to remove any query condition
query : |
a GnomeDbQuery object |
cond : |
a GnomeDbCondition object, or NULL to remove condition
|
GnomeDbCondition* gnome_db_query_get_condition (GnomeDbQuery *query);
Get the query's associated condition
query : |
a GnomeDbQuery object |
Returns : | the GnomeDbCondition object |
GSList* gnome_db_query_get_main_conditions (GnomeDbQuery *query);
Makes a list of all the conditions (part of the WHERE clause) which
are always verified by query
when it is executed.
Examples: if the WHERE clause is: --> "A and B" then the list will contains {A, B} --> "A and (B or C)" it will contain {A, B or C} --> "A and (B and not C)", it will contain {A, B, not C}
query : |
a GnomeDbQuery object |
Returns : | a new list of GnomeDbCondition objects |
void gnome_db_query_append_condition (GnomeDbQuery *query, GnomeDbCondition *cond, gboolean append_as_and);
Appends the cond
object to query
's condition. If query
does not yet
have any condition, then the result is the same as gnome_db_query_set_condition()
;
otherwise, cond
is added to query
's condition, using the AND operator
if append_as_and
is TRUE, and an OR operator if append_as_and
is FALSE.
query : |
a GnomeDbQuery object |
cond : |
a GnomeDbCondition object |
append_as_and : |
mode of append if there is already a query condition |
void gnome_db_query_set_order_by_field (GnomeDbQuery *query, GnomeDbQfield *field, gint order, gboolean ascendant);
Sets field
to be used in the ORDER BY clause (using the order
and ascendant
attributes) if
order
>= 0. If order
< 0, then field
will not be used in the ORDER BY clause.
query : |
a GnomeDbQuery |
field : |
a GnomeDbQfield which is in query
|
order : |
the order in the list of ORDER BY fields (starts at 0), or -1 |
ascendant : |
TRUE to sort ascending |
gint gnome_db_query_get_order_by_field (GnomeDbQuery *query, GnomeDbQfield *field, gboolean *ascendant);
Tells if field
(which MUST be in query
) is part of the ORDER BY clause.
query : |
a GnomeDbQuery |
field : |
a GnomeDbQfield which is in query
|
ascendant : |
if not NULL , will be set TRUE if ascendant sorting and FALSE otherwise
|
Returns : | -1 if no, and the order where it appears in the ORDER BY list otherwise |
GSList* gnome_db_query_expand_all_field (GnomeDbQuery *query, GnomeDbTarget *target);
Converts each visible "target.*" (GnomeDbQfAll) field into its list of fields. For example "t1.*" becomes "t1.a, t1.b" if table t1 is composed of fields "a" and "b". The original GnomeDbQfAll field is not removed, but simply rendered non visible.
The returned list must be free'd by the caller using g_slist_free()
.
query : |
a GnomeDbQuery object |
target : |
a GnomeDbTarget, or NULL
|
Returns : | a new list of the GnomeDbQfield objects which have been created |
void gnome_db_query_order_fields_using_join_conds (GnomeDbQuery *query);
Re-orders the fields in query
using the joins' conditions: for each join condition,
the used query fields are grouped together near the 1st visible field.
query : |
a GnomeDbQuery object |
GnomeDbQfield* gnome_db_query_add_field_from_sql (GnomeDbQuery *query, const gchar *field, GError **error);
Parses field
and if it represents a valid SQL expression for a
field, then add it to query
.
query : |
a GnomeDbQuery object |
field : |
a SQL expression |
error : |
place to store the error, or NULL
|
Returns : | a new GnomeDbQfield object, or NULL
|
auto-clean
" property"auto-clean" gboolean : Read / Write
Determines if the query tries to clean unused objects.
Default value: TRUE
void user_function (GnomeDbQuery *dbquery, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer arg1, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GnomeDbQuery *dbquery, gpointer user_data) : Run first
dbquery : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |