1 /********************************************************************\ 2 * Query.h : api for finding transactions * 3 * Copyright 2000 Bill Gribble <grib@billgribble.com> * 4 * Copyright 2002 Linas Vepstas <linas@linas.org> * 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 #ifndef GNUCASH_QUERY_H 25 #define GNUCASH_QUERY_H 26 27 #include <sys/types.h> 28 #include <time.h> 29 #include <glib.h> 30 #include "qof.h" 31 #include "Account.h" 32 33 /* 34 * This function defines a compatibility API from the old Query API to 35 * the new Query API. Note that it is not a 100% complete equivalent. 36 * Many functions have a one-to-one mapping in the new API, but many 37 * others do not. 38 */ 39 40 typedef QofQuery Query; 41 42 typedef enum 43 { 44 QUERY_TXN_MATCH_ALL = 1, /* match all accounts */ 45 QUERY_TXN_MATCH_ANY = 2 /* match any account */ 46 } query_txn_match_t; 47 48 /* After the query has been set up, call one of these to run the query. 49 * XXX The routines below should be replaced by a query 50 * that explicitly asks for a list of the desired item. 51 * 52 * The xaccQueryGetSplits() routine returns all splits matching the 53 * query. Any given split will appear at most once in the result; 54 * however, several splits from one transaction may appear in the list. 55 * The caller MUST NOT change the GList. 56 */ 57 58 /** 59 * The xaccQueryGetSplitsUniqueTrans() routine returns splits matching 60 * the query, but only one matching split per transaction will be 61 * returned. In other words, any given transaction will be 62 * represented at most once in the returned list. The caller must 63 * free the GList. 64 */ 65 SplitList * xaccQueryGetSplitsUniqueTrans(QofQuery *q); 66 67 /** 68 * The xaccQueryGetTransactions() routine returns a list of 69 * transactions that match the query. The GList must be freed by 70 * the caller. The query_run_t argument is used to provide account 71 * matching in the following way: 72 * 73 * query_txn_match_t describes how to match accounts when querying 74 * for transactions with xaccQueryGetTransactions(). 75 * What is the difference between 'ANY' and 'ALL', you 76 * may ask? First, let us recall that a transaction consists 77 * of splits, and each split belongs to exactly one account. 78 * Specifying "MATCH_ALL" means that *every* account that 79 * shows up in the query must also show up in some split in 80 * the transaction (in order for that transaction to be 81 * selected). By contrast, specifying 'ANY' means that 82 * any account in the query must show up in some split 83 * in the transaction (in order for the transaction to 84 * be selected). Thus, 'ANY' acts as a boolean-OR when 85 * matching accounts, whereas 'AND' acts as a boolean-AND 86 * for matching accounts. Whew. Got that? 87 */ 88 TransList * xaccQueryGetTransactions(QofQuery * q, query_txn_match_t type); 89 90 /** 91 * The xaccQueryGetLots() routine is just like GetTransactions() except 92 * it returns a list of Lots. 93 * 94 */ 95 LotList * xaccQueryGetLots(QofQuery * q, query_txn_match_t type); 96 97 /******************************************************************* 98 * match-adding API 99 *******************************************************************/ 100 101 void xaccQueryAddAccountMatch(QofQuery *, AccountList *, 102 QofGuidMatch how, QofQueryOp op); 103 104 void xaccQueryAddAccountGUIDMatch(QofQuery *, AccountGUIDList *, 105 QofGuidMatch, QofQueryOp); 106 107 void xaccQueryAddSingleAccountMatch(QofQuery *, Account *, QofQueryOp); 108 109 void xaccQueryAddStringMatch (QofQuery* q, const char *matchstring, 110 gboolean case_sens, gboolean use_regexp, 111 QofQueryCompare how, QofQueryOp op, 112 const char * path, ...); 113 void 114 xaccQueryAddDescriptionMatch(QofQuery *q, const char *m, gboolean c, gboolean r, 115 QofQueryCompare how, QofQueryOp o); 116 void 117 xaccQueryAddNotesMatch(QofQuery *q, const char *m, gboolean c, gboolean r, 118 QofQueryCompare how, QofQueryOp o); 119 void 120 xaccQueryAddNumberMatch(QofQuery *q, const char *m, gboolean c, gboolean r, 121 QofQueryCompare how, QofQueryOp o); 122 void 123 xaccQueryAddActionMatch(QofQuery *q, const char *m, gboolean c, gboolean r, 124 QofQueryCompare how, QofQueryOp o); 125 void 126 xaccQueryAddMemoMatch(QofQuery *q, const char *m, gboolean c, gboolean r, 127 QofQueryCompare how, QofQueryOp o); 128 void 129 xaccQueryAddValueMatch(QofQuery *q, gnc_numeric amt, QofNumericMatch sgn, 130 QofQueryCompare how, QofQueryOp op); 131 void 132 xaccQueryAddSharePriceMatch(QofQuery *q, gnc_numeric amt, QofQueryCompare how, 133 QofQueryOp op); 134 void 135 xaccQueryAddSharesMatch(QofQuery *q, gnc_numeric amt, QofQueryCompare how, 136 QofQueryOp op); 137 void 138 xaccQueryAddBalanceMatch(QofQuery *q, QofQueryCompare bal, QofQueryOp op); 139 140 void xaccQueryAddNumericMatch (QofQuery *q, gnc_numeric amount, 141 QofNumericMatch sign, QofQueryCompare how, 142 QofQueryOp op, const char * path, ...); 143 144 /** The DateMatch queries match transactions whose posted date 145 * is in a date range. If use_start is TRUE, then a matching 146 * posted date will be greater than the start date. If 147 * use_end is TRUE, then a match occurs for posted dates earlier 148 * than the end date. If both flags are set, then *both* 149 * conditions must hold ('and'). If neither flag is set, then 150 * all transactions are matched. 151 */ 152 153 void xaccQueryAddDateMatch(QofQuery * q, gboolean use_start, 154 int sday, int smonth, int syear, 155 gboolean use_end, int eday, int emonth, int eyear, 156 QofQueryOp op); 157 void xaccQueryAddDateMatchTT(QofQuery * q, 158 gboolean use_start, time64 stt, 159 gboolean use_end, time64 ett, 160 QofQueryOp op); 161 void xaccQueryGetDateMatchTT (QofQuery * q, 162 time64 * stt, 163 time64 * ett); 164 165 void xaccQueryAddClosingTransMatch(QofQuery *q, gboolean value, QofQueryOp op); 166 167 typedef enum 168 { 169 CLEARED_NONE = 0x0000, 170 CLEARED_NO = 0x0001, 171 CLEARED_CLEARED = 0x0002, 172 CLEARED_RECONCILED = 0x0004, 173 CLEARED_FROZEN = 0x0008, 174 CLEARED_VOIDED = 0x0010, 175 CLEARED_ALL = 0x001F 176 } cleared_match_t; 177 178 void xaccQueryAddClearedMatch(QofQuery * q, cleared_match_t how, QofQueryOp op); 179 void xaccQueryAddGUIDMatch(QofQuery * q, const GncGUID *guid, 180 QofIdType id_type, QofQueryOp op); 181 182 183 /******************************************************************* 184 * compatibility interface with old QofQuery API 185 *******************************************************************/ 186 time64 xaccQueryGetEarliestDateFound(QofQuery * q); 187 time64 xaccQueryGetLatestDateFound(QofQuery * q); 188 189 #endif 190