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 872 : static inline GncInvoice * gncInvoiceLookup (const QofBook *book, const GncGUID *guid)
277 : {
278 872 : if (book == NULL || guid == NULL) return NULL;
279 137 : 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_JOB "invoice_job"
307 :
308 : #define INVOICE_FROM_LOT "invoice-from-lot"
309 : #define INVOICE_FROM_TXN "invoice-from-txn"
310 :
311 : QofBook *gncInvoiceGetBook (GncInvoice *x);
312 :
313 : /** deprecated functions */
314 : #define gncInvoiceGetGUID(x) qof_instance_get_guid (QOF_INSTANCE(x))
315 : #define gncInvoiceRetGUID(x) (x ? *(qof_instance_get_guid (QOF_INSTANCE(x))) : *(guid_null()))
316 :
317 : /** Test support function used by test-dbi-business-stuff.c */
318 : gboolean gncInvoiceEqual (const GncInvoice *a, const GncInvoice *b);
319 :
320 : #ifdef __cplusplus
321 : }
322 : #endif
323 :
324 : #endif /* GNC_INVOICE_H_ */
325 : /** @} */
326 : /** @} */
|
