GnuCash  4.8a-80-g9825132ea+
qofquery.h
Go to the documentation of this file.
1 /********************************************************************\
2  * qofquery.h -- find objects that match a certain expression. *
3  * *
4  * This program is free software; you can redistribute it and/or *
5  * modify it under the terms of the GNU General Public License as *
6  * published by the Free Software Foundation; either version 2 of *
7  * the License, or (at your option) any later version. *
8  * *
9  * This program is distributed in the hope that it will be useful, *
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
12  * GNU General Public License for more details. *
13  * *
14  * You should have received a copy of the GNU General Public License*
15  * along with this program; if not, contact: *
16  * *
17  * Free Software Foundation Voice: +1-617-542-5942 *
18  * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
19  * Boston, MA 02110-1301, USA gnu@gnu.org *
20  * *
21 \********************************************************************/
22 
74 #ifndef QOF_QUERYNEW_H
75 #define QOF_QUERYNEW_H
76 
77 #include "guid.h"
78 #include "qofbook.h"
79 #include "qofquerycore.h"
80 #include "qofchoice.h"
81 
82 #ifdef __cplusplus
83 extern "C"
84 {
85 #endif
86 
87 #define QOF_MOD_QUERY "qof.query"
88 
90 typedef struct _QofQuery QofQuery;
91 
93 typedef enum
94 {
95  QOF_QUERY_AND = 1,
96  QOF_QUERY_OR,
97  QOF_QUERY_NAND,
98  QOF_QUERY_NOR,
99  QOF_QUERY_XOR
100 } QofQueryOp;
101 
103 #define QOF_QUERY_FIRST_TERM QOF_QUERY_AND
104 
106 #define QUERY_DEFAULT_SORT "QofQueryDefaultSort"
107 
109 #define QOF_PARAM_BOOK "book"
110 #define QOF_PARAM_GUID "guid"
111 
113 #define QOF_PARAM_KVP "kvp"
114 #define QOF_PARAM_ACTIVE "active"
115 #define QOF_PARAM_VERSION "version"
116 
117 /* --------------------------------------------------------- */
119 // @{
126 void qof_query_init (void);
127 void qof_query_shutdown (void);
128 // @}
129 
130 /* --------------------------------------------------------- */
132 // @{
133 
134 QofQueryParamList * qof_query_build_param_list (char const *param, ...);
135 
145 QofQuery * qof_query_create (void);
146 QofQuery * qof_query_create_for (QofIdTypeConst obj_type);
147 
149 void qof_query_destroy (QofQuery *q);
150 
154 void qof_query_search_for (QofQuery *query, QofIdTypeConst obj_type);
155 
165 void qof_query_set_book (QofQuery *q, QofBook *book);
166 
167 
192 void qof_query_add_term (QofQuery *query, QofQueryParamList *param_list,
193  QofQueryPredData *pred_data, QofQueryOp op);
194 
196 void qof_query_add_guid_match (QofQuery *q, QofQueryParamList *param_list,
197  const GncGUID *guid, QofQueryOp op);
199 void qof_query_add_guid_list_match (QofQuery *q, QofQueryParamList *param_list,
200  GList *guid_list, QofGuidMatch options,
201  QofQueryOp op);
202 
207 void qof_query_add_boolean_match (QofQuery *q,
208  QofQueryParamList *param_list,
209  gboolean value,
210  QofQueryOp op);
211 
222 GList * qof_query_run (QofQuery *query);
223 
228 GList * qof_query_last_run (QofQuery *query);
229 
237 GList * qof_query_run_subquery (QofQuery *subquery,
238  const QofQuery* primary_query);
239 
243 void qof_query_clear (QofQuery *query);
244 
251 void qof_query_purge_terms (QofQuery *q, QofQueryParamList *param_list);
252 
257 int qof_query_has_terms (QofQuery *q);
258 
261 int qof_query_num_terms (QofQuery *q);
262 
264 gboolean qof_query_has_term_type (QofQuery *q, QofQueryParamList *term_param);
265 GSList * qof_query_get_term_type (QofQuery *q, QofQueryParamList *term_param);
266 
268 QofQuery * qof_query_copy (QofQuery *q);
269 
281 QofQuery * qof_query_invert(QofQuery *q);
282 
301 QofQuery * qof_query_merge(QofQuery *q1, QofQuery *q2, QofQueryOp op);
302 
306 void qof_query_merge_in_place(QofQuery *q1, QofQuery *q2, QofQueryOp op);
307 
328 void qof_query_set_sort_order (QofQuery *q,
329  QofQueryParamList *primary_sort_params,
330  QofQueryParamList *secondary_sort_params,
331  QofQueryParamList *tertiary_sort_params);
332 
333 void qof_query_set_sort_options (QofQuery *q, gint prim_op, gint sec_op,
334  gint tert_op);
335 
347 void qof_query_set_sort_increasing (QofQuery *q, gboolean prim_inc,
348  gboolean sec_inc, gboolean tert_inc);
349 
350 
361 void qof_query_set_max_results (QofQuery *q, int n);
362 
369 gboolean qof_query_equal (const QofQuery *q1, const QofQuery *q2);
370 
376 void qof_query_print (QofQuery *query);
377 
379 /*@ dependent @*/
380 QofIdType qof_query_get_search_for (const QofQuery *q);
381 
383 GList * qof_query_get_books (QofQuery *q);
384 
385 // @}
386 /* @} */
387 #ifdef __cplusplus
388 }
389 #endif
390 
391 #endif /* QOF_QUERYNEW_H */
void qof_query_add_term(QofQuery *query, QofQueryParamList *param_list, QofQueryPredData *pred_data, QofQueryOp op)
This is the general function that adds a new Query Term to a query.
Definition: qofquery.cpp:665
void qof_query_set_sort_order(QofQuery *q, QofQueryParamList *primary_sort_params, QofQueryParamList *secondary_sort_params, QofQueryParamList *tertiary_sort_params)
When a query is run, the results are sorted before being returned.
Definition: qofquery.cpp:1231
void qof_query_purge_terms(QofQuery *q, QofQueryParamList *param_list)
Remove query terms of a particular type from q.
Definition: qofquery.cpp:689
const gchar * QofIdTypeConst
QofIdTypeConst declaration.
Definition: qofid.h:87
void qof_query_print(QofQuery *query)
Log the Query.
Definition: qofquery.cpp:1522
globally unique ID User API
QofQuery * qof_query_copy(QofQuery *q)
Make a copy of the indicated query.
Definition: qofquery.cpp:1001
gboolean qof_query_equal(const QofQuery *q1, const QofQuery *q2)
Compare two queries for equality.
Definition: qofquery.cpp:1454
void qof_query_set_sort_increasing(QofQuery *q, gboolean prim_inc, gboolean sec_inc, gboolean tert_inc)
When a query is run, the results are sorted before being returned.
Definition: qofquery.cpp:1262
GSList QofQueryParamList
A list of parameters (QofIdType) used to describe a parameter to use in a predicate or when sorting...
Definition: qofquerycore.h:151
void qof_query_set_max_results(QofQuery *q, int n)
Set the maximum number of results that should be returned.
Definition: qofquery.cpp:1271
const gchar * QofIdType
QofIdType declaration.
Definition: qofid.h:85
int qof_query_num_terms(QofQuery *q)
Return the number of terms in the canonical form of the query.
Definition: qofquery.cpp:937
API for providing core Query data types.
GList * qof_query_run_subquery(QofQuery *subquery, const QofQuery *primary_query)
Perform a subquery, return the results.
Definition: qofquery.cpp:863
void qof_query_destroy(QofQuery *q)
Frees the resources associate with a Query object.
QofGuidMatch
Definition: qofquerycore.h:109
void qof_query_init(void)
Subsystem initialization and shutdown.
Definition: qofquery.cpp:1342
void qof_query_set_book(QofQuery *q, QofBook *book)
Set the book to be searched.
QofQuery * qof_query_merge(QofQuery *q1, QofQuery *q2, QofQueryOp op)
Combine two queries together using the Boolean set (logical) operator 'op'.
Definition: qofquery.cpp:1112
QofQuery * qof_query_invert(QofQuery *q)
Make a copy of the indicated query, inverting the sense of the search.
Definition: qofquery.cpp:1033
void qof_query_clear(QofQuery *query)
Remove all query terms from query.
Definition: qofquery.cpp:888
gboolean qof_query_has_term_type(QofQuery *q, QofQueryParamList *term_param)
DOCUMENT ME !!
Definition: qofquery.cpp:947
void qof_query_add_guid_match(QofQuery *q, QofQueryParamList *param_list, const GncGUID *guid, QofQueryOp op)
DOCUMENT ME !!
Definition: qofquery.cpp:1292
Encapsulate all the information about a dataset.
GList * qof_query_last_run(QofQuery *query)
Return the results of the last query, without causing the query to be re-run.
Definition: qofquery.cpp:880
QofQueryOp
Query Term Operators, for combining Query Terms.
Definition: qofquery.h:93
GList * qof_query_run(QofQuery *query)
Perform the query, return the results.
QofIdType qof_query_get_search_for(const QofQuery *q)
Return the type of data we're querying for.
Definition: qofquery.cpp:1362
Linking one entity to other entities of many possible types.
int qof_query_has_terms(QofQuery *q)
Return boolean FALSE if there are no terms in the query Can be used as a predicate to see if the quer...
Definition: qofquery.cpp:931
void qof_query_add_boolean_match(QofQuery *q, QofQueryParamList *param_list, gboolean value, QofQueryOp op)
Handy-dandy convenience routines, avoids having to create a separate predicate for boolean matches...
Definition: qofquery.cpp:1329
The type used to store guids in C.
Definition: guid.h:75
QofQuery * qof_query_create(void)
Create a new query.
Definition: qofquery.cpp:901
A Query.
Definition: qofquery.cpp:77
void qof_query_add_guid_list_match(QofQuery *q, QofQueryParamList *param_list, GList *guid_list, QofGuidMatch options, QofQueryOp op)
DOCUMENT ME !!
Definition: qofquery.cpp:1277
void qof_query_search_for(QofQuery *query, QofIdTypeConst obj_type)
Set the object type to be searched for.
Definition: qofquery.cpp:909
GList * qof_query_get_books(QofQuery *q)
Return the list of books we're using.
Definition: qofquery.cpp:1323
void qof_query_merge_in_place(QofQuery *q1, QofQuery *q2, QofQueryOp op)
Like qof_query_merge, but this will merge a copy of q2 into q1.
Definition: qofquery.cpp:1218