Branch data Line data Source code
1 : : /********************************************************************\
2 : : * gncInvoice.h -- the Core Business Invoice 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 Invoice
25 : :
26 : : An invoice holds a list of entries, a pointer to the customer,
27 : : and the job, the dates entered and posted, as well as the account,
28 : : transaction and lot for the posted invoice.
29 : : @{ */
30 : : /** @file gncInvoice.h
31 : : @brief Business Invoice Interface
32 : : @author Copyright (C) 2001,2006 Derek Atkins <warlord@MIT.EDU>
33 : : @author Copyright (c) 2005 Neil Williams <linux@codehelp.co.uk>
34 : : */
35 : :
36 : : #ifndef GNC_INVOICE_H_
37 : : #define GNC_INVOICE_H_
38 : :
39 : : struct _gncInvoice;
40 : : typedef struct _gncInvoice GncInvoice;
41 : : typedef struct _gncInvoiceClass GncInvoiceClass;
42 : : typedef GList GncInvoiceList;
43 : :
44 : : #include <glib.h>
45 : : #include "gncBillTerm.h"
46 : : #include "gncEntry.h"
47 : : #include "gncOwner.h"
48 : : #include "gnc-lot.h"
49 : : #include "qofbook.h"
50 : : #include "qofbook.h"
51 : : #include "gnc-pricedb.h"
52 : :
53 : : #ifdef __cplusplus
54 : : extern "C" {
55 : : #endif
56 : :
57 : : #define GNC_ID_INVOICE "gncInvoice"
58 : :
59 : : typedef enum
60 : : {
61 : : GNC_INVOICE_UNDEFINED ,
62 : : GNC_INVOICE_CUST_INVOICE , /* Invoice */
63 : : GNC_INVOICE_VEND_INVOICE , /* Bill */
64 : : GNC_INVOICE_EMPL_INVOICE , /* Voucher */
65 : : GNC_INVOICE_CUST_CREDIT_NOTE , /* Credit Note for a customer */
66 : : GNC_INVOICE_VEND_CREDIT_NOTE , /* Credit Note from a vendor */
67 : : GNC_INVOICE_EMPL_CREDIT_NOTE , /* Credit Note from an employee,
68 : : not sure this makes sense,
69 : : but all code is symmetrical
70 : : so I've added it to prevent unexpected errors */
71 : : GNC_INVOICE_NUM_TYPES
72 : : } GncInvoiceType;
73 : :
74 : : /* --- type macros --- */
75 : : #define GNC_TYPE_INVOICE (gnc_invoice_get_type ())
76 : : #define GNC_INVOICE(o) \
77 : : (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_INVOICE, GncInvoice))
78 : : #define GNC_INVOICE_CLASS(k) \
79 : : (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_INVOICE, GncInvoiceClass))
80 : : #define GNC_IS_INVOICE(o) \
81 : : (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_INVOICE))
82 : : #define GNC_IS_INVOICE_CLASS(k) \
83 : : (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_INVOICE))
84 : : #define GNC_INVOICE_GET_CLASS(o) \
85 : : (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_INVOICE, GncInvoiceClass))
86 : : GType gnc_invoice_get_type(void);
87 : :
88 : : /** @name Create/Destroy Functions
89 : : @{ */
90 : : GncInvoice *gncInvoiceCreate (QofBook *book);
91 : :
92 : : void gncInvoiceDestroy (GncInvoice *invoice);
93 : :
94 : : /** Create a new GncInvoice object as a deep copy of the given other
95 : : * invoice.
96 : : *
97 : : * The returned new invoice has everything copied from the other
98 : : * invoice, including the ID string field. All GncEntries are newly
99 : : * allocated copies of the original invoice's entries. */
100 : : GncInvoice *gncInvoiceCopy (const GncInvoice *other_invoice);
101 : : /** @} */
102 : :
103 : : /** @name Set Functions
104 : : @{ */
105 : : void gncInvoiceSetID (GncInvoice *invoice, const char *id);
106 : : void gncInvoiceSetOwner (GncInvoice *invoice, GncOwner *owner);
107 : : /** Set the DateOpened using a GDate argument. (Note: Internally this stores
108 : : the date in a time64 as created through time64CanonicalDayTime()). */
109 : : void gncInvoiceSetDateOpenedGDate (GncInvoice *invoice, const GDate *date);
110 : : void gncInvoiceSetDateOpened (GncInvoice *invoice, time64 date);
111 : : void gncInvoiceSetDatePosted (GncInvoice *invoice, time64 date);
112 : : void gncInvoiceSetTerms (GncInvoice *invoice, GncBillTerm *terms);
113 : : void gncInvoiceSetBillingID (GncInvoice *invoice, const char *billing_id);
114 : : void gncInvoiceSetNotes (GncInvoice *invoice, const char *notes);
115 : : void gncInvoiceSetDocLink (GncInvoice *invoice, const char *doclink);
116 : : void gncInvoiceSetCurrency (GncInvoice *invoice, gnc_commodity *currency);
117 : : void gncInvoiceSetActive (GncInvoice *invoice, gboolean active);
118 : : void gncInvoiceSetIsCreditNote (GncInvoice *invoice, gboolean credit_note);
119 : : void gncInvoiceSetBillTo (GncInvoice *invoice, GncOwner *billto);
120 : : void gncInvoiceSetToChargeAmount (GncInvoice *invoice, gnc_numeric amount);
121 : : /** @} */
122 : :
123 : : void gncInvoiceAddEntry (GncInvoice *invoice, GncEntry *entry);
124 : : void gncInvoiceRemoveEntry (GncInvoice *invoice, GncEntry *entry);
125 : : void gncInvoiceAddPrice (GncInvoice *invoice, GNCPrice *price);
126 : :
127 : : /** Call this function when adding an entry to a bill instead of an invoice */
128 : : void gncBillAddEntry (GncInvoice *bill, GncEntry *entry);
129 : : void gncBillRemoveEntry (GncInvoice *bill, GncEntry *entry);
130 : :
131 : : /** Call this function when an Entry is changed and you want to
132 : : re-sort the list of entries
133 : : */
134 : : void gncInvoiceSortEntries (GncInvoice *invoice);
135 : :
136 : : /** Remove all entries from an invoice. To be called before
137 : : * destroying an invoice.
138 : : */
139 : : void gncInvoiceRemoveEntries (GncInvoice *invoice);
140 : :
141 : : /** @name Get Functions
142 : : @{ */
143 : : const char * gncInvoiceGetID (const GncInvoice *invoice);
144 : : const GncOwner * gncInvoiceGetOwner (const GncInvoice *invoice);
145 : : time64 gncInvoiceGetDateOpened (const GncInvoice *invoice);
146 : : time64 gncInvoiceGetDatePosted (const GncInvoice *invoice);
147 : : time64 gncInvoiceGetDateDue (const GncInvoice *invoice);
148 : : GncBillTerm * gncInvoiceGetTerms (const GncInvoice *invoice);
149 : : const char * gncInvoiceGetBillingID (const GncInvoice *invoice);
150 : : const char * gncInvoiceGetNotes (const GncInvoice *invoice);
151 : : const char * gncInvoiceGetDocLink (const GncInvoice *invoice);
152 : : GncOwnerType gncInvoiceGetOwnerType (const GncInvoice *invoice);
153 : : GList * gncInvoiceGetTypeListForOwnerType (const GncOwnerType type);
154 : : GncInvoiceType gncInvoiceGetType (const GncInvoice *invoice);
155 : : const char * gncInvoiceGetTypeString (const GncInvoice *invoice);
156 : : gnc_commodity * gncInvoiceGetCurrency (const GncInvoice *invoice);
157 : : GncOwner * gncInvoiceGetBillTo (GncInvoice *invoice);
158 : : gnc_numeric gncInvoiceGetToChargeAmount (const GncInvoice *invoice);
159 : : gboolean gncInvoiceGetActive (const GncInvoice *invoice);
160 : : gboolean gncInvoiceGetIsCreditNote (const GncInvoice *invoice);
161 : :
162 : : GNCLot * gncInvoiceGetPostedLot (const GncInvoice *invoice);
163 : : Transaction * gncInvoiceGetPostedTxn (const GncInvoice *invoice);
164 : : Account * gncInvoiceGetPostedAcc (const GncInvoice *invoice);
165 : : /** @} */
166 : :
167 : : /** Return the "total" amount of the invoice as seen on the document
168 : : * (and shown to the user in the reports and invoice ledger). */
169 : : gnc_numeric gncInvoiceGetTotal (GncInvoice *invoice);
170 : : gnc_numeric gncInvoiceGetTotalOf (GncInvoice *invoice, GncEntryPaymentType type);
171 : : gnc_numeric gncInvoiceGetTotalSubtotal (GncInvoice *invoice);
172 : : gnc_numeric gncInvoiceGetTotalTax (GncInvoice *invoice);
173 : : /** Return a list of tax totals accumulated per tax account.
174 : : */
175 : : AccountValueList *gncInvoiceGetTotalTaxList (GncInvoice *invoice);
176 : :
177 : : typedef GList EntryList;
178 : : EntryList * gncInvoiceGetEntries (GncInvoice *invoice);
179 : : GNCPrice * gncInvoiceGetPrice (GncInvoice *invoice, gnc_commodity* commodity);
180 : :
181 : : /** Depending on the invoice type, invoices have a different effect
182 : : * on the balance. Customer invoices increase the balance, while
183 : : * vendor bills decrease the balance. Credit notes have the opposite
184 : : * effect.
185 : : *
186 : : * Returns TRUE if the invoice will increase the balance or FALSE
187 : : * otherwise.
188 : : */
189 : : gboolean gncInvoiceAmountPositive (const GncInvoice *invoice);
190 : :
191 : : /** Return an overview of amounts on this invoice that will be posted to
192 : : * accounts in currencies that are different from the invoice currency.
193 : : * These accounts can be the accounts referred to in invoice entries
194 : : * or tax tables. This information is returned in the from of a hash
195 : : * table. The keys in the hash table are the foreign currencies, the
196 : : * values are the accumulated amounts in that currency.
197 : : * Drop the reference to the hash table with g_hash_table_unref when
198 : : * no longer needed.
199 : : */
200 : : GHashTable *gncInvoiceGetForeignCurrencies (const GncInvoice *invoice);
201 : :
202 : : /** Post this invoice to an account. Returns the new Transaction
203 : : * that is tied to this invoice. The transaction is set with
204 : : * the supplied posted date, due date, and memo. The Transaction
205 : : * description is set to the name of the company.
206 : : *
207 : : * If accumulate splits is TRUE, entries in the same account
208 : : * will be merged into one single split in that account.
209 : : * Otherwise each entry will be posted as a separate split,
210 : : * possibly resulting in multiple splits in one account.
211 : : *
212 : : * If autopay is TRUE, the code will try to find pre-payments,
213 : : * invoices or credit notes that can reduce the amount due for this
214 : : * invoice, marking the invoice as fully or partially paid, depending
215 : : * on the amounts on all documents involved. If autopay is FALSE,
216 : : * it's the user's responsibility to explicitly pay the invoice.
217 : : *
218 : : */
219 : : Transaction *
220 : : gncInvoicePostToAccount (GncInvoice *invoice, Account *acc,
221 : : time64 posted_date, time64 due_date,
222 : : const char *memo, gboolean accumulatesplits,
223 : : gboolean autopay);
224 : :
225 : : /**
226 : : * Unpost this invoice. This will destroy the posted transaction and
227 : : * return the invoice to its unposted state. It may leave empty lots
228 : : * out there. If reset_tax_tables is TRUE, then it will also revert
229 : : * all the Tax Tables to the parent, which will potentially change the
230 : : * total value of the invoice. It may also leave some orphaned Tax
231 : : * Table children.
232 : : *
233 : : * Returns TRUE if successful, FALSE if there is a problem.
234 : : */
235 : : gboolean
236 : : gncInvoiceUnpost (GncInvoice *invoice, gboolean reset_tax_tables);
237 : :
238 : : /**
239 : : * Attempt to pay the invoice using open payment lots and
240 : : * lots for documents of the opposite sign (credit notes versus
241 : : * invoices).
242 : : */
243 : : void
244 : : gncInvoiceAutoApplyPayments (GncInvoice *invoice);
245 : :
246 : : /**
247 : : * A convenience function to apply a payment to an invoice.
248 : : * It creates a lot for a payment optionally based on an existing
249 : : * transaction and then tries to balance it with
250 : : * the given invoice.
251 : : * Contrary to gncOwnerApplyPayment, no other open documents
252 : : * or payments for the owner will be considered
253 : : * to balance the payment.
254 : : *
255 : : * This code is actually a convenience wrapper around gncOwnerCreatePaymentLotSecs
256 : : * and gncOwnerAutoApplyPaymentsWithLots. See their descriptions for more
257 : : * details on what happens exactly.
258 : : */
259 : : void
260 : : gncInvoiceApplyPayment (const GncInvoice *invoice, Transaction *txn,
261 : : Account *xfer_acc, gnc_numeric amount,
262 : : gnc_numeric exch, time64 date,
263 : : const char *memo, const char *num);
264 : :
265 : :
266 : : /** Given a transaction, find and return the Invoice */
267 : : GncInvoice * gncInvoiceGetInvoiceFromTxn (const Transaction *txn);
268 : :
269 : : /** Given a LOT, find and return the Invoice attached to the lot */
270 : : GncInvoice * gncInvoiceGetInvoiceFromLot (GNCLot *lot);
271 : :
272 : : /** Return a pointer to the instance gncInvoice that is identified
273 : : * by the guid, and is residing in the book. Returns NULL if the
274 : : * instance can't be found.
275 : : */
276 : 2514 : static inline GncInvoice * gncInvoiceLookup (const QofBook *book, const GncGUID *guid)
277 : : {
278 : 2514 : if (book == NULL || guid == NULL) return NULL;
279 : 337 : QOF_BOOK_RETURN_ENTITY(book, guid, GNC_ID_INVOICE, GncInvoice);
280 : : }
281 : :
282 : : void gncInvoiceBeginEdit (GncInvoice *invoice);
283 : : void gncInvoiceCommitEdit (GncInvoice *invoice);
284 : : int gncInvoiceCompare (const GncInvoice *a, const GncInvoice *b);
285 : : gboolean gncInvoiceIsPosted (const GncInvoice *invoice);
286 : : gboolean gncInvoiceIsPaid (const GncInvoice *invoice);
287 : :
288 : : #define INVOICE_ID "id"
289 : : #define INVOICE_OWNER "owner"
290 : : #define INVOICE_OPENED "date_opened"
291 : : #define INVOICE_POSTED "date_posted"
292 : : #define INVOICE_DUE "date_due"
293 : : #define INVOICE_IS_POSTED "is_posted?"
294 : : #define INVOICE_IS_PAID "is_paid?"
295 : : #define INVOICE_TERMS "terms"
296 : : #define INVOICE_BILLINGID "billing_id"
297 : : #define INVOICE_NOTES "notes"
298 : : #define INVOICE_DOCLINK "doclink"
299 : : #define INVOICE_ACC "account"
300 : : #define INVOICE_POST_TXN "posted_txn"
301 : : #define INVOICE_POST_LOT "posted_lot"
302 : : #define INVOICE_IS_CN "credit_note"
303 : : #define INVOICE_TYPE "type"
304 : : #define INVOICE_TYPE_STRING "type_string"
305 : : #define INVOICE_BILLTO "bill-to"
306 : : #define INVOICE_ENTRIES "list_of_entries"
307 : : #define INVOICE_JOB "invoice_job"
308 : :
309 : : #define INVOICE_FROM_LOT "invoice-from-lot"
310 : : #define INVOICE_FROM_TXN "invoice-from-txn"
311 : :
312 : : QofBook *gncInvoiceGetBook (GncInvoice *x);
313 : :
314 : : /** deprecated functions */
315 : : #define gncInvoiceGetGUID(x) qof_instance_get_guid (QOF_INSTANCE(x))
316 : : #define gncInvoiceRetGUID(x) (x ? *(qof_instance_get_guid (QOF_INSTANCE(x))) : *(guid_null()))
317 : :
318 : : /** Test support function used by test-dbi-business-stuff.c */
319 : : gboolean gncInvoiceEqual (const GncInvoice *a, const GncInvoice *b);
320 : :
321 : : #ifdef __cplusplus
322 : : }
323 : : #endif
324 : :
325 : : #endif /* GNC_INVOICE_H_ */
326 : : /** @} */
327 : : /** @} */
|
