GnuCash  2.6.16
TransactionP.h
1 /********************************************************************\
2  * TransactionP.h -- private header for transaction & splits *
3  * Copyright (C) 1997 Robin D. Clark *
4  * Copyright (C) 1997-2000 Linas Vepstas <linas@linas.org> *
5  * Copyright (C) 2000 Bill Gribble *
6  * *
7  * This program is free software; you can redistribute it and/or *
8  * modify it under the terms of the GNU General Public License as *
9  * published by the Free Software Foundation; either version 2 of *
10  * the License, or (at your option) any later version. *
11  * *
12  * This program is distributed in the hope that it will be useful, *
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
15  * GNU General Public License for more details. *
16  * *
17  * You should have received a copy of the GNU General Public License*
18  * along with this program; if not, contact: *
19  * *
20  * Free Software Foundation Voice: +1-617-542-5942 *
21  * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
22  * Boston, MA 02110-1301, USA gnu@gnu.org *
23  * *
24 \********************************************************************/
25 
26 /*
27  * FILE:
28  * TransactionP.h
29  *
30  * FUNCTION:
31  * The is the *private* transaction header file. Code outside of
32  * engine should *not* include this file. This is because code
33  * outside of the engine should *never* access any of the structure
34  * members directly.
35  *
36  * Note that this header file also defines prototypes for various
37  * routines that perform sub-atomic updates of the accounting
38  * structures. If these routines are not used properly, they
39  * can result in inconsistent, unbalanced accounting structures.
40  * In other words, their use is dangerous, and their use outside
41  * of the scope of the engine is forbidden.
42  *
43  */
44 
45 #ifndef XACC_TRANSACTION_P_H
46 #define XACC_TRANSACTION_P_H
47 
48 #include <time.h>
49 #include <glib.h>
50 
51 #include "gnc-engine.h" /* for typedefs */
52 #include "SplitP.h"
53 #include "qof.h"
54 
55 
57 /*
58  * Double-entry is forced by having at least two splits in every
59  * transaction. By convention, (and only by convention, not by
60  * any innate requirement), the first split is considered to be
61  * the source split or the crediting split, and the others are
62  * the destination, or debiting splits. The grand total of all
63  * of the splits must always be kept zero.
64  */
65 
66 /* A split transaction is one which shows up as a credit (or debit) in
67  * one account, and pieces of it show up as debits (or credits) in other
68  * accounts. Thus, a single credit-card transaction might be split
69  * between "dining", "tips" and "taxes" categories.
70  *
71  * A "split" is more commonly referred to as an "entry" in a "transaction".
72  */
73 
75 {
76  QofInstance inst; /* glbally unique id */
77 
78  Timespec date_entered; /* date register entry was made */
79  Timespec date_posted; /* date transaction was posted at bank */
80 
81  /* The num field is a arbitrary user-assigned field.
82  * It is intended to store a short id number, typically the check number,
83  * deposit number, invoice number or other tracking number.
84  */
85  char * num;
86 
87  /* The description field is an arbitrary user-assigned value.
88  * It is meant to be a short descriptive phrase.
89  */
90  char * description;
91 
92  /* The common_currency field is the balancing common currency for
93  * all the splits in the transaction. Alternate, better(?) name:
94  * "valuation currency": it is the currency in which all of the
95  * splits can be valued. */
96  gnc_commodity *common_currency;
97 
98  GList * splits; /* list of splits */
99 
100  /* marker is used to track the progress of transaction traversals.
101  * 0 is never a legitimate marker value, so we can tell is we hit
102  * a new transaction in the middle of a traversal. All each new
103  * traversal cares about is whether or not the marker stored in
104  * a transaction is the same as or different than the one
105  * corresponding to the current traversal. */
106  unsigned char marker;
107 
108  /* The orig pointer points at a copy of the original transaction,
109  * before editing was started. This orig copy is used to rollback
110  * any changes made if/when the edit is abandoned.
111  */
112  Transaction *orig;
113 };
114 
116 {
117  QofInstanceClass parent_class;
118 };
119 
120 /* Set the transaction's GncGUID. This should only be done when reading
121  * a transaction from a datafile, or some other external source. Never
122  * call this on an existing transaction! */
123 #define xaccTransSetGUID(t,g) qof_instance_set_guid(QOF_INSTANCE(t),g)
124 
125 /* This routine makes a 'duplicate' of the indicated transaction.
126  * This routine cannot be exposed publically since the duplicate
127  * is wrong in many ways: it is not issued a unique guid, and thus
128  * not a properly registered Entity. The splits are copied, but
129  * these are also funny: they aren't inserted into the accounts
130  * they claim to be in. The splits also have bogus GncGUID's.
131  * Another 'feature': the splits point at the old transaction
132  * as the parent, not the new transaction.
133  */
134 Transaction * xaccDupeTransaction (const Transaction *t);
135 
136 /* The xaccTransSet/GetVersion() routines set & get the version
137  * numbers on this transaction. The version number is used to manage
138  * multi-user updates. These routines are private because we don't
139  * want anyone except the backend to mess with them.
140  */
141 void xaccTransSetVersion (Transaction*, gint32);
142 gint32 xaccTransGetVersion (const Transaction*);
143 
144 /* Code to register Transaction type with the engine */
145 gboolean xaccTransRegister (void);
146 
147 /* The xaccTransactionGetBackend() subroutine will find the
148  * persistent-data storage backend associated with this
149  * transaction.
150  */
151 QofBackend * xaccTransactionGetBackend (Transaction *trans);
152 
153 /* The xaccEnable/DisableDataScrubbing() routines affect what
154  * happens during transaction commit. When scrubbing is enabled,
155  * then transactions are fixed up during transaction commit,
156  * so that only consistent transactions are committed to the engine.
157  * However, when data is being loaded from a backend (in particular,
158  * from the file backend), the data might not be consistent until
159  * its completely loaded. In particular, gains transactions might
160  * be loaded at a different time than the transactions that caused
161  * the gains. Thus, scrubbing needs do be disabled during file
162  * load. These routines enable that.
163  */
164 void xaccEnableDataScrubbing(void);
165 void xaccDisableDataScrubbing(void);
166 
172 #define xaccTransSetSlots_nc(T,F) qof_instance_set_slots(QOF_INSTANCE(T),F)
173 
174 void xaccTransRemoveSplit (Transaction *trans, const Split *split);
175 void check_open (const Transaction *trans);
176 
177 /* Structure for accessing static functions for testing */
178 typedef struct
179 {
180  void (*mark_trans)(Transaction*);
181  void (*gen_event_trans)(Transaction*);
182  void (*xaccFreeTransaction)(Transaction*);
183  void (*destroy_gains)(Transaction*);
184  void (*do_destroy)(Transaction*);
185  gboolean (*was_trans_emptied)(Transaction*);
186  void (*trans_on_error)(Transaction*, QofBackendError);
187  void (*trans_cleanup_commit)(Transaction*);
188  void (*xaccTransScrubGainsDate)(Transaction*);
189 
191 
192 TransTestFunctions* _utest_trans_fill_functions (void);
193 
197 #endif /* XACC_TRANSACTION_P_H */
QofBackendError
The errors that can be reported to the GUI & other front-end users.
Definition: qofbackend.h:55
Transaction in Gnucash. A Transaction is a piece of business done; the transfer of money from one acc...
Definition: TransactionP.h:74
All type declarations for the whole Gnucash engine.