1 /********************************************************************\
2 * gncEntry.h -- the Core Business Entry Interface *
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 Business
23 @{ */
24 /** @addtogroup Entry
25 @{ */
26 /** @file gncEntry.h
27 @brief Business Entry Interface
28 @author Copyright (C) 2001,2002 Derek Atkins <warlord@MIT.EDU>
29 */
30
31 #ifndef GNC_ENTRY_H_
32 #define GNC_ENTRY_H_
33
34 #ifdef __cplusplus
35 extern "C++" {
36 #include <glib.h>
37 }
38 #endif
39
40 typedef struct _gncEntry GncEntry;
41 typedef struct _gncEntryClass GncEntryClass;
42
43 typedef enum
44 {
45 GNC_PAYMENT_CASH = 1,
46 GNC_PAYMENT_CARD
47 } GncEntryPaymentType;
48
49 typedef enum
50 {
51 GNC_DISC_PRETAX = 1,
52 GNC_DISC_SAMETIME,
53 GNC_DISC_POSTTAX
54 } GncDiscountHow;
55
56 typedef GList AccountValueList;
57
58 #include "gncBusiness.h"
59 #include "gncInvoice.h"
60 #include "gncOrder.h"
61 #include "gncTaxTable.h"
62 #include "gncOwner.h"
63
64 #define GNC_ID_ENTRY "gncEntry"
65
66 /* --- type macros --- */
67 #define GNC_TYPE_ENTRY (gnc_entry_get_type ())
68 #define GNC_ENTRY(o) \
69 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_ENTRY, GncEntry))
70 #define GNC_ENTRY_CLASS(k) \
71 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_ENTRY, GncEntryClass))
72 #define GNC_IS_ENTRY(o) \
73 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_ENTRY))
74 #define GNC_IS_ENTRY_CLASS(k) \
75 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_ENTRY))
76 #define GNC_ENTRY_GET_CLASS(o) \
77 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_ENTRY, GncEntryClass))
78 GType gnc_entry_get_type(void);
79
80 /** How to apply the discount and taxes. There are three distinct ways to
81 * apply them:
82 *
83 * Type: discount tax
84 * PRETAX pretax pretax-discount
85 * SAMETIME pretax pretax
86 * POSTTAX pretax+tax pretax
87 */
88
89 const char * gncEntryDiscountHowToString (GncDiscountHow how);
90 gboolean gncEntryDiscountStringToHow (const char *str, GncDiscountHow *how);
91
92 const char * gncEntryPaymentTypeToString (GncEntryPaymentType type);
93 gboolean gncEntryPaymentStringToType (const char *str, GncEntryPaymentType *type);
94
95 /** @name Create/Destroy Functions
96 @{ */
97 GncEntry *gncEntryCreate (QofBook *book);
98 void gncEntryDestroy (GncEntry *entry);
99 /** @} */
100
101 /* SET FUNCTIONS */
102
103 /** @name Generic (shared) data
104 @{ */
105 /** Set the date of this entry */
106 void gncEntrySetDateGDate (GncEntry *entry, const GDate* date);
107 /** DEPRECATED - use gncEntrySetDateGDate() instead! (Because the time-of-day
108 is a misleading extra information. We are only dealing with the day
109 information! */
110 void gncEntrySetDate (GncEntry *entry, time64 date);
111 void gncEntrySetDateEntered (GncEntry *entry, time64 date);
112 void gncEntrySetDescription (GncEntry *entry, const char *desc);
113 void gncEntrySetAction (GncEntry *entry, const char *action);
114 void gncEntrySetNotes (GncEntry *entry, const char *notes);
115 /** Set the internal quantity without any conversion.
116 * This distinction is made because credit notes store their quantity
117 * sign-reversed compared to how the quantity is written on the
118 * actual credit note (and hence how the ledger and reports show it
119 * to the user). */
120 void gncEntrySetQuantity (GncEntry *entry, gnc_numeric quantity);
121 /** Set the internal quantity converting from the quantity as
122 * visible on the physical document.
123 * This distinction is made because credit notes store their quantity
124 * sign-reversed compared to how the quantity is written on the
125 * actual credit note (and hence how the ledger and reports show it
126 * to the user). */
127 void gncEntrySetDocQuantity (GncEntry *entry, gnc_numeric quantity, gboolean is_cn);
128 /** @} */
129
130 /** @name Customer Invoices
131 @{ */
132 void gncEntrySetInvAccount (GncEntry *entry, Account *acc);
133 void gncEntrySetInvPrice (GncEntry *entry, gnc_numeric price);
134 void gncEntrySetInvTaxable (GncEntry *entry, gboolean taxable);
135 void gncEntrySetInvTaxIncluded (GncEntry *entry, gboolean tax_included);
136 void gncEntrySetInvTaxTable (GncEntry *entry, GncTaxTable *table);
137 void gncEntrySetInvDiscount (GncEntry *entry, gnc_numeric discount);
138 void gncEntrySetInvDiscountType (GncEntry *entry, GncAmountType type);
139 void gncEntrySetInvDiscountHow (GncEntry *entry, GncDiscountHow how);
140 void qofEntrySetInvDiscType (GncEntry *entry, const char *type);
141 void qofEntrySetInvDiscHow (GncEntry *entry, const char *type);
142 /** @} */
143
144 /** @name Vendor Bills (and Employee Expenses)
145 @{ */
146 void gncEntrySetBillAccount (GncEntry *entry, Account *acc);
147 void gncEntrySetBillPrice (GncEntry *entry, gnc_numeric price);
148 void gncEntrySetBillTaxable (GncEntry *entry, gboolean taxable);
149 void gncEntrySetBillTaxIncluded (GncEntry *entry, gboolean tax_included);
150 void gncEntrySetBillTaxTable (GncEntry *entry, GncTaxTable *table);
151 void gncEntrySetBillable (GncEntry *entry, gboolean billable);
152 void gncEntrySetBillTo (GncEntry *entry, GncOwner *billto);
153 /** @} */
154
155 /** @name employee-stuff
156 @{ */
157 void gncEntrySetBillPayment (GncEntry *entry, GncEntryPaymentType type);
158 /** @} */
159
160 /* GET FUNCTIONS */
161 /** @name Generic (shared) data
162 @{ */
163 /** Returns the day of this entry */
164 GDate gncEntryGetDateGDate (const GncEntry *entry);
165 /** DEPRECATED - use gncEntryGetDateGDate() instead! (Because the time-of-day
166 is a misleading extra information. We are only dealing with the day
167 information! */
168 time64 gncEntryGetDate (const GncEntry *entry);
169 time64 gncEntryGetDateEntered (const GncEntry *entry);
170 const char * gncEntryGetDescription (const GncEntry *entry);
171 const char * gncEntryGetAction (const GncEntry *entry);
172 const char * gncEntryGetNotes (const GncEntry *notes);
173 /** Get the quantity as stored internally.
174 * This distinction is made because credit notes store their quantity
175 * sign-reversed compared to how the quantity is written on the
176 * actual credit note (and hence how the ledger and reports show it
177 * to the user). */
178 gnc_numeric gncEntryGetQuantity (const GncEntry *entry);
179 /** Get the quantity as on the physical document.
180 * This distinction is made because credit notes store their quantity
181 * sign-reversed compared to how the quantity is written on the
182 * actual credit note (and hence how the ledger and reports show it
183 * to the user). */
184 gnc_numeric gncEntryGetDocQuantity (const GncEntry *entry, gboolean is_cn);
185 /** @} */
186
187 /** @name Customer Invoices
188 @{ */
189 Account * gncEntryGetInvAccount (const GncEntry *entry);
190 gnc_numeric gncEntryGetInvPrice (const GncEntry *entry);
191 gnc_numeric gncEntryGetPrice (const GncEntry *entry, const gboolean cust_doc, const gboolean net);
192 gnc_numeric gncEntryGetInvDiscount (const GncEntry *entry);
193 GncAmountType gncEntryGetInvDiscountType (const GncEntry *entry);
194 GncDiscountHow gncEntryGetInvDiscountHow (const GncEntry *entry);
195 char* qofEntryGetInvDiscType (const GncEntry *entry);
196 char* qofEntryGetInvDiscHow (const GncEntry *entry);
197 gboolean gncEntryGetInvTaxable (const GncEntry *entry);
198 gboolean gncEntryGetInvTaxIncluded (const GncEntry *entry);
199 GncTaxTable * gncEntryGetInvTaxTable (const GncEntry *entry);
200 /** @} */
201
202 /** @name Vendor Bills (and Employee Expenses)
203 @{ */
204 Account * gncEntryGetBillAccount (const GncEntry *entry);
205 gnc_numeric gncEntryGetBillPrice (const GncEntry *entry);
206 gboolean gncEntryGetBillTaxable (const GncEntry *entry);
207 gboolean gncEntryGetBillTaxIncluded (const GncEntry *entry);
208 GncTaxTable * gncEntryGetBillTaxTable (const GncEntry *entry);
209 gboolean gncEntryGetBillable (const GncEntry *entry);
210 GncOwner *gncEntryGetBillTo (GncEntry *entry);
211
212 GncEntryPaymentType gncEntryGetBillPayment (const GncEntry* entry);
213 /** @} */
214
215 void gncEntryCopy (const GncEntry *src, GncEntry *dest, gboolean add_entry);
216
217 /** @name Getting Values
218 *
219 * An entry has three important values:
220 * - entry value: the amount the merchant gets
221 * - tax value: the amount the government gets
222 * - discount value: the amount the customer saved
223 *
224 * These values can be retrieved in several variants. Depending on
225 * how they will be used some sign reversals can be applied on
226 * the values:
227 * - Doc value: the value as listed on the document. This is usually
228 * a positive value, unless the document was a
229 * negative invoice/bill or negative credit note.
230 * Since credit note entry values are stored negatively
231 * internally, they will be sign-reversed before returning
232 * them.
233 * - Bal value: the value as it will impact the balance. Customer
234 * invoices and vendor credit notes have a positive
235 * influence on the balance, so these values will be positive.
236 * For vendor bills and customer credit notes, the
237 * values will be negative.
238 *
239 * For tax there are TaxValue and TaxValues variants: the first one
240 * returns to total tax value for this entry, meaning the sum of all
241 * individual taxes. The second one returns a list of all the individual
242 * tax values for this entry. This list holds unrounded values only, there's
243 * no variant with rounded values.
244 *
245 * Note that this list is not owned by the entry. When no longer needed,
246 * it should be freed with gncAccountValueDestroy.
247 *
248 * Finally, there are rounded and unrounded variants of most of
249 * these functions.
250 @{
251 */
252 gnc_numeric gncEntryGetDocValue (GncEntry *entry, gboolean round, gboolean is_cust_doc, gboolean is_cn);
253 gnc_numeric gncEntryGetDocTaxValue (GncEntry *entry, gboolean round, gboolean is_cust_doc, gboolean is_cn);
254 /** Careful: the returned list is NOT owned by the entry and should be freed by the caller */
255 AccountValueList * gncEntryGetDocTaxValues (GncEntry *entry, gboolean is_cust_doc, gboolean is_cn);
256 gnc_numeric gncEntryGetDocDiscountValue (GncEntry *entry, gboolean round, gboolean is_cust_doc, gboolean is_cn);
257
258 gnc_numeric gncEntryGetBalValue (GncEntry *entry, gboolean round, gboolean is_cust_doc);
259 gnc_numeric gncEntryGetBalTaxValue (GncEntry *entry, gboolean round, gboolean is_cust_doc);
260 /** Careful: the returned list is NOT owned by the entry and should be freed by the caller */
261 AccountValueList * gncEntryGetBalTaxValues (GncEntry *entry, gboolean is_cust_doc);
262 gnc_numeric gncEntryGetBalDiscountValue (GncEntry *entry, gboolean round, gboolean is_cust_doc);
263
264 /** Compute the Entry value, tax_value, and discount_value, based on
265 * the quantity, price, discount, tax_-table, and types. The value is
266 * the amount the merchant gets, the taxes are what the gov't gets,
267 * and the discount is how much the customer saved. The SCU is the
268 * target denominator of the value and tax -- it should be the
269 * account or commodity SCU of the target.
270 *
271 * The return values are NOT rounded.
272 *
273 * If the tax_values list is owned by the entry, it will be destroyed
274 * automatically. Otherwise use gncAccountValueDestroy to free it.
275 */
276 void gncEntryComputeValue (gnc_numeric qty, gnc_numeric price,
277 const GncTaxTable *tax_table, gboolean tax_included,
278 gnc_numeric discount, GncAmountType discount_type,
279 GncDiscountHow discount_how, int SCU,
280 /* return values */
281 gnc_numeric *value, gnc_numeric *discount_value,
282 GList **tax_values);
283
284 /** @} */
285
286 GncOrder * gncEntryGetOrder (const GncEntry *entry);
287 GncInvoice * gncEntryGetInvoice (const GncEntry *entry);
288 GncInvoice * gncEntryGetBill (const GncEntry *entry);
289
290 /** Return a pointer to the instance gncEntry that is identified
291 * by the guid, and is residing in the book. Returns NULL if the
292 * instance can't be found.
293 * Equivalent function prototype is
294 * GncEntry * gncEntryLookup (QofBook *book, const GncGUID *guid);
295 */
gncEntryLookup(const QofBook * book,const GncGUID * guid)296 static inline GncEntry * gncEntryLookup (const QofBook *book, const GncGUID *guid)
297 {
298 QOF_BOOK_RETURN_ENTITY(book, guid, GNC_ID_ENTRY, GncEntry);
299 }
300
301 gboolean gncEntryIsOpen (const GncEntry *entry);
302 void gncEntryBeginEdit (GncEntry *entry);
303 void gncEntryCommitEdit (GncEntry *entry);
304 int gncEntryCompare (const GncEntry *a, const GncEntry *b);
305
306 #define ENTRY_DATE "date"
307 #define ENTRY_DATE_ENTERED "date-entered"
308 #define ENTRY_DESC "desc"
309 #define ENTRY_ACTION "action"
310 #define ENTRY_NOTES "notes"
311 #define ENTRY_QTY "qty"
312
313 #define ENTRY_IPRICE "iprice"
314 #define ENTRY_IACCT "invoice-account"
315 #define ENTRY_BACCT "bill-account"
316 #define ENTRY_BPRICE "bprice"
317 #define ENTRY_BILLABLE "billable?"
318 #define ENTRY_BILLTO "bill-to"
319
320 #define ENTRY_ORDER "order"
321 #define ENTRY_INVOICE "invoice"
322 #define ENTRY_BILL "bill"
323
324 #define ENTRY_INV_DISC_TYPE "discount-type"
325 #define ENTRY_INV_DISC_HOW "discount-method"
326
327 #define ENTRY_INV_TAXABLE "invoice-taxable"
328 #define ENTRY_BILL_TAXABLE "bill-taxable"
329 #define ENTRY_INV_TAX_INC "invoice-tax-included"
330 #define ENTRY_BILL_TAX_INC "bill-tax-included"
331 #define ENTRY_INV_DISCOUNT "invoice-discount"
332 #define ENTRY_BILL_PAY_TYPE "bill-payment-type"
333
334
335 /* deprecated functions, should be removed */
336 #define gncEntryGetGUID(x) qof_instance_get_guid(QOF_INSTANCE(x))
337
338 #endif /* GNC_ENTRY_H_ */
339 /** @} */
340 /** @} */
341