1 /********************************************************************\ 2 * This program is free software; you can redistribute it and/or * 3 * modify it under the terms of the GNU General Public License as * 4 * published by the Free Software Foundation; either version 2 of * 5 * the License, or (at your option) any later version. * 6 * * 7 * This program is distributed in the hope that it will be useful, * 8 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 10 * GNU General Public License for more details. * 11 * * 12 * You should have received a copy of the GNU General Public License* 13 * along with this program; if not, contact: * 14 * * 15 * Free Software Foundation Voice: +1-617-542-5942 * 16 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 17 * Boston, MA 02110-1301, USA gnu@gnu.org * 18 * * 19 \********************************************************************/ 20 /** @addtogroup Engine 21 @{ */ 22 /** @addtogroup Transaction Transaction, Split 23 A good overview of transactions, splits and accounts can be 24 found in the texinfo documentation, together with an overview of 25 how to use this API. 26 27 Splits, or "Ledger Entries" are the fundamental 28 accounting units. Each Split consists of an amount (number of dollar 29 bills, number of shares, etc.), the value of that amount expressed in 30 a (possibly) different currency than the amount, a Memo, a pointer to 31 the parent Transaction, a pointer to the debited Account, a reconciled 32 flag and timestamp, an "Action" field, and a key-value frame which can 33 store arbitrary data. 34 35 Transactions embody the notion of "double entry" accounting. 36 A Transaction consists of a date, a description, an ID number, 37 a list of one or more Splits, and a key-value frame. The transaction 38 also specifies the currency with which all of the splits will be valued. 39 When double-entry rules are enforced, the sum total value of the splits 40 are zero. If there are only two splits, then the value of one must be 41 positive, the other negative: this denotes that one account is debited, 42 and another is credited by an equal amount. By forcing the value of the 43 splits to always 'add up' to zero, we can guarantee that the balances 44 of the accounts are always correctly balanced. 45 46 The engine does not enforce double-entry accounting, but provides an API 47 to enable user-code to find unbalanced transactions and 'repair' them so 48 that they are in balance. 49 50 Note the sum of the values of Splits in a Transaction is always computed 51 with respect to a currency; thus splits can be balanced even when they 52 are in different currencies, as long as they share a common currency. 53 This feature allows currency-trading accounts to be established. 54 55 Every Split must point to its parent Transaction, and that Transaction 56 must in turn include that Split in the Transaction's list of Splits. A 57 Split can belong to at most one Transaction. These relationships are 58 enforced by the engine. The engine user cannot accidentally destroy 59 this relationship as long as they stick to using the API and never 60 access internal structures directly. 61 62 Splits are grouped into Accounts which are also known 63 as "Ledgers" in accounting practice. Each Account consists of a list of 64 Splits that debit that Account. To ensure consistency, if a Split points 65 to an Account, then the Account must point to the Split, and vice-versa. 66 A Split can belong to at most one Account. Besides merely containing a 67 list of Splits, the Account structure also gives the Account a name, a 68 code number, description and notes fields, a key-value frame, a pointer 69 to the commodity that is used for all splits in this account. The 70 commodity can be the name of anything traded and tradable: a stock 71 (e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or anything 72 added to the commodity table. 73 74 Accounts can be arranged in a hierarchical tree. The nodes of the tree 75 are called "Account Groups". By accounting 76 convention, the value of an Account is equal to the value of all of its 77 Splits plus the value of all of its sub-Accounts. 78 79 @{ */ 80 /** @file Transaction.h 81 @brief API for Transactions and Splits (journal entries) 82 @author Copyright (C) 1997 Robin D. Clark 83 @author Copyright (C) 1997-2001 Linas Vepstas <linas@linas.org> 84 */ 85 86 #ifndef XACC_TRANSACTION_H 87 #define XACC_TRANSACTION_H 88 89 typedef struct _TransactionClass TransactionClass; 90 91 #include <time.h> 92 93 #include "gnc-commodity.h" 94 #include "gnc-engine.h" 95 #include "gnc-pricedb.h" 96 #include "Split.h" 97 98 #ifdef __cplusplus 99 extern "C" { 100 #endif 101 102 /* --- type macros --- */ 103 #define GNC_TYPE_TRANSACTION (gnc_transaction_get_type ()) 104 #define GNC_TRANSACTION(o) \ 105 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_TRANSACTION, Transaction)) 106 #define GNC_TRANSACTION_CLASS(k) \ 107 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_TRANSACTION, TransactionClass)) 108 #define GNC_IS_TRANSACTION(o) \ 109 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_TRANSACTION)) 110 #define GNC_IS_TRANSACTION_CLASS(k) \ 111 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_TRANSACTION)) 112 #define GNC_TRANSACTION_GET_CLASS(o) \ 113 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_TRANSACTION, TransactionClass)) 114 GType gnc_transaction_get_type(void); 115 116 117 /* FIXME: These macros are not consistent with the type name */ 118 #define GNC_IS_TRANS(obj) GNC_IS_TRANSACTION(obj) 119 #define GNC_TRANS(obj) GNC_TRANSACTION(obj) 120 121 /** @name Transaction Type field values 122 @{ 123 */ 124 #define TXN_TYPE_NONE '\0' /**< No transaction type */ 125 #define TXN_TYPE_INVOICE 'I' /**< Transaction is an invoice */ 126 #define TXN_TYPE_PAYMENT 'P' /**< Transaction is a payment */ 127 #define TXN_TYPE_LINK 'L' /**< Transaction is a link between (invoice and payment) lots */ 128 /** @} */ 129 130 /* --------------------------------------------------------------- */ 131 /* Transactions */ 132 133 /** @name Transaction creation and editing 134 @{ 135 */ 136 /** 137 The xaccMallocTransaction() will malloc memory and initialize it. 138 Once created, it is usually unsafe to merely "free" this memory; 139 the xaccTransDestroy() method should be called. */ 140 Transaction * xaccMallocTransaction (QofBook *book); 141 142 /** Destroys a transaction. 143 * Each split in transaction @a trans is removed from its 144 * account and destroyed as well. 145 * 146 * If the transaction has not already been opened for editing with 147 * ::xaccTransBeginEdit() then the changes are committed immediately. 148 * Otherwise, the caller must follow up with either 149 * ::xaccTransCommitEdit(), in which case the transaction and 150 * split memory will be freed, or xaccTransRollbackEdit(), in which 151 * case nothing at all is freed, and everything is put back into 152 * original order. 153 * 154 * @param trans the transaction to destroy 155 */ 156 void xaccTransDestroy (Transaction *trans); 157 158 /** 159 The xaccTransClone() method will create a complete copy of an 160 existing transaction. 161 */ 162 Transaction * xaccTransClone (const Transaction *t); 163 164 /** 165 The xaccTransCloneNoKvp() method will create a complete copy of an 166 existing transaction except that the KVP slots will be empty. 167 */ 168 Transaction * xaccTransCloneNoKvp (const Transaction *t); 169 170 /** Equality. 171 * 172 * @param ta First transaction to compare 173 * @param tb Second transaction to compare 174 * 175 * @param check_guids If TRUE, try a guid_equal() on the GUIDs of both 176 * transactions if their pointers are not equal in the first place. 177 * Also passed to subsidiary calls to xaccSplitEqual. 178 * 179 * @param check_splits If TRUE, after checking the transaction data 180 * structures for equality, also check all splits attached to the 181 * transaction for equality. 182 * 183 * @param check_balances If TRUE, when checking splits also compare 184 * balances between the two splits. Balances are recalculated 185 * whenever a split is added or removed from an account, so YMMV on 186 * whether this should be set. 187 * 188 * @param assume_ordered If TRUE, assume that the splits in each 189 * transaction appear in the same order. This saves some time looking 190 * up splits by GncGUID, and is required for checking duplicated 191 * transactions because all the splits have new GUIDs. 192 */ 193 gboolean xaccTransEqual(const Transaction *ta, 194 const Transaction *tb, 195 gboolean check_guids, 196 gboolean check_splits, 197 gboolean check_balances, 198 gboolean assume_ordered); 199 200 /** The xaccTransBeginEdit() method must be called before any changes 201 are made to a transaction or any of its component splits. If 202 this is not done, errors will result. */ 203 void xaccTransBeginEdit (Transaction *trans); 204 205 /** The xaccTransCommitEdit() method indicates that the changes to the 206 transaction and its splits are complete and should be made 207 permanent. Note this routine may result in the deletion of the 208 transaction, if the transaction is "empty" (has no splits), or 209 of xaccTransDestroy() was called on the transaction. */ 210 void xaccTransCommitEdit (Transaction *trans); 211 212 /** The xaccTransRollbackEdit() routine rejects all edits made, and 213 sets the transaction back to where it was before the editing 214 started. This includes restoring any deleted splits, removing 215 any added splits, and undoing the effects of xaccTransDestroy, 216 as well as restoring share quantities, memos, descriptions, etc. */ 217 void xaccTransRollbackEdit (Transaction *trans); 218 219 /** The xaccTransIsOpen() method returns TRUE if the transaction 220 is open for editing. Otherwise, it returns false. 221 XXX this routine should probably be deprecated. its, umm, 222 hard to imagine legitimate uses (but it is used by 223 the import/export code for reasons I can't understand.) 224 */ 225 gboolean xaccTransIsOpen (const Transaction *trans); 226 227 /** The xaccTransLookup() subroutine will return the 228 transaction associated with the given id, or NULL 229 if there is no such transaction. */ 230 /*@ dependent @*//*@ null @*/ 231 Transaction * xaccTransLookup (const GncGUID *guid, QofBook *book); 232 #define xaccTransLookupDirect(g,b) xaccTransLookup(&(g),b) 233 234 /*################## Added for Reg2 #################*/ 235 236 /** Copy a transaction to the 'clipboard' transaction using 237 * dupe_transaction. The 'clipboard' transaction must never 238 * be dereferenced. 239 */ 240 Transaction * xaccTransCopyToClipBoard(const Transaction *from_trans); 241 242 /** Copy a transaction to another using the function below without 243 * changing any account information. 244 */ 245 void xaccTransCopyOnto(const Transaction *from_trans, Transaction *to_trans); 246 247 /** This function explicitly must robustly handle some unusual input. 248 * 249 * 'from_trans' may be a duped trans (see xaccDupeTransaction), so its 250 * splits may not really belong to the accounts that they say they do. 251 * 252 * 'from_acc' need not be a valid account. It may be an already freed 253 * Account. Therefore, it must not be dereferenced at all. 254 * 255 * Neither 'from_trans', nor 'from_acc', nor any of 'from's splits may be modified 256 * in any way. 257 * 258 * 'no_date' if TRUE will not copy the date posted. 259 * 260 * The 'to_trans' transaction will end up with valid copies of from's 261 * splits. In addition, the copies of any of from's splits that were 262 * in from_acc (or at least claimed to be) will end up in to_acc. 263 */ 264 void xaccTransCopyFromClipBoard(const Transaction *from_trans, Transaction *to_trans, 265 const Account *from_acc, Account *to_acc, gboolean no_date); 266 267 /*################## Added for Reg2 #################*/ 268 269 270 Split * xaccTransFindSplitByAccount(const Transaction *trans, 271 const Account *acc); 272 273 /** The xaccTransScrubGains() routine performs a number of cleanup 274 * functions on the indicated transaction, with the end-goal of 275 * setting up a consistent set of gains/losses for all the splits 276 * in the transaction. This includes making sure that the lot 277 * assignments of all the splits are good, and that the lots 278 * balance appropriately. 279 */ 280 void xaccTransScrubGains (Transaction *trans, Account *gain_acc); 281 282 283 /** \warning XXX FIXME 284 * gnc_book_count_transactions is a utility function, 285 * probably needs to be moved to a utility file somewhere. 286 */ 287 guint gnc_book_count_transactions(QofBook *book); 288 289 /** @} */ 290 291 292 /** @name Transaction general getters/setters 293 @{ 294 */ 295 296 /** Determine whether this transaction should use commodity trading accounts 297 */ 298 gboolean xaccTransUseTradingAccounts(const Transaction *trans); 299 300 /** Sorts the splits in a transaction, putting the debits first, 301 * followed by the credits. 302 */ 303 void xaccTransSortSplits (Transaction *trans); 304 305 /** Set the Transaction Type 306 * 307 * See #TXN_TYPE_NONE, #TXN_TYPE_INVOICE and #TXN_TYPE_PAYMENT */ 308 void xaccTransSetTxnType (Transaction *trans, char type); 309 /** Returns the Transaction Type 310 * 311 * See #TXN_TYPE_NONE, #TXN_TYPE_INVOICE and #TXN_TYPE_PAYMENT */ 312 char xaccTransGetTxnType (const Transaction *trans); 313 314 /** Sets the transaction Number (or ID) field; rather than use this function 315 * directly, see 'gnc_set_num_action' in engine/engine-helpers.c & .h which 316 * takes a user-set book option for selecting the source for the num-cell (the 317 * transaction-number or the split-action field) in registers/reports into 318 * account automatically */ 319 void xaccTransSetNum (Transaction *trans, const char *num); 320 321 /** Sets the transaction Description */ 322 void xaccTransSetDescription (Transaction *trans, const char *desc); 323 324 /** Sets the transaction Document Link */ 325 void xaccTransSetDocLink (Transaction *trans, const char *doclink); 326 327 /** Sets the transaction Notes 328 * 329 The Notes field is only visible in the register in double-line mode */ 330 void xaccTransSetNotes (Transaction *trans, const char *notes); 331 332 /** Gets the transaction Number (or ID) field; rather than use this function 333 * directly, see 'gnc_get_num_action' and 'gnc_get_action_num' in 334 * engine/engine-helpers.c & .h which takes a user-set book option for 335 * selecting the source for the num-cell (the transaction-number or the 336 * split-action field) in registers/reports into account automatically */ 337 const char * xaccTransGetNum (const Transaction *trans); 338 /** Gets the transaction Description */ 339 const char * xaccTransGetDescription (const Transaction *trans); 340 /** Gets the transaction Document Link */ 341 const char * xaccTransGetDocLink(const Transaction *trans); 342 /** Gets the transaction Notes 343 * 344 The Notes field is only visible in the register in double-line mode */ 345 const char * xaccTransGetNotes (const Transaction *trans); 346 347 348 /** Sets whether or not this transaction is a "closing transaction" */ 349 void xaccTransSetIsClosingTxn (Transaction *trans, gboolean is_closing); 350 351 /** Returns whether this transaction is a "closing transaction" */ 352 gboolean xaccTransGetIsClosingTxn (const Transaction *trans); 353 354 355 /** Add a split to the transaction 356 * 357 The xaccTransAppendSplit() method will append the indicated 358 split to the collection of splits in this transaction. 359 @note If the split is already a part of another transaction, 360 it will be removed from that transaction first. 361 */ 362 #define xaccTransAppendSplit(t, s) xaccSplitSetParent((s), (t)) 363 364 /** Return a pointer to the indexed split in this transaction's split list. 365 366 Note that the split list is a linked list and that indexed access is 367 O(N). Do not use this method for iteration. 368 @param trans The transaction 369 @param i The split number. Valid values for i are zero to 370 (number_of__splits-1). 371 @return A Split* or NULL if i is out of range. 372 */ 373 Split* xaccTransGetSplit (const Transaction *trans, int i); 374 375 /** Inverse of xaccTransGetSplit() */ 376 int xaccTransGetSplitIndex(const Transaction *trans, const Split *split); 377 378 /** The xaccTransGetSplitList() method returns a GList of the splits 379 in a transaction. 380 @param trans The transaction 381 @return The list of splits. This list must NOT be modified. Do *NOT* free 382 this list when you are done with it. */ 383 /*@ dependent @*/ 384 SplitList * xaccTransGetSplitList (const Transaction *trans); 385 386 /** The xaccTransGetPaymentAcctSplitList() method returns a GList of the splits 387 in a transaction that belong to an account which is considered a 388 valid account for business payments. 389 @param trans The transaction 390 @return The list of splits. This list must be freed when you are done with it. */ 391 SplitList * xaccTransGetPaymentAcctSplitList (const Transaction *trans); 392 393 /** The xaccTransGetAPARSplitList() method returns a GList of the splits 394 in a transaction that belong to an AR or AP account. 395 @param trans The transaction 396 @param strict This slightly modifies the test to only consider splits in an AR or AP account and the split is part of a business lot 397 @return The list of splits. This list must be freed when you are done with it. */ 398 SplitList * xaccTransGetAPARAcctSplitList (const Transaction *trans, gboolean strict); 399 400 401 gboolean xaccTransStillHasSplit(const Transaction *trans, const Split *s); 402 403 /** The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first 404 split in this transaction that belongs to an account which is considered a 405 valid account for business payments. 406 @param trans The transaction 407 408 If there is no such split in the transaction NULL will be returned. */ 409 Split * xaccTransGetFirstPaymentAcctSplit (const Transaction *trans); 410 411 /** The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first 412 split in this transaction that belongs to an AR or AP account. 413 @param trans The transaction 414 @param strict This slightly modifies the test to only consider splits in an AR or AP account and the split is part of a business lot 415 416 If there is no such split in the transaction NULL will be returned. */ 417 Split * xaccTransGetFirstAPARAcctSplit (const Transaction *trans, gboolean strict); 418 419 /** Set the transaction to be ReadOnly by setting a non-NULL value as "reason". 420 * 421 * FIXME: If "reason" is NULL, this function does nothing, instead of removing the 422 * readonly flag; the actual removal is possible only through 423 * xaccTransClearReadOnly(). */ 424 void xaccTransSetReadOnly (Transaction *trans, const char *reason); 425 void xaccTransClearReadOnly (Transaction *trans); 426 427 /** Returns a non-NULL value if this Transaction was marked as read-only with 428 * some specific "reason" text. */ 429 const char * xaccTransGetReadOnly (Transaction *trans); 430 431 /** Returns TRUE if this Transaction is read-only because its posted-date is 432 * older than the "auto-readonly" threshold of this book. See 433 * qof_book_uses_autofreeze() and qof_book_get_autofreeze_gdate(). */ 434 gboolean xaccTransIsReadonlyByPostedDate(const Transaction *trans); 435 436 /*################## Added for Reg2 #################*/ 437 438 /** Returns TRUE if this Transaction's posted-date is in the future */ 439 gboolean xaccTransInFutureByPostedDate (const Transaction *trans); 440 441 /*################## Added for Reg2 #################*/ 442 443 /** Returns the number of splits in this transaction. */ 444 int xaccTransCountSplits (const Transaction *trans); 445 446 /** FIXME: document me */ 447 gboolean xaccTransHasReconciledSplits (const Transaction *trans); 448 /** FIXME: document me */ 449 gboolean xaccTransHasReconciledSplitsByAccount (const Transaction *trans, 450 const Account *account); 451 452 /** FIXME: document me */ 453 gboolean xaccTransHasSplitsInState (const Transaction *trans, const char state); 454 /** FIXME: document me */ 455 gboolean xaccTransHasSplitsInStateByAccount (const Transaction *trans, 456 const char state, 457 const Account *account); 458 459 460 /** Returns the valuation commodity of this transaction. 461 * 462 * Each transaction's valuation commodity, or 'currency' is, by definition, 463 * the common currency in which all splits in the transaction can be valued. 464 * The total value of the transaction must be zero when all splits 465 * are valued in this currency. 466 * @note What happens if the Currency isn't set? Ans: bad things. */ 467 /*@ dependent @*/ 468 gnc_commodity * xaccTransGetCurrency (const Transaction *trans); 469 470 /** Set the commodity of this transaction. */ 471 void xaccTransSetCurrency (Transaction *trans, gnc_commodity *curr); 472 473 /** The xaccTransGetImbalanceValue() method returns the total value of the 474 * transaction. In a pure double-entry system, this imbalance 475 * should be exactly zero, and if it is not, something is broken. 476 * However, when double-entry semantics are not enforced, unbalanced 477 * transactions can sneak in, and this routine can be used to find 478 * out how much things are off by. The value returned is denominated 479 * in the currency that is returned by the xaccTransFindCommonCurrency() 480 * method. 481 * 482 * If the use of currency exchange accounts is enabled then the a 483 * a transaction must be balanced in each currency it uses to be considered 484 * to be balanced. The method xaccTransGetImbalance is used by most 485 * code to take this into consideration. This method is only used in a few 486 * places that want the transaction value even if currency exchange accounts 487 * are enabled. */ 488 gnc_numeric xaccTransGetImbalanceValue (const Transaction * trans); 489 490 /** The xaccTransGetImbalance method returns a list giving the value of 491 * the transaction in each currency for which the balance is not zero. 492 * If the use of currency accounts is disabled, then this will be only 493 * the common currency for the transaction and xaccTransGetImbalance 494 * becomes equivalent to xaccTransGetImbalanceValue. Otherwise it will 495 * return a list containing the imbalance in each currency. */ 496 MonetaryList *xaccTransGetImbalance (const Transaction * trans); 497 498 /** Returns true if the transaction is balanced according to the rules 499 * currently in effect. */ 500 gboolean xaccTransIsBalanced(const Transaction * trans); 501 502 /** The xaccTransGetAccountValue() method returns the total value applied 503 * to a particular account. In some cases there may be multiple Splits 504 * in a single Transaction applied to one account (in particular when 505 * trying to balance Lots) -- this function is just a convenience to 506 * view everything at once. 507 */ 508 gnc_numeric xaccTransGetAccountValue (const Transaction *trans, 509 const Account *account); 510 511 /** Same as xaccTransGetAccountValue, but uses the Account's commodity. */ 512 gnc_numeric xaccTransGetAccountAmount (const Transaction *trans, 513 const Account *account); 514 515 /*################## Added for Reg2 #################*/ 516 /* Gets the amt/val rate, i.e. rate from the transaction currency to 517 the 'split_com' */ 518 gboolean 519 xaccTransGetRateForCommodity(const Transaction *trans, 520 const gnc_commodity *split_com, 521 const Split *split_to_exclude, gnc_numeric *rate); 522 /*################## Added for Reg2 #################*/ 523 524 /* Compute the conversion rate for the transaction to this account. 525 * Any "split value" (which is in the transaction currency), 526 * multiplied by this conversion rate, will give you the value you 527 * should display for this account. 528 * 529 * If 'acc' is NULL, return unity. 530 */ 531 gnc_numeric xaccTransGetAccountConvRate(const Transaction *txn, const Account *acc); 532 533 /** Get the account balance for the specified account after the last 534 split in the specified transaction. */ 535 gnc_numeric xaccTransGetAccountBalance (const Transaction *trans, 536 const Account *account); 537 538 /** 539 * The xaccTransOrder(ta,tb) method is useful for sorting. 540 * Orders ta and tb 541 * return <0 if ta sorts before tb 542 * return >0 if ta sorts after tb 543 * return 0 if they are absolutely equal 544 * 545 * The comparrison uses the following fields, in order: 546 * date posted (compare as a date) 547 * num field (compare as an integer) 548 * date entered (compare as a date) 549 * description field (comcpare as a string using strcmp()) 550 * GncGUID (compare as a guid) 551 * Finally, it returns zero if all of the above match. 552 * Note that it does *NOT* compare its member splits. 553 * Note also that it calls xaccTransOrder_num_action with actna and actnb 554 * set as NULL. 555 */ 556 int xaccTransOrder (const Transaction *ta, const Transaction *tb); 557 558 559 /** 560 * The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting. 561 * Orders ta and tb 562 * return <0 if ta sorts before tb 563 * return >0 if ta sorts after tb 564 * return 0 if they are absolutely equal 565 * 566 * The comparrison uses the following fields, in order: 567 * date posted (compare as a date) 568 * if actna and actnb are NULL, 569 * num field (compare as an integer) 570 * else actna and actnb (compare as an integer) 571 * date entered (compare as a date) 572 * description field (comcpare as a string using strcmp()) 573 * GncGUID (compare as a guid) 574 * Finally, it returns zero if all of the above match. 575 * Note that it does *NOT* compare its member splits (except action as 576 * specified above). 577 */ 578 int xaccTransOrder_num_action (const Transaction *ta, const char *actna, 579 const Transaction *tb, const char *actnb); 580 581 /** @} */ 582 583 584 /** @name Transaction date setters/getters 585 @{ 586 */ 587 588 /** The xaccTransSetDate() method does the same thing as 589 xaccTransSetDate[Posted]Secs(), but takes a convenient 590 day-month-year format. 591 592 (Footnote: this shouldn't matter to a user, but anyone modifying 593 the engine should understand that when xaccTransCommitEdit() is 594 called, the date order of each of the component splits will be 595 checked, and will be restored in ascending date order.) 596 */ 597 void xaccTransSetDate (Transaction *trans, 598 int day, int mon, int year); 599 600 /** This method modifies <i>posted</i> date of the transaction, 601 * specified by a GDate. The posted date is the date when this 602 * transaction was posted at the bank. 603 * 604 * This is identical to xaccTransSetDate(), but different from 605 * xaccTransSetDatePostedSecs which artificially introduces the 606 * time-of-day part, which needs to be ignored. */ 607 void xaccTransSetDatePostedGDate (Transaction *trans, GDate date); 608 609 /** The xaccTransSetDatePostedSecs() method will modify the <i>posted</i> 610 * date of the transaction, specified by a time64 (see ctime(3)). The 611 * posted date is the date when this transaction was posted at the 612 * bank. 613 * 614 * Please do not use this function, as the extra time-of-day part messes up a 615 * lot of places. Rather, please use xaccTransSetDatePostedGDate() or 616 * xaccTransSetDatePostedSecsNormalized(). 617 */ 618 void xaccTransSetDatePostedSecs (Transaction *trans, time64 time); 619 620 /** This function sets the <i>posted</i> date of the transaction, specified by 621 * a time64 (see ctime(3)). Contrary to xaccTransSetDatePostedSecs(), the time 622 * will be normalized to only the date part, and the time-of-day will be 623 * ignored. The resulting date is the same as if it had been set as a GDate 624 * through xaccTransSetDatePostedGDate(). 625 * 626 * Please prefer this function over xaccTransSetDatePostedSecs(). 627 * 628 * The posted date is the date when this transaction was posted at the bank. */ 629 void xaccTransSetDatePostedSecsNormalized (Transaction *trans, time64 time); 630 631 /** Modify the date of when the transaction was entered. The entered 632 * date is the date when the register entry was made. */ 633 void xaccTransSetDateEnteredSecs (Transaction *trans, time64 time); 634 635 /** Dates and txn-type for A/R and A/P "invoice" postings */ 636 void xaccTransSetDateDue (Transaction * trans, time64 time); 637 638 /** Retrieve the posted date of the transaction. The posted date is 639 the date when this transaction was posted at the bank. (Although 640 having different function names, GetDate and GetDatePosted refer 641 to the same single date.)*/ 642 time64 xaccTransGetDate (const Transaction *trans); 643 /** Retrieve the posted date of the transaction. The posted date is 644 the date when this transaction was posted at the bank. (Although 645 having different function names, GetDate and GetDatePosted refer 646 to the same single date.)*/ 647 time64 xaccTransRetDatePosted (const Transaction *trans); 648 /** Retrieve the posted date of the transaction. The posted date is 649 the date when this transaction was posted at the bank. */ 650 GDate xaccTransGetDatePostedGDate (const Transaction *trans); 651 652 /*################## Added for Reg2 #################*/ 653 /** Retrieve the date of when the transaction was entered. The entered 654 * date is the date when the register entry was made.*/ 655 time64 xaccTransGetDateEntered (const Transaction *trans); 656 /*################## Added for Reg2 #################*/ 657 /** Retrieve the date of when the transaction was entered. The entered 658 * date is the date when the register entry was made.*/ 659 time64 xaccTransRetDateEntered (const Transaction *trans); 660 661 /** Dates and txn-type for A/R and A/P "invoice" postings */ 662 time64 xaccTransRetDateDue (const Transaction *trans); 663 /** @} */ 664 665 666 667 /********************************************************************\ 668 * Miscellaneous utility routines. 669 \********************************************************************/ 670 671 672 /** @name Transaction voiding 673 @{ 674 */ 675 /** xaccTransVoid voids a transaction. A void transaction has no 676 * values, is unaffected by reconciliation, and, by default is not 677 * included in any queries. A voided transaction may not be altered. 678 * 679 * @param transaction The transaction to void. 680 * 681 * @param reason The textual reason why this transaction is being 682 * voided. 683 */ 684 void xaccTransVoid(Transaction *transaction, 685 const char *reason); 686 687 /** xaccTransUnvoid restores a voided transaction to its original 688 * state. At some point when gnucash is enhanced to support an audit 689 * trail (i.e. write only transactions) this command should be 690 * automatically disabled when the audit trail feature is enabled. 691 * 692 * @param transaction The transaction to restore from voided state. 693 */ 694 void xaccTransUnvoid(Transaction *transaction); 695 696 /** xaccTransReverse creates a Transaction that reverses the given 697 * transaction by inverting all the numerical values in the given 698 * transaction. This function cancels out the effect of an earlier 699 * transaction. This will be needed by write only accounts as a way 700 * to void a previous transaction (since you can't alter the existing 701 * transaction). 702 * 703 * @param transaction The transaction to create a reverse of. 704 * 705 * @return a new transaction which reverses the given transaction 706 */ 707 Transaction * xaccTransReverse(Transaction *transaction); 708 709 /** Returns the transaction that reversed the given transaction. 710 * 711 * @param trans a Transaction that has been reversed 712 * 713 * @return the transaction that reversed the given transaction, or 714 * NULL if the given transaction has not been reversed. 715 */ 716 Transaction * xaccTransGetReversedBy(const Transaction *trans); 717 718 /** Retrieve information on whether or not a transaction has been voided. 719 * 720 * @param transaction The transaction in question. 721 * 722 * @return TRUE if the transaction is void, FALSE otherwise. Also 723 * returns FALSE upon an error. 724 */ 725 gboolean xaccTransGetVoidStatus(const Transaction *transaction); 726 727 /** Returns the user supplied textual reason why a transaction was 728 * voided. 729 * 730 * @param transaction The transaction in question. 731 * 732 * @return A pointer to the user supplied reason for voiding. 733 */ 734 const char *xaccTransGetVoidReason(const Transaction *transaction); 735 736 /** Returns the time that a transaction was voided. 737 * 738 * @param tr The transaction in question. 739 * 740 * @return A time64 containing the time that this transaction was 741 * voided. Returns a time of zero upon error. 742 */ 743 time64 xaccTransGetVoidTime(const Transaction *tr); 744 /** @} */ 745 746 /** @name Transaction Parameter names 747 @{ 748 */ 749 #define TRANS_KVP "kvp" 750 #define TRANS_NUM "num" 751 #define TRANS_DESCRIPTION "desc" 752 #define TRANS_DATE_ENTERED "date-entered" 753 #define TRANS_DATE_POSTED "date-posted" 754 #define TRANS_DATE_DUE "date-due" 755 #define TRANS_IMBALANCE "trans-imbalance" 756 #define TRANS_IS_BALANCED "trans-balanced?" 757 #define TRANS_IS_CLOSING "trans-is-closing?" 758 #define TRANS_NOTES "notes" 759 #define TRANS_DOCLINK "doclink" 760 #define TRANS_TYPE "type" 761 #define TRANS_VOID_STATUS "void-p" 762 #define TRANS_VOID_REASON "void-reason" 763 #define TRANS_VOID_TIME "void-time" 764 #define TRANS_SPLITLIST "split-list" /* for guid_match_all */ 765 /**@}*/ 766 767 #ifdef DUMP_FUNCTIONS 768 void xaccTransDump (const Transaction *trans, const char *tag); 769 #endif 770 771 /** The xaccTransRecordPrice() method iterates through the splits and 772 * and record the non-currency equivalent prices in the price database. 773 * 774 * @param trans The transaction whose price is recorded 775 * @param source The price priority level 776 */ 777 void xaccTransRecordPrice (Transaction *trans, PriceSource source); 778 779 780 #define RECONCILED_MATCH_TYPE "reconciled-match" 781 782 /** \deprecated */ 783 #define xaccTransGetBook(X) qof_instance_get_book (QOF_INSTANCE(X)) 784 /** \deprecated */ 785 #define xaccTransGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X)) 786 /** \deprecated */ 787 #define xaccTransReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null())) 788 789 #ifdef __cplusplus 790 } /* extern "C" */ 791 #endif 792 793 #endif /* XACC_TRANSACTION_H */ 794 /** @} */ 795 /** @} */ 796