1 /******************************************************************** 2 * gnc-engine.h -- top-level include file for Gnucash Engine * 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 /** @addtogroup Engine GnuCash Engine: Core, Non-GUI Accounting Functions 23 The GnuCash Engine provides a set of objects and classes that 24 encapsulate typical financial accounting concepts. The GnuCash 25 GUI is expected to manipulate these objects through the provided 26 engine API. 27 @{ */ 28 /** @file gnc-engine.h 29 @brief All type declarations for the whole Gnucash engine 30 @author Copyright (C) 1997 Robin D. Clark 31 @author Copyright (C) 2000 Bill Gribble <grib@billgribble.com> 32 @author Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu> 33 @author Copyright (C) 1997-2001 Linas Vepstas <linas@linas.org> 34 */ 35 36 #ifndef GNC_ENGINE_H 37 #define GNC_ENGINE_H 38 39 #ifdef __cplusplus 40 extern "C++" { 41 #include <glib.h> 42 } 43 #endif 44 45 #include "qof.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** \name QofLogModule identifiers */ 52 // @{ 53 #define GNC_MOD_ROOT "gnc" 54 #define GNC_MOD_ENGINE "gnc.engine" 55 #define GNC_MOD_ACCOUNT "gnc.account" 56 #define GNC_MOD_SX "gnc.engine.sx" 57 #define GNC_MOD_QUERY "gnc.query" 58 #define GNC_MOD_SCRUB "gnc.scrub" 59 #define GNC_MOD_LOT "gnc.lots" 60 #define GNC_MOD_COMMODITY "gnc.commodity" 61 #define GNC_MOD_BACKEND "gnc.backend" 62 #define GNC_MOD_PRICE "gnc.pricedb" 63 #define GNC_MOD_BUSINESS "gnc.business" 64 #define GNC_MOD_IO "gnc.io" 65 #define GNC_MOD_BOOK "gnc.book-period" 66 #define GNC_MOD_GUI "gnc.gui" 67 #define GNC_MOD_GUI_SX "gnc.gui.sx" 68 #define GNC_MOD_GUILE "gnc.guile" 69 #define GNC_MOD_LEDGER "gnc.ledger" 70 #define GNC_MOD_REGISTER "gnc.register" 71 #define GNC_MOD_HTML "gnc.html" 72 #define GNC_MOD_PREFS "gnc.pref" 73 #define GNC_MOD_IMPORT "gnc.import" 74 #define GNC_MOD_ASSISTANT "gnc.assistant" 75 #define GNC_MOD_BUDGET "gnc.budget" 76 //@} 77 78 /** @brief IDENTIFIERS 79 * GncGUID Identifiers can be used to reference Accounts, Transactions, 80 * Splits and other objects. These Gnucash types are referred to as Gnucash 81 * entities. GncGUID Identifiers are globally-unique and permanent, i.e., once 82 * an entity has been assigned an identifier, it retains that same 83 * identifier for its lifetime. 84 * - 85 * Identifiers are 'typed' with strings. The ids used in gnucash are 86 * defined below. An id with type GNC_ID_NONE does not refer to any 87 * entity, although that may change as new ids are created. An id with 88 * type GNC_ID_NULL does not refer to any entity, and will never refer 89 * to any entity. An identifier with any other type may refer to an 90 * actual entity, but that is not guaranteed. If an id does refer to 91 * an entity, the type of the entity will match the type of the 92 * identifier. 93 */ 94 95 #define GNC_ID_NONE QOF_ID_NONE 96 #define GNC_ID_BOOK QOF_ID_BOOK 97 #define GNC_ID_SESSION QOF_ID_SESSION 98 #define GNC_ID_NULL QOF_ID_NULL 99 100 #define GNC_ID_ACCOUNT "Account" 101 #define GNC_ID_COMMODITY "Commodity" 102 #define GNC_ID_COMMODITY_NAMESPACE "CommodityNamespace" 103 #define GNC_ID_COMMODITY_TABLE "CommodityTable" 104 #define GNC_ID_LOT "Lot" 105 #define GNC_ID_PERIOD "Period" 106 #define GNC_ID_PRICE "Price" 107 #define GNC_ID_PRICEDB "PriceDB" 108 #define GNC_ID_SPLIT "Split" 109 #define GNC_ID_BUDGET "Budget" 110 #define GNC_ID_SCHEDXACTION "SchedXaction" 111 #define GNC_ID_SXES "SchedXactions" 112 #define GNC_ID_SXTG "SXTGroup" 113 #define GNC_ID_SXTT "SXTTrans" 114 #define GNC_ID_TRANS "Trans" 115 116 /* TYPES **********************************************************/ 117 118 /* CAS: ISTM, it would make more sense to put the typedefs in their 119 corresponding header files, (e.g. Account.h), and to #include all 120 the engine API header files right here. After all, when I jump to 121 the definition "Account", I want to end up in Account.h, not this 122 file, like I do now. 123 124 Also, as it is now, if I want to use the engine api, I need to 125 include this header, plus all the other engine headers for the 126 types whose functions I call, so this header is providing almost no 127 benefit of aggregation. But, if it included all the headers I 128 could just include this file. Or would that cause a massive 129 recompile every time one engine header changed? 130 Even if including all the headers here doesn't make sense, I think 131 distributing the stuff in the "Types" section does. 132 */ 133 134 135 /** @brief Account in Gnucash. 136 * This is the typename for an account. The actual structure is 137 * defined in the private header AccountP.h, but no one outside the 138 * engine should include that file. Instead, access that data only 139 * through the functions in Account.h .*/ 140 typedef struct account_s Account; 141 142 /** @brief Split in Gnucash. 143 * A "split" is more commonly referred to as a "entry" in a 144 * "transaction". Each split belongs to one Account and one 145 * Transaction. The split is one out of several parts a Transaction is 146 * divided into. 147 * 148 * This is the typename for a split. The actual structure is defined 149 * in the private header TransactionP.h, but no one outside the engine 150 * should include that file. Instead, access that data only through 151 * the functions in Transaction.h .*/ 152 typedef struct split_s Split; 153 154 /** @brief Transaction in Gnucash. 155 * A Transaction is a piece of business done; the transfer of money 156 * from one account to one or more other accounts. Each Transaction is 157 * divided into one or more Splits (usually two). 158 * 159 * This is the typename for a transaction. The actual structure is 160 * defined in the private header TransactionP.h, but no one outside 161 * the engine should include that file. Instead, access that data only 162 * through the functions in Transaction.h .*/ 163 typedef struct transaction_s Transaction; 164 165 /** @brief An article that is bought and sold. 166 * A Commodity is the most general term of what an account keeps track 167 * of. Usually this is a monetary currency, but it can also be a stock 168 * share or even a precious metal. Every account keeps track of 169 * exactly one gnc_commodity. 170 * 171 * (Up to version 1.6.x, we used to have currencies and 172 * securities. Now these concepts have been merged into this 173 * gnc_commodity. See the comments at xaccAccountSetCommodity() for 174 * more about that.) 175 * 176 * This is the typename for a gnc_commodity. The actual structure is 177 * defined in a private source file. For accessing that data, only use 178 * the functions in gnc-commodity.h .*/ 179 typedef struct gnc_commodity_s gnc_commodity; 180 181 /** @brief A gnc_commodity_namespace is an collection of commodities. */ 182 typedef struct gnc_commodity_namespace_s gnc_commodity_namespace; 183 184 /** @brief A gnc_commodity_table is a database of commodity info. */ 185 typedef struct gnc_commodity_table_s gnc_commodity_table; 186 187 /** @brief Identifies that something sold at one time was bought at another. 188 * A GNCLot provides a way of tracking physical items as they are 189 * bought and sold in different transactions. By identifying 190 * the individual, underlying physical objects, it provides the 191 * needed framework for implementing depreciation, capital gains, 192 * inventory control and invoices. 193 * 194 * See the file src/doc/lots.txt for implementation overview. 195 */ 196 typedef struct gnc_lot_s GNCLot; 197 198 /** @brief Price of commodity on a given date. 199 * A GNCPrice encapsulates price information: the cost of a commodity 200 * expressed as a currency, on a given date. It also holds info about 201 * the provenance of the price: where it came from, its general validity. 202 */ 203 typedef struct gnc_price_s GNCPrice; 204 typedef struct gnc_quote_source_s gnc_quote_source; 205 206 /** GList of Account */ 207 typedef GList AccountList; 208 /** GList of GNCLots */ 209 typedef GList LotList; 210 /** GList of Split */ 211 typedef GList SplitList; 212 /** GList of Transaction */ 213 typedef GList TransList; 214 /** GList of GUIDs of a Account */ 215 typedef GList AccountGUIDList; 216 /** GList of GUIDs of a QofBook */ 217 typedef GList BookGUIDList; 218 219 typedef void (*EngineCommitErrorCallback)( gpointer data, QofBackendError errcode ); 220 221 typedef gint (*SplitCallback)(Split *s, gpointer data); 222 typedef gint (*TransactionCallback)(Transaction *t, void *data); 223 224 /** Function type for init hooks in the engine. */ 225 typedef void (* gnc_engine_init_hook_t)(int, char **); 226 227 228 /** PROTOTYPES ******************************************************/ 229 230 /** gnc_engine_init should be called before gnc engine 231 * functions can be used. */ 232 void gnc_engine_init(int argc, char ** argv); 233 234 /** This is the statically linked-in version of gnc_engine_init. It is 235 * identical to that function except that it doesn't load any backend library. 236 */ 237 void gnc_engine_init_static(int argc, char ** argv); 238 239 /** Called to shutdown the engine. */ 240 void gnc_engine_shutdown (void); 241 242 /** check the engine is fully initialized */ 243 gboolean gnc_engine_is_initialized(void); 244 245 /** enable default log modules */ 246 void gnc_log_default(void); 247 248 /** Pass a function pointer to gnc_engine_add_init_hook and 249 * it will be called during the evaluation of gnc_engine_init */ 250 void gnc_engine_add_init_hook(gnc_engine_init_hook_t hook); 251 252 /** Set a callback function to be called in case an engine commit 253 * fails */ 254 void gnc_engine_add_commit_error_callback( EngineCommitErrorCallback cb, gpointer data ); 255 256 void gnc_engine_signal_commit_error( QofBackendError errcode ); 257 258 /** STRING CONSTANTS ********************************************** 259 * Used to declare constant KVP keys used in more than one class 260 */ 261 #define GNC_INVOICE_ID "gncInvoice" 262 #define GNC_INVOICE_GUID "invoice-guid" 263 #define GNC_OWNER_ID "gncOwner" 264 #define GNC_OWNER_TYPE "owner-type" 265 #define GNC_OWNER_GUID "owner-guid" 266 #define GNC_SX_ID "sched-xaction" 267 268 #ifdef __cplusplus 269 } /* extern "C" */ 270 #endif 271 272 #endif 273 /** @} */ 274