1 /********************************************************************\ 2 * qofquerycore.h -- API for providing core Query data types * 3 * Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU> * 4 * Copyright (C) 2006 Neil Williams <linux@codehelp.co.uk> * 5 * * 6 * This program is free software; you can redistribute it and/or * 7 * modify it under the terms of the GNU General Public License as * 8 * published by the Free Software Foundation; either version 2 of * 9 * the License, or (at your option) any later version. * 10 * * 11 * This program is distributed in the hope that it will be useful, * 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 14 * GNU General Public License for more details. * 15 * * 16 * You should have received a copy of the GNU General Public License* 17 * along with this program; if not, contact: * 18 * * 19 * Free Software Foundation Voice: +1-617-542-5942 * 20 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 21 * Boston, MA 02110-1301, USA gnu@gnu.org * 22 * * 23 \********************************************************************/ 24 25 /** @addtogroup Query 26 @{ */ 27 28 /** @file qofquerycore.h 29 @brief API for providing core Query data types 30 @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU> 31 */ 32 33 #ifndef QOF_QUERYCORE_H 34 #define QOF_QUERYCORE_H 35 36 #include "qofnumeric.h" 37 #include "qofdate.h" 38 #include "kvpframe.h" 39 #include "qofclass.h" 40 41 /** 42 * PREDICATE DATA TYPES: All the predicate data types are rolled up into 43 * the union type PredicateData. The "type" field specifies which type 44 * the union is. 45 */ 46 typedef struct _QofQueryPredData QofQueryPredData; 47 48 /** Standard Query comparitors, for how to compare objects in a predicate. 49 * Note that not all core types implement all comparitors 50 */ 51 typedef enum 52 { 53 QOF_COMPARE_LT = 1, 54 QOF_COMPARE_LTE, 55 QOF_COMPARE_EQUAL, 56 QOF_COMPARE_GT, 57 QOF_COMPARE_GTE, 58 QOF_COMPARE_NEQ 59 } QofQueryCompare; 60 61 /** List of known core query data-types... 62 * Each core query type defines it's set of optional "comparitor qualifiers". 63 */ 64 /* Comparisons for QOF_TYPE_STRING */ 65 typedef enum 66 { 67 QOF_STRING_MATCH_NORMAL = 1, 68 QOF_STRING_MATCH_CASEINSENSITIVE 69 } QofStringMatch; 70 71 /** Comparisons for QOF_TYPE_DATE 72 * The QOF_DATE_MATCH_DAY comparison rounds the two time 73 * values to mid-day and then compares these rounded values. 74 * The QOF_DATE_MATCH_NORMAL comparison matches the time values, 75 * down to the second. 76 */ 77 78 typedef enum 79 { 80 QOF_DATE_MATCH_NORMAL = 1, 81 QOF_DATE_MATCH_DAY 82 } QofDateMatch; 83 84 /** Comparisons for QOF_TYPE_NUMERIC, QOF_TYPE_DEBCRED 85 * 86 * XXX Should be deprecated, or at least wrapped up as a convenience 87 * function, this is based on the old bill gribble code, which assumed 88 * the amount was always positive, and then specified a funds-flow 89 * direction (credit, debit, or either). 90 * 91 * The point being that 'match credit' is equivalent to the compound 92 * predicate (amount >= 0) && (amount 'op' value) while the 'match 93 * debit' predicate is equivalent to (amount <= 0) && (abs(amount) 'op' value) 94 */ 95 96 typedef enum 97 { 98 QOF_NUMERIC_MATCH_DEBIT = 1, 99 QOF_NUMERIC_MATCH_CREDIT, 100 QOF_NUMERIC_MATCH_ANY 101 } QofNumericMatch; 102 103 /* Comparisons for QOF_TYPE_GUID */ 104 typedef enum 105 { 106 /** These expect a single object and expect the 107 * QofAccessFunc returns GUID* */ 108 QOF_GUID_MATCH_ANY = 1, 109 QOF_GUID_MATCH_NONE, 110 QOF_GUID_MATCH_NULL, 111 /** These expect a GList* of objects and calls the QofAccessFunc routine 112 * on each item in the list to obtain a GUID* for each object */ 113 QOF_GUID_MATCH_ALL, 114 /** These expect a single object and expect the QofAccessFunc function 115 * to return a GList* of GUID* (the list is the property of the caller) */ 116 QOF_GUID_MATCH_LIST_ANY, 117 } QofGuidMatch; 118 119 /** A CHAR type is for a RECNCell, Comparisons for QOF_TYPE_CHAR 120 * 'ANY' will match any charagter in the string. 121 * 122 * Match 'ANY' is a convenience/performance-enhanced predicate 123 * for the compound statement (value==char1) || (value==char2) || etc. 124 * Match 'NONE' is equivalent to 125 * (value != char1) && (value != char2) && etc. 126 */ 127 typedef enum 128 { 129 QOF_CHAR_MATCH_ANY = 1, 130 QOF_CHAR_MATCH_NONE 131 } QofCharMatch; 132 133 /** No extended comparisons for QOF_TYPE_INT32, QOF_TYPE_INT64, 134 * QOF_TYPE_DOUBLE, QOF_TYPE_BOOLEAN, QOF_TYPE_KVP 135 */ 136 137 /** Head of Predicate Data structures. All PData must start like this. */ 138 struct _QofQueryPredData 139 { 140 QofType type_name; /* QOF_TYPE_* */ 141 QofQueryCompare how; 142 }; 143 144 145 /** @name Core Data Type Predicates 146 @{ */ 147 QofQueryPredData * 148 qof_query_string_predicate (QofQueryCompare how, 149 const gchar * str, 150 QofStringMatch options, 151 gboolean is_regex); 152 153 QofQueryPredData * 154 qof_query_time_predicate (QofQueryCompare how, 155 QofDateMatch options, 156 QofTime *qt); 157 158 QofQueryPredData * 159 qof_query_numeric_predicate (QofQueryCompare how, 160 QofNumericMatch options, 161 QofNumeric value); 162 163 QofQueryPredData * 164 qof_query_guid_predicate (QofGuidMatch options, 165 GList * guids); 166 167 QofQueryPredData * 168 qof_query_int32_predicate (QofQueryCompare how, gint32 val); 169 170 QofQueryPredData * 171 qof_query_int64_predicate (QofQueryCompare how, gint64 val); 172 173 QofQueryPredData * 174 qof_query_double_predicate (QofQueryCompare how, 175 double val); 176 177 QofQueryPredData * 178 qof_query_boolean_predicate (QofQueryCompare how, 179 gboolean val); 180 181 QofQueryPredData * 182 qof_query_char_predicate (QofCharMatch options, 183 const gchar * chars); 184 185 QofQueryPredData * 186 qof_query_collect_predicate (QofGuidMatch options, 187 QofCollection * coll); 188 189 QofQueryPredData * 190 qof_query_choice_predicate (QofGuidMatch options, 191 GList * guids); 192 193 /** The qof_query_kvp_predicate() matches the object that has 194 * the value 'value' located at the path 'path'. In a certain 195 * sense, the 'path' is handled as if it were a parameter. 196 */ 197 QofQueryPredData * 198 qof_query_kvp_predicate (QofQueryCompare how, 199 GSList * path, 200 const KvpValue * value); 201 202 /** Same predicate as above, except that 'path' is assumed to be 203 * a string containing slash-separated pathname. */ 204 QofQueryPredData * 205 qof_query_kvp_predicate_path (QofQueryCompare how, 206 const gchar * path, 207 const KvpValue * value); 208 209 /** Copy a predicate. */ 210 QofQueryPredData * 211 qof_query_core_predicate_copy (QofQueryPredData * pdata); 212 213 /** Destroy a predicate. */ 214 void qof_query_core_predicate_free (QofQueryPredData * pdata); 215 216 /** Retrieve a predicate. */ 217 gboolean 218 qof_query_time_predicate_get_time (QofQueryPredData * pd, 219 QofTime * qt); 220 221 /** Return a printable string for a core data object. Caller needs 222 * to g_free() the returned string. 223 */ 224 gchar * 225 qof_query_core_to_string (QofType, gpointer object, 226 QofParam * getter); 227 228 #endif /* QOF_QUERYCORE_H */ 229 /* @} */ 230 /* @} */ 231