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 Account 23 Splits are grouped into Accounts which are also known 24 as "Ledgers" in accounting practice. Each Account consists of a list of 25 Splits that debit that Account. To ensure consistency, if a Split points 26 to an Account, then the Account must point to the Split, and vice-versa. 27 A Split can belong to at most one Account. Besides merely containing a 28 list of Splits, the Account structure also gives the Account a name, a 29 code number, description and notes fields, a key-value frame, a pointer 30 to the commodity that is used for all splits in this account. The 31 commodity can be the name of anything traded and tradeable: a stock 32 (e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or 33 anything added to the commodity table. 34 35 Accounts can be arranged in a hierarchical tree. By accounting 36 convention, the value of an Account is equal to the value of all of its 37 Splits plus the value of all of its sub-Accounts. 38 @{ */ 39 /** @file Account.h 40 @brief Account handling public routines 41 @author Copyright (C) 1997 Robin D. Clark 42 @author Copyright (C) 1997-2003 Linas Vepstas <linas@linas.org> 43 */ 44 45 #ifndef XACC_ACCOUNT_H 46 #define XACC_ACCOUNT_H 47 #include "qof.h" 48 #include "gnc-engine.h" 49 #include "policy.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 typedef gnc_numeric (*xaccGetBalanceFn)( const Account *account ); 55 56 typedef gnc_numeric (*xaccGetBalanceInCurrencyFn) ( 57 const Account *account, const gnc_commodity *report_commodity, 58 gboolean include_children); 59 60 typedef gnc_numeric (*xaccGetBalanceAsOfDateFn) ( 61 Account *account, time64 date); 62 63 typedef void (*AccountCb)(Account *a, gpointer data); 64 typedef gpointer (*AccountCb2)(Account *a, gpointer data); 65 66 typedef struct 67 { 68 QofInstanceClass parent_class; 69 } AccountClass; 70 71 typedef struct 72 { 73 Account *acc; 74 QofBook *book; 75 } GncImportMatchMap; 76 77 /* --- type macros --- */ 78 #define GNC_TYPE_ACCOUNT (gnc_account_get_type ()) 79 #define GNC_ACCOUNT(o) \ 80 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_ACCOUNT, Account)) 81 #define GNC_ACCOUNT_CLASS(k) \ 82 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_ACCOUNT, AccountClass)) 83 #define GNC_IS_ACCOUNT(o) \ 84 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_ACCOUNT)) 85 #define GNC_IS_ACCOUNT_CLASS(k) \ 86 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_ACCOUNT)) 87 #define GNC_ACCOUNT_GET_CLASS(o) \ 88 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_ACCOUNT, AccountClass)) 89 /** Returns the GType type system description of the Account class. 90 * 91 * This must not be confused with the \ref GNCAccountType as returned 92 * by xaccAccountGetType(). */ 93 GType gnc_account_get_type(void); 94 95 /** The account types are used to determine how the transaction data 96 * in the account is displayed. These values can be safely changed 97 * from one release to the next. Note that if values are added, 98 * the file IO translation routines need to be updated. Note 99 * also that GUI code depends on these numbers. 100 * 101 * @note ***IMPORTANT***: If you do change the enumeration names (not the 102 * numbers), you need to update xaccAccountTypeEnumAsString --- used 103 * for text file exports */ 104 105 typedef enum 106 { 107 ACCT_TYPE_INVALID = -1, /**< Not a type */ 108 ACCT_TYPE_NONE = -1,/**< Not a type */ 109 110 ACCT_TYPE_BANK = 0, /**< The bank account type denotes a savings 111 * or checking account held at a bank. 112 * Often interest bearing. */ 113 ACCT_TYPE_CASH = 1, /**< The cash account type is used to denote a 114 * shoe-box or pillowcase stuffed with * 115 * cash. */ 116 ACCT_TYPE_CREDIT = 3, /**< The Credit card account is used to denote 117 * credit (e.g. amex) and debit (e.g. visa, 118 * mastercard) card accounts */ 119 ACCT_TYPE_ASSET = 2, /**< asset (and liability) accounts indicate 120 * generic, generalized accounts that are 121 * none of the above. */ 122 ACCT_TYPE_LIABILITY = 4,/**< liability (and asset) accounts indicate 123 * generic, generalized accounts that are 124 * none of the above. */ 125 ACCT_TYPE_STOCK = 5, /**< Stock accounts will typically be shown in 126 * registers which show three columns: 127 * price, number of shares, and value. */ 128 ACCT_TYPE_MUTUAL = 6, /**< Mutual Fund accounts will typically be 129 * shown in registers which show three 130 * columns: price, number of shares, and 131 * value. */ 132 ACCT_TYPE_CURRENCY = 7,/**< The currency account type indicates that 133 * the account is a currency trading 134 * account. In many ways, a currency 135 * trading account is like a stock * 136 * trading account. It is shown in the 137 * register with three columns: price, 138 * number of shares, and value. Note: 139 * Since version 1.7.0, this account is * 140 * no longer needed to exchange currencies 141 * between accounts, so this type is 142 * DEPRECATED. */ 143 ACCT_TYPE_INCOME = 8, /**< Income accounts are used to denote 144 * income */ 145 146 ACCT_TYPE_EXPENSE = 9,/**< Expense accounts are used to denote 147 * expenses. */ 148 149 ACCT_TYPE_EQUITY = 10,/**< Equity account is used to balance the 150 * balance sheet. */ 151 152 ACCT_TYPE_RECEIVABLE = 11,/**< A/R account type */ 153 154 ACCT_TYPE_PAYABLE = 12, /**< A/P account type */ 155 156 ACCT_TYPE_ROOT = 13, /**< The hidden root account of an account tree. */ 157 158 ACCT_TYPE_TRADING = 14, /**< Account used to record multiple commodity transactions. 159 * This is not the same as ACCT_TYPE_CURRENCY above. 160 * Multiple commodity transactions have splits in these 161 * accounts to make the transaction balance in each 162 * commodity as well as in total value. */ 163 164 NUM_ACCOUNT_TYPES = 15, /**< stop here; the following types 165 * just aren't ready for prime time */ 166 167 /* bank account types */ 168 ACCT_TYPE_CHECKING = 15, /**< bank account type -- don't use this 169 * for now, see NUM_ACCOUNT_TYPES */ 170 ACCT_TYPE_SAVINGS = 16, /**< bank account type -- don't use this for 171 * now, see NUM_ACCOUNT_TYPES */ 172 ACCT_TYPE_MONEYMRKT = 17, /**< bank account type -- don't use this 173 * for now, see NUM_ACCOUNT_TYPES */ 174 ACCT_TYPE_CREDITLINE = 18, /**< line of credit -- don't use this for 175 * now, see NUM_ACCOUNT_TYPES */ 176 ACCT_TYPE_LAST 177 } GNCAccountType; 178 179 180 181 /** @name Account Constructors, Edit/Commit, Comparison 182 @{ */ 183 184 /** Constructor */ 185 Account * xaccMallocAccount (QofBook *book); 186 187 /** Create a new root level account. */ 188 Account * gnc_account_create_root (QofBook *book); 189 190 /** The xaccCloneAccount() routine makes a simple copy of the 191 * indicated account, placing it in the indicated book. It copies 192 * the account type, name, description, and the kvp values; 193 * it does not copy splits/transactions. The book should have 194 * a commodity table in it that has commodities with the same 195 * unique name as the ones being copied in the account (the 196 * commodities in the clone will be those from the book). 197 */ 198 Account * xaccCloneAccount (const Account *source, QofBook *book); 199 200 /** The xaccAccountBeginEdit() subroutine is the first phase of 201 * a two-phase-commit wrapper for account updates. */ 202 void xaccAccountBeginEdit (Account *account); 203 204 /** ThexaccAccountCommitEdit() subroutine is the second phase of 205 * a two-phase-commit wrapper for account updates. */ 206 void xaccAccountCommitEdit (Account *account); 207 208 /** The xaccAccountDestroy() routine can be used to get rid of an 209 * account. The account should have been opened for editing 210 * (by calling xaccAccountBeginEdit()) before calling this routine.*/ 211 void xaccAccountDestroy (Account *account); 212 213 /** Compare two accounts for equality - this is a deep compare. */ 214 gboolean xaccAccountEqual(const Account *a, const Account* b, 215 gboolean check_guids); 216 217 /** The xaccAccountOrder() subroutine defines a sorting order on 218 * accounts. It takes pointers to two accounts, and returns an int < 0 if 219 * the first account is "less than" the second, returns an int > 0 if the 220 * first is "greater than" the second, and 0 if they are equal. To 221 * determine the sort order, first the account codes are compared, 222 * and if these are equal, then account types, then account 223 * names. If still equal, it compares GUID to ensure that there 224 * aren't any ties. 225 */ 226 int xaccAccountOrder (const Account *account_1, const Account *account_2); 227 228 /** @} */ 229 230 /* ------------------ */ 231 232 /** @name Account lookup and GncGUID routines 233 @{ */ 234 235 /** Returns the account separation character chosen by the user. 236 * 237 * @return The character to use. 238 */ 239 const gchar *gnc_get_account_separator_string (void); 240 gunichar gnc_get_account_separator (void); 241 void gnc_set_account_separator (const gchar *separator); 242 243 /*@ dependent @*/ 244 Account *gnc_book_get_root_account(QofBook *book); 245 void gnc_book_set_root_account(QofBook *book, Account *root); 246 247 /** @deprecated */ 248 #define xaccAccountGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X)) 249 #define xaccAccountReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null())) 250 251 /** The xaccAccountLookup() subroutine will return the 252 * account associated with the given id, or NULL 253 * if there is no such account. */ 254 /*@ dependent @*/ Account * xaccAccountLookup (const GncGUID *guid, QofBook *book); 255 #define xaccAccountLookupDirect(g,b) xaccAccountLookup(&(g),b) 256 257 /** @} */ 258 259 /* Tests account and descendants -- if all have no splits then return TRUE. 260 * Otherwise if any account or its descendants have split return FALSE. 261 */ 262 263 gboolean gnc_account_and_descendants_empty (Account *acc); 264 265 /** Composes a translatable error message showing which account 266 * names clash with the current account separator. Can be called 267 * after gnc_account_list_name_violations to have a consistent 268 * error message in different parts of GnuCash 269 * 270 * @param separator The separator character that was verified against 271 * @param invalid_account_names A GList of invalid account names. 272 * 273 * @return An error message that can be displayed to the user or logged. 274 * This message string should be freed with g_free when no longer 275 * needed. 276 */ 277 gchar *gnc_account_name_violations_errmsg (const gchar *separator, GList* invalid_account_names); 278 279 /** Runs through all the accounts and returns a list of account names 280 * that contain the provided separator character. This can be used to 281 * check if certain account names are invalid. 282 * 283 * @param book Pointer to the book with accounts to verify 284 * @param separator The separator character to verify against 285 * 286 * @return A GList of invalid account names. Should be freed with 287 * g_list_free_full (value, g_free) when no longer needed. 288 */ 289 GList *gnc_account_list_name_violations (QofBook *book, const gchar *separator); 290 291 /* ------------------ */ 292 293 /** @name Account general setters/getters 294 @{ */ 295 296 QofBook *gnc_account_get_book(const Account *account); 297 /** Set the account's type */ 298 void xaccAccountSetType (Account *account, GNCAccountType); 299 /** Set the account's name */ 300 void xaccAccountSetName (Account *account, const char *name); 301 /** Set the account's accounting code */ 302 void xaccAccountSetCode (Account *account, const char *code); 303 /** Set the account's description */ 304 void xaccAccountSetDescription (Account *account, const char *desc); 305 /** Set the account's Color */ 306 void xaccAccountSetColor (Account *account, const char *color); 307 /** Set the account's Filter */ 308 void xaccAccountSetFilter (Account *account, const char *filter); 309 /** Set the account's Sort Order */ 310 void xaccAccountSetSortOrder (Account *account, const char *sortorder); 311 /** Set the account's Sort Order direction */ 312 void xaccAccountSetSortReversed (Account *account, gboolean sortreversed); 313 /** Set the account's notes */ 314 void xaccAccountSetNotes (Account *account, const char *notes); 315 /** Set the last num field of an Account */ 316 void xaccAccountSetLastNum (Account *account, const char *num); 317 /** Set the account's lot order policy */ 318 void gnc_account_set_policy (Account *account, GNCPolicy *policy); 319 /** Returns the account's account type. 320 * 321 * This must not be confused with the \ref GType as returned by 322 * gnc_account_get_type(), which is related to glib's type system. */ 323 GNCAccountType xaccAccountGetType (const Account *account); 324 /** Returns true if the account is a stock, mutual fund or currency, 325 * otherwise false. */ 326 gboolean xaccAccountIsPriced(const Account *acc); 327 328 /** This function will set the starting commodity balance for this 329 * account. This routine is intended for use with backends that do 330 * not return the complete list of splits for an account, but rather 331 * return a partial list. In such a case, the backend will typically 332 * return all of the splits after some certain date, and the 333 * 'starting balance' will represent the summation of the splits up 334 * to that date. */ 335 void gnc_account_set_start_balance (Account *acc, 336 const gnc_numeric start_baln); 337 338 /** This function will set the starting cleared commodity balance for 339 * this account. This routine is intended for use with backends that 340 * do not return the complete list of splits for an account, but 341 * rather return a partial list. In such a case, the backend will 342 * typically return all of the splits after some certain date, and 343 * the 'starting balance' will represent the summation of the splits 344 * up to that date. */ 345 void gnc_account_set_start_cleared_balance (Account *acc, 346 const gnc_numeric start_baln); 347 348 /** This function will set the starting reconciled commodity balance 349 * for this account. This routine is intended for use with backends 350 * that do not return the complete list of splits for an account, but 351 * rather return a partial list. In such a case, the backend will 352 * typically return all of the splits after some certain date, and 353 * the 'starting balance' will represent the summation of the splits 354 * up to that date. */ 355 void gnc_account_set_start_reconciled_balance (Account *acc, 356 const gnc_numeric start_baln); 357 358 /** Tell the account that the running balances may be incorrect and 359 * need to be recomputed. 360 * 361 * @param acc Set the flag on this account. */ 362 void gnc_account_set_balance_dirty (Account *acc); 363 364 /** Tell the account believes that the splits may be incorrectly 365 * sorted and need to be resorted. 366 * 367 * @param acc Set the flag on this account. */ 368 void gnc_account_set_sort_dirty (Account *acc); 369 370 /** Set the defer balance flag. If defer is true, the account balance 371 * is not automatically computed, which can save a lot of time if 372 * multiple operations have to be done on the same account. If 373 * defer is false, further operations on account will cause the 374 * balance to be recomputed as normal. 375 * 376 * @param acc Set the flag on this account. 377 * 378 * @param defer New value for the flag. */ 379 void gnc_account_set_defer_bal_computation (Account *acc, gboolean defer); 380 381 /** Insert the given split from an account. 382 * 383 * @param acc The account to which the split should be added. 384 * 385 * @param s The split to be added. 386 * 387 * @result TRUE is the split is successfully added to the set of 388 * splits in the account. FALSE if the addition fails for any reason 389 * (including that the split is already in the account). */ 390 gboolean gnc_account_insert_split (Account *acc, Split *s); 391 392 /** Remove the given split from an account. 393 * 394 * @param acc The account from which the split should be removed. 395 * 396 * @param s The split to be removed. 397 * 398 * @result TRUE is the split is successfully removed from the set of 399 * splits in the account. FALSE if the removal fails for any 400 * reason. */ 401 gboolean gnc_account_remove_split (Account *acc, Split *s); 402 403 /** Get the account's name */ 404 const char * xaccAccountGetName (const Account *account); 405 /** Get the account's accounting code */ 406 const char * xaccAccountGetCode (const Account *account); 407 /** Get the account's description */ 408 const char * xaccAccountGetDescription (const Account *account); 409 /** Get the account's color */ 410 const char * xaccAccountGetColor (const Account *account); 411 /** Get the account's filter */ 412 const char * xaccAccountGetFilter (const Account *account); 413 /** Get the account's Sort Order */ 414 const char * xaccAccountGetSortOrder (const Account *account); 415 /** Get the account's Sort Order direction */ 416 gboolean xaccAccountGetSortReversed (const Account *account); 417 /** Get the account's notes */ 418 const char * xaccAccountGetNotes (const Account *account); 419 /** Get the last num field of an Account */ 420 const char * xaccAccountGetLastNum (const Account *account); 421 /** Get the account's lot order policy */ 422 GNCPolicy *gnc_account_get_policy (Account *account); 423 /** Get the account's flag for deferred balance computation */ 424 gboolean gnc_account_get_defer_bal_computation (Account *acc); 425 426 /** The following recompute the partial balances (stored with the 427 * transaction) and the total balance, for this account 428 */ 429 void xaccAccountRecomputeBalance (Account *); 430 431 /** The xaccAccountSortSplits() routine will resort the account's 432 * splits if the sort is dirty. If 'force' is true, the account 433 * is sorted even if the editlevel is not zero. 434 */ 435 void xaccAccountSortSplits (Account *acc, gboolean force); 436 437 /** The gnc_account_get_full_name routine returns the fully qualified name 438 * of the account using the given separator char. The name must be 439 * g_free'd after use. The fully qualified name of an account is the 440 * concatenation of the names of the account and all its ancestor 441 * accounts starting with the topmost account and ending with the 442 * given account. Each name is separated by the given character. 443 * 444 * @note: WAKE UP! 445 * Unlike all other gets, the string returned by gnc_account_get_full_name() 446 * must be freed by you the user !!! 447 * hack alert -- since it breaks the rule of string allocation, maybe this 448 * routine should not be in this library, but some utility library? 449 */ 450 gchar * gnc_account_get_full_name (const Account *account); 451 452 /** Retrieve the gains account used by this account for the indicated 453 * currency, creating and recording a new one if necessary. 454 * 455 * FIXME: There is at present no interface to designate an existing 456 * account, and the new account name is hard coded to 457 * "Orphaned Gains -- CUR" 458 * 459 * FIXME: There is no provision for creating separate accounts for 460 * anything other than currency, e.g. holding period of a security. 461 */ 462 Account * xaccAccountGainsAccount (Account *acc, gnc_commodity *curr); 463 /** Set a string that identifies the Finance::Quote backend that 464 * should be used to retrieve online prices. See price-quotes.scm 465 * for more information 466 * 467 * @deprecated Price quote information is now stored on the 468 * commodity, not the account. */ 469 void dxaccAccountSetPriceSrc (Account *account, const char *src); 470 /** Get a string that identifies the Finance::Quote backend that 471 * should be used to retrieve online prices. See price-quotes.scm 472 * for more information. This function uses a static char*. 473 * 474 * @deprecated Price quote information is now stored on the 475 * commodity, not the account. */ 476 const char * dxaccAccountGetPriceSrc (const Account *account); 477 /** @} */ 478 479 /** @name Account Commodity setters/getters 480 481 * Accounts are used to store an amount of 'something', that 'something' 482 * is called the 'commodity'. An account can only hold one kind of 483 * commodity. The following are used to get and set the commodity, 484 * and also to set the SCU, the 'Smallest Commodity Unit'. 485 * 486 * Note that when we say that a 'split' holds an 'amount', that amount 487 * is denominated in the account commodity. Do not confuse 'amount' 488 * and 'value'. The 'value' of a split is the value of the amount 489 * expressed in the currency of the transaction. Thus, for example, 490 * the 'amount' may be 12 apples, where the account commodity is 491 * 'apples'. The value of these 12 apples may be 12 dollars, where 492 * the transaction currency is 'dollars'. 493 * 494 * The SCU is the 'Smallest Commodity Unit', signifying the smallest 495 * non-zero amount that can be stored in the account. It is 496 * represented as the integer denominator of a fraction. Thus, 497 * for example, a SCU of 12 means that 1/12 of something is the 498 * smallest amount that can be stored in the account. SCU's can 499 * be any value; they do not need to be decimal. This allows 500 * the use of accounts with unusual, non-decimal commodities and 501 * currencies. 502 * 503 * Normally, the SCU is determined by the commodity of the account. 504 * However, this default SCU can be over-ridden and set to an 505 * account-specific value. This is account-specific value is 506 * called the 'non-standard' value in the documentation below. 507 @{ 508 */ 509 510 /** Set the account's commodity */ 511 void xaccAccountSetCommodity (Account *account, gnc_commodity *comm); 512 513 /** Get the account's commodity */ 514 /*@ dependent @*/ 515 gnc_commodity * xaccAccountGetCommodity (const Account *account); 516 517 /** Returns a gnc_commodity that is a currency, suitable for being a 518 Transaction's currency. The gnc_commodity is taken either from the current 519 account, or from the next parent account that has a gnc_commodity that is a 520 currency. If neither this account nor any of its parent has such a commodity 521 that is a currency, NULL is returned. In that case, you can use 522 gnc_default_currency() but you might want to show a warning dialog first. */ 523 gnc_commodity * gnc_account_get_currency_or_parent(const Account* account); 524 525 /** Return the SCU for the account. If a non-standard SCU has been 526 * set for the account, that is returned; else the default SCU for 527 * the account commodity is returned. 528 */ 529 int xaccAccountGetCommoditySCU (const Account *account); 530 531 /** Return the 'internal' SCU setting. This returns the over-ride 532 * SCU for the account (which might not be set, and might be zero). */ 533 int xaccAccountGetCommoditySCUi (const Account *account); 534 535 /** Set the SCU for the account. Normally, this routine is not 536 * required, as the default SCU for an account is given by its 537 * commodity. 538 */ 539 void xaccAccountSetCommoditySCU (Account *account, int frac); 540 541 /** Set the flag indicating that this account uses a non-standard SCU. */ 542 void xaccAccountSetNonStdSCU (Account *account, gboolean flag); 543 544 /** Return boolean, indicating whether this account uses a 545 * non-standard SCU. */ 546 gboolean xaccAccountGetNonStdSCU (const Account *account); 547 /**@}*/ 548 549 550 /** @name Account Balance 551 @{ 552 */ 553 /** Get the current balance of the account, which may include future 554 splits */ 555 gnc_numeric xaccAccountGetBalance (const Account *account); 556 /** Get the current balance of the account, only including cleared 557 transactions */ 558 gnc_numeric xaccAccountGetClearedBalance (const Account *account); 559 /** Get the current balance of the account, only including reconciled 560 transactions */ 561 gnc_numeric xaccAccountGetReconciledBalance (const Account *account); 562 gnc_numeric xaccAccountGetPresentBalance (const Account *account); 563 gnc_numeric xaccAccountGetProjectedMinimumBalance (const Account *account); 564 /** Get the balance of the account at the end of the day before the date specified. */ 565 gnc_numeric xaccAccountGetBalanceAsOfDate (Account *account, 566 time64 date); 567 568 /** Get the reconciled balance of the account at the end of the day of the date specified. */ 569 gnc_numeric xaccAccountGetReconciledBalanceAsOfDate (Account *account, time64 date); 570 571 /* These two functions convert a given balance from one commodity to 572 another. The account argument is only used to get the Book, and 573 may have nothing to do with the supplied balance. Likewise, the 574 date argument is only used for commodity conversion and may have 575 nothing to do with supplied balance. 576 577 Since they really have nothing to do with Accounts, there's 578 probably some better place for them, but where? gnc-commodity.h? 579 */ 580 gnc_numeric xaccAccountConvertBalanceToCurrency( 581 const Account *account, /* for book */ 582 gnc_numeric balance, 583 const gnc_commodity *balance_currency, 584 const gnc_commodity *new_currency); 585 gnc_numeric xaccAccountConvertBalanceToCurrencyAsOfDate( 586 const Account *account, /* for book */ 587 gnc_numeric balance, const gnc_commodity *balance_currency, 588 const gnc_commodity *new_currency, time64 date); 589 590 /* These functions get some type of balance in the desired commodity. 591 'report_commodity' may be NULL to use the account's commodity. */ 592 gnc_numeric xaccAccountGetBalanceInCurrency ( 593 const Account *account, const gnc_commodity *report_commodity, 594 gboolean include_children); 595 gnc_numeric xaccAccountGetClearedBalanceInCurrency ( 596 const Account *account, const gnc_commodity *report_commodity, 597 gboolean include_children); 598 gnc_numeric xaccAccountGetReconciledBalanceInCurrency ( 599 const Account *account, const gnc_commodity *report_commodity, 600 gboolean include_children); 601 gnc_numeric xaccAccountGetPresentBalanceInCurrency ( 602 const Account *account, const gnc_commodity *report_commodity, 603 gboolean include_children); 604 gnc_numeric xaccAccountGetProjectedMinimumBalanceInCurrency ( 605 const Account *account, const gnc_commodity *report_commodity, 606 gboolean include_children); 607 608 /** This function gets the balance at the end of the given date, ignoring 609 closing entries, in the desired commodity. */ 610 gnc_numeric xaccAccountGetNoclosingBalanceAsOfDateInCurrency( 611 Account *acc, time64 date, gnc_commodity *report_commodity, 612 gboolean include_children); 613 /** This function gets the balance at the end of the given date in the desired 614 commodity. */ 615 gnc_numeric xaccAccountGetBalanceAsOfDateInCurrency( 616 Account *account, time64 date, gnc_commodity *report_commodity, 617 gboolean include_children); 618 619 gnc_numeric xaccAccountGetNoclosingBalanceChangeForPeriod ( 620 Account *acc, time64 date1, time64 date2, gboolean recurse); 621 gnc_numeric xaccAccountGetBalanceChangeForPeriod ( 622 Account *acc, time64 date1, time64 date2, gboolean recurse); 623 624 /** @} */ 625 626 /** @name Account Children and Parents. 627 628 * The set of accounts is represented as a doubly-linked tree, so that given 629 * any account, both its parent and its children can be easily found. 630 * At the top of the tree hierarchy lies a single root node, the root account. 631 * 632 * The account tree hierarchy is unique, in that a given account can 633 * have only one parent account. 634 @{ 635 */ 636 637 /** This function will remove from the child account any pre-existing 638 * parent relationship, and will then add the account as a child of 639 * the new parent. The exception to this is when the old and new 640 * parent accounts are the same, in which case this function does 641 * nothing. 642 * 643 * If the child account belongs to a different book than the 644 * specified new parent account, the child will be removed from the 645 * other book (and thus, the other book's entity tables, generating a 646 * destroy event), and will be added to the new book (generating a 647 * create event). 648 * 649 * @param new_parent The new parent account to which the child should 650 * be attached. 651 * 652 * @param child The account to attach. 653 */ 654 void gnc_account_append_child (Account *new_parent, Account *child); 655 656 /** This function will remove the specified child account from the 657 * specified parent account. It will NOT free the associated memory 658 * or otherwise alter the account: the account can now be reparented 659 * to a new location. Note, however, that it will mark the old 660 * parents as having been modified. 661 * 662 * @param parent The parent account from which the child should be 663 * removed. 664 * 665 * @param child The child account to remove. */ 666 void gnc_account_remove_child (Account *parent, Account *child); 667 668 /** This routine returns a pointer to the parent of the specified 669 * account. If the account has no parent, i.e it is either the root 670 * node or is a disconnected account, then its parent will be NULL. 671 * 672 * @param account A pointer to any exiting account. 673 * 674 * @return A pointer to the parent account node, or NULL if there is 675 * no parent account. */ 676 /*@ dependent @*/ 677 Account * gnc_account_get_parent (const Account *account); 678 679 /** This routine returns the root account of the account tree that the 680 * specified account belongs to. It is the equivalent of repeatedly 681 * calling the gnc_account_get_parent() routine until that routine 682 * returns NULL. 683 * 684 * @param account A pointer to any existing account. 685 * 686 * @return The root node of the account tree to which this account 687 * belongs. NULL if the account is not part of any account tree. */ 688 Account * gnc_account_get_root (Account *account); 689 690 /** This routine indicates whether the specified account is the root 691 * node of an account tree. 692 * 693 * @param account A pointer to any account. 694 * 695 * @return TRUE if this account is of type ROOT. FALSE otherwise. */ 696 gboolean gnc_account_is_root (const Account *account); 697 698 /** This routine returns a GList of all children accounts of the specified 699 * account. This function only returns the immediate children of the 700 * specified account. For a list of all descendant accounts, use the 701 * gnc_account_get_descendants() function. 702 * 703 * If you are looking for the splits of this account, use 704 * xaccAccountGetSplitList() instead. This function here deals with 705 * children accounts inside the account tree. 706 * 707 * @param account The account whose children should be returned. 708 * 709 * @return A GList of account pointers, or NULL if there are no 710 * children accounts. It is the callers responsibility to free any returned 711 * list with the g_list_free() function. */ 712 GList *gnc_account_get_children (const Account *account); 713 714 /** This routine returns a GList of all children accounts of the specified 715 * account, ordered by xaccAccountOrder(). \sa gnc_account_get_children() 716 */ 717 GList *gnc_account_get_children_sorted (const Account *account); 718 719 /** Return the number of children of the specified account. The 720 * returned number does not include the account itself. 721 * 722 * @param account The account to query. 723 * 724 * @return The number of children of the specified account. */ 725 gint gnc_account_n_children (const Account *account); 726 727 /** Return the index of the specified child within the list of the 728 * parent's children. The first child index is 0. This function 729 * returns -1 if the parent account is NULL of if the specified child 730 * does not belong to the parent account. 731 * 732 * @param parent The parent account to check. 733 * 734 * @param child The child account to find. 735 * 736 * @return The index of the child account within the specified 737 * parent, or -1. */ 738 gint gnc_account_child_index (const Account *parent, const Account *child); 739 740 /** Return the n'th child account of the specified parent account. If 741 * the parent account is not specified or the child index number is 742 * invalid, this function returns NULL. 743 * 744 * @param parent The parent account to check. 745 * 746 * @param num The index number of the child account that should be 747 * returned. 748 * 749 * @return A pointer to the specified child account, or NULL */ 750 Account *gnc_account_nth_child (const Account *parent, gint num); 751 752 /** This routine returns a flat list of all of the accounts that are 753 * descendants of the specified account. This includes not only the 754 * the children, but the children of the children, etc. For a list of 755 * only the immediate child accounts, use the 756 * gnc_account_get_children() function. Within each set of child 757 * accounts, the accounts returned by this function are unordered. 758 * For a list of descendants where each set of children is sorted via 759 * the standard account sort function, use the 760 * gnc_account_get_descendants_sorted() function. 761 * 762 * @param account The account whose descendants should be returned. 763 * 764 * @return A GList of account pointers, or NULL if there are no 765 * descendants. It is the callers responsibility to free any returned 766 * list with the g_list_free() function. */ 767 GList * gnc_account_get_descendants (const Account *account); 768 769 /** This function returns a GList containing all the descendants of 770 * the specified account, sorted at each level. This includes not 771 * only the the children, but the children of the children, etc. 772 * Within each set of child accounts, the accounts returned by this 773 * function are ordered via the standard account sort function. For 774 * a list of descendants where each set of children is unordered, use 775 * the gnc_account_get_descendants() function. 776 * 777 * Note: Use this function where the results are intended for display 778 * to the user. If the results are internal to GnuCash or will be 779 * resorted at some later point in time you should use the 780 * gnc_account_get_descendants() function. 781 * 782 * @param account The account whose descendants should be returned. 783 * 784 * @return A GList of account pointers, or NULL if there are no 785 * descendants. It is the callers responsibility to free any returned 786 * list with the g_list_free() function. */ 787 GList *gnc_account_get_descendants_sorted (const Account *account); 788 789 /** Return the number of descendants of the specified account. The 790 * returned number does not include the account itself. 791 * 792 * @param account The account to query. 793 * 794 * @return The number of descendants of the specified account. */ 795 gint gnc_account_n_descendants (const Account *account); 796 797 /** Return the number of levels of this account below the root 798 * account. 799 * 800 * @param account The account to query. 801 * 802 * @return The number of levels below the root. */ 803 gint gnc_account_get_current_depth (const Account *account); 804 805 /** Return the number of levels of descendants accounts below the 806 * specified account. The returned number does not include the 807 * specified account itself. 808 * 809 * @param account The account to query. 810 * 811 * @return The number of levels of descendants. */ 812 gint gnc_account_get_tree_depth (const Account *account); 813 814 /** @name ForEach 815 @{ 816 */ 817 818 /** This method will traverse the immediate children of this accounts, 819 * calling 'func' on each account. This function traverses all 820 * children nodes. To traverse only a subset of the child nodes use 821 * the gnc_account_foreach_child_until() function. 822 * 823 * @param account A pointer to the account on whose children the 824 * function should be called. 825 * 826 * @param func A function taking two arguments, an Account and a 827 * gpointer. 828 * 829 * @param user_data This data will be passed to each call of func. */ 830 void gnc_account_foreach_child (const Account *account, 831 AccountCb func, /*@ null @*/ gpointer user_data); 832 833 /** This method will traverse all children of this accounts and their 834 * descendants, calling 'func' on each account. This function 835 * traverses all descendant nodes. To traverse only a subset of the 836 * descendant nodes use the gnc_account_foreach_descendant_until() 837 * function. 838 * 839 * @param account A pointer to the account on whose descendants the 840 * function should be called. 841 * 842 * @param func A function taking two arguments, an Account and a 843 * gpointer. 844 * 845 * @param user_data This data will be passed to each call of func. */ 846 void gnc_account_foreach_descendant (const Account *account, 847 AccountCb func, /*@ null @*/ gpointer user_data); 848 849 /** This method will traverse all children of this accounts and their 850 * descendants, calling 'func' on each account. Traversal will stop 851 * when func returns a non-null value, and the routine will return 852 * with that value. Therefore, this function will return null if 853 * func returns null for every account. For a simpler function that 854 * always traverses all children nodes, use the 855 * gnc_account_foreach_descendant() function. 856 * 857 * @param account A pointer to the account on whose descendants the 858 * function should be called. 859 * 860 * @param func A function taking two arguments, an Account and a 861 * gpointer. 862 * 863 * @param user_data This data will be passed to each call of func. */ 864 gpointer gnc_account_foreach_descendant_until (const Account *account, 865 AccountCb2 func, /*@ null @*/ gpointer user_data); 866 867 868 /** @} */ 869 870 /** @name Concatenation, Merging 871 @{ 872 */ 873 874 /** The gnc_account_join_children() subroutine will move (reparent) 875 * all child accounts from the from_parent account to the to_parent 876 * account, preserving the account hierarchy. It will also take care 877 * that the moved accounts will have the to_parent's book parent 878 * as well. 879 */ 880 void gnc_account_join_children (Account *to_parent, Account *from_parent); 881 882 /** The gnc_account_merge_children() subroutine will go through an 883 * account, merging all child accounts that have the same name and 884 * description. This function is useful when importing Quicken(TM) 885 * files. 886 */ 887 void gnc_account_merge_children (Account *parent); 888 889 /** @} */ 890 891 /** DOCUMENT ME! */ 892 void xaccAccountSetReconcileChildrenStatus(Account *account, gboolean status); 893 894 /** DOCUMENT ME! */ 895 gboolean xaccAccountGetReconcileChildrenStatus(const Account *account); 896 897 /** Returns true if the account is 'ancestor' or has 'ancestor' as an 898 * ancestor. An ancestor account may be the accounts parent, its 899 * parent's parent, its parent's parent's parent, etc. Returns false 900 * if either one is NULL. 901 */ 902 gboolean xaccAccountHasAncestor(const Account *acc, const Account *ancestor); 903 904 /** @} */ 905 906 /** @name Lookup Accounts and Subaccounts by name or code 907 @{ 908 */ 909 /** The gnc_account_lookup_by_name() subroutine fetches the account by 910 * name from the descendants of the specified account. The immediate 911 * children are searched first. If there is no match,, then a 912 * recursive search of all descendants is performed looking for a 913 * match. 914 * 915 * @return A pointer to the account with the specified name, or NULL 916 * if the account was not found. 917 */ 918 Account *gnc_account_lookup_by_name (const Account *parent, const char *name); 919 920 /** The gnc_account_lookup_full_name() subroutine works like 921 * gnc_account_lookup_by_name, but uses fully-qualified names using the 922 * given separator. 923 */ 924 Account *gnc_account_lookup_by_full_name (const Account *any_account, 925 const gchar *name); 926 927 /** The gnc_account_lookup_by_code() subroutine works like 928 * gnc_account_lookup_by_name, but uses the account code. 929 */ 930 Account *gnc_account_lookup_by_code (const Account *parent, 931 const char *code); 932 933 /** Find the opening balance account for the currency. 934 * 935 * @param account The account of which the sought-for account is a descendant. 936 * @param commodity The commodity in which the account should be denominated 937 * @return The descendant account of EQUITY_TYPE_OPENING_BALANCE or NULL if one doesn't exist. 938 */ 939 Account *gnc_account_lookup_by_opening_balance (Account *account, gnc_commodity *commodity); 940 941 /** Find a direct child account matching name, GNCAccountType, and/or commodity. 942 * 943 * Name and commodity may be nullptr in which case the accounts in the 944 * list may have any value for those properties. Note that commodity 945 * matching is by equivalence: If the mnemonic/symbol and namespace 946 * are the same, it matches. 947 * 948 * @param root The account among whose children one expects to find 949 * the account. 950 * @param name The name of the account to look for or nullptr. 951 * @param acctype The GNCAccountType to match. 952 * @param commodity The commodity in which the account should be denominated or nullptr. 953 * @return A GList of children matching the supplied parameters. 954 */ 955 GList *gnc_account_lookup_by_type_and_commodity (Account* root, 956 const char* name, 957 GNCAccountType acctype, 958 gnc_commodity* commodity); 959 /** @} */ 960 961 /* ------------------ */ 962 963 /** @name GNCAccountType conversion/checking 964 @{ 965 */ 966 /** 967 * Conversion routines for the account types to/from strings 968 * that are used in persistent storage, communications. These 969 * strings should *not* be translated to the local language. 970 * Typical conversion is ACCT_TYPE_INCOME -> "INCOME". */ 971 const char * xaccAccountTypeEnumAsString (GNCAccountType type); 972 /** 973 * Conversion routines for the account types to/from strings 974 * that are used in persistent storage, communications. These 975 * strings should *not* be translated to the local language. 976 * Typical conversion is "INCOME" -> ACCT_TYPE_INCOME. */ 977 gboolean xaccAccountStringToType (const char* str, GNCAccountType *type); 978 /** 979 * Conversion routines for the account types to/from strings 980 * that are used in persistent storage, communications. These 981 * strings should *not* be translated to the local language. 982 * Typical conversion is "INCOME" -> ACCT_TYPE_INCOME. */ 983 GNCAccountType xaccAccountStringToEnum (const char* str); 984 985 /** The xaccAccountGetTypeStr() routine returns a string suitable for 986 * use in the GUI/Interface. These strings should be translated 987 * to the local language. */ 988 const char * xaccAccountGetTypeStr (GNCAccountType type); 989 990 /** Return the bitmask of account types compatible with a given type. 991 * That is, you could switch to any of the account types in the compatible 992 * list without unwanted side-effects. */ 993 guint32 xaccAccountTypesCompatibleWith (GNCAccountType type); 994 995 /** Return the bitmask of parent account types compatible with a given type. */ 996 guint32 xaccParentAccountTypesCompatibleWith (GNCAccountType type); 997 998 /** Return TRUE if accounts of type parent_type can have accounts 999 * of type child_type as children. */ 1000 gboolean xaccAccountTypesCompatible (GNCAccountType parent_type, 1001 GNCAccountType child_type); 1002 1003 /** Returns the bitmask of the account type enums that are valid. Deprecated and 1004 * root account types are stripped. */ 1005 guint32 xaccAccountTypesValid(void); 1006 1007 /** Convenience function to check if the account is a valid 1008 * Asset or Liability type, but not a business account type 1009 * (meaning not an Accounts Payable/Accounts Receivable). */ 1010 gboolean xaccAccountIsAssetLiabType(GNCAccountType t); 1011 1012 /** Convenience function to return the fundamental type 1013 * asset/liability/income/expense/equity given an account type. */ 1014 GNCAccountType xaccAccountTypeGetFundamental (GNCAccountType t); 1015 1016 1017 /** Convenience function to check if the account is a valid 1018 * business account type 1019 * (meaning an Accounts Payable/Accounts Receivable). */ 1020 gboolean xaccAccountIsAPARType(GNCAccountType t); 1021 1022 /** Convenience function to check if the account is a valid 1023 * Equity type. */ 1024 gboolean xaccAccountIsEquityType(GNCAccountType t); 1025 1026 1027 /** @} */ 1028 1029 /* ------------------ */ 1030 1031 /** @name Account split/transaction list management 1032 @{ 1033 */ 1034 /** The xaccAccountInsertSplit() method will insert the indicated 1035 * split into the indicated account. If the split already 1036 * belongs to another account, it will be removed from that 1037 * account first.*/ 1038 #define xaccAccountInsertSplit(acc, s) xaccSplitSetAccount((s), (acc)) 1039 1040 /** The xaccAccountGetSplitList() routine returns a pointer to a GList of 1041 * the splits in the account. 1042 * @note This GList is the account's internal 1043 * data structure: do not delete it when done; treat it as a read-only 1044 * structure. Note that some routines (such as xaccAccountRemoveSplit()) 1045 * modify this list directly, and could leave you with a corrupted 1046 * pointer. 1047 * @note This should be changed so that the returned value is a copy 1048 * of the list. No other part of the code should have access to the 1049 * internal data structure used by this object. 1050 */ 1051 SplitList* xaccAccountGetSplitList (const Account *account); 1052 1053 1054 /** The xaccAccountCountSplits() routine returns the number of all 1055 * the splits in the account. xaccAccountCountSplits is O(N). if 1056 * testing for emptiness, use xaccAccountGetSplitList != NULL. 1057 1058 * @param acc the account for which to count the splits 1059 * 1060 * @param include_children also count splits in descendants (TRUE) or 1061 * for this account only (FALSE). 1062 */ 1063 gint64 xaccAccountCountSplits (const Account *acc, gboolean include_children); 1064 1065 /** The xaccAccountMoveAllSplits() routine reassigns each of the splits 1066 * in accfrom to accto. */ 1067 void xaccAccountMoveAllSplits (Account *accfrom, Account *accto); 1068 1069 /** The xaccAccountForEachTransaction() routine will traverse all of 1070 * the transactions in @a account and call the callback 1071 * function @a proc on each transaction. Processing will continue 1072 * if-and-only-if @a proc returns 0. The user data pointer 1073 * @a data will be passed on to the callback function @a proc. 1074 * 1075 * This function does not descend recursively to traverse transactions 1076 * in child accounts. 1077 * 1078 * @a proc will be called exactly once for each transaction that is 1079 * pointed to by at least one split in the given account. 1080 * 1081 * The result of this function will be 0 <em>if and only if</em> 1082 * every relevant transaction was traversed exactly once. 1083 * Else the return value is the last non-zero value returned by proc. 1084 * 1085 * \warning For performance reasons, the transaction callback @a proc 1086 * must never destroy any of the transaction's splits, nor assign any 1087 * of them to a different account. <b>To do so risks a crash.</b> 1088 * 1089 * \warning The traversal occurs only over the transactions that 1090 * are locally cached in the local gnucash engine. If the gnucash 1091 * engine is attached to a remote database, the database may contain 1092 * (many) transactions that are not mirrored in the local cache. 1093 * This routine will not cause an SQL database query to be performed; 1094 * it will not traverse transactions present only in the remote 1095 * database. 1096 */ 1097 gint xaccAccountForEachTransaction(const Account *account, 1098 TransactionCallback proc, 1099 void *data); 1100 1101 /** Returns a pointer to the transaction, not a copy. */ 1102 Transaction * xaccAccountFindTransByDesc(const Account *account, 1103 const char *description); 1104 1105 /** Returns a pointer to the split, not a copy. */ 1106 Split * xaccAccountFindSplitByDesc(const Account *account, 1107 const char *description); 1108 1109 /** @} */ 1110 1111 /* ------------------ */ 1112 1113 /** @name Account lots 1114 @{ 1115 */ 1116 /** The xaccAccountInsertLot() method will register the indicated lot 1117 * with this account. Any splits later inserted into this lot must 1118 * belong to this account. If the lot is already in another account, 1119 * the lot, and all of the splits in it, will be moved from that 1120 * account to this account. */ 1121 void xaccAccountInsertLot (Account *, GNCLot *); 1122 void xaccAccountRemoveLot (Account *, GNCLot *); 1123 1124 /** The xaccAccountGetLotList() routine returns a list of all lots in 1125 * this account. 1126 * 1127 * @param account The account whose lots should be returned. 1128 * 1129 * @return A GList of lot pointers, or NULL if there are no lots in 1130 * this account children. It is the callers responsibility to free 1131 * any returned list with the g_list_free() function. */ 1132 LotList* xaccAccountGetLotList (const Account *account); 1133 1134 /** The xaccAccountForEachLot() method will apply the function 'proc' 1135 * to each lot in the account. If 'proc' returns a non-NULL value, 1136 * further application will be stopped, and the resulting value 1137 * will be returned. There is no guaranteed order over which 1138 * the Lots will be traversed. 1139 */ 1140 gpointer xaccAccountForEachLot( 1141 const Account *acc, 1142 gpointer (*proc)(GNCLot *lot, gpointer user_data), /*@ null @*/ gpointer user_data); 1143 1144 1145 /** Find a list of open lots that match the match_func. Sort according 1146 * to sort_func. If match_func is NULL, then all open lots are returned. 1147 * If sort_func is NULL, then the returned list has no particular order. 1148 * The caller must free to returned list. 1149 */ 1150 LotList * xaccAccountFindOpenLots (const Account *acc, 1151 gboolean (*match_func)(GNCLot *lot, 1152 gpointer user_data), 1153 /*@ null @*/ gpointer user_data, GCompareFunc sort_func); 1154 1155 /** @} */ 1156 /* ------------------ */ 1157 1158 /** @name Account Reconciliation information getters/setters 1159 @{ 1160 */ 1161 /** DOCUMENT ME! */ 1162 gboolean xaccAccountGetReconcileLastDate (const Account *account, 1163 time64 *last_date); 1164 /** DOCUMENT ME! */ 1165 void xaccAccountSetReconcileLastDate (Account *account, time64 last_date); 1166 1167 /** DOCUMENT ME! */ 1168 gboolean xaccAccountGetReconcileLastInterval (const Account *account, 1169 int *months, int *days); 1170 /** DOCUMENT ME! */ 1171 void xaccAccountSetReconcileLastInterval (Account *account, 1172 int months, int days); 1173 /** DOCUMENT ME! */ 1174 gboolean xaccAccountGetReconcilePostponeDate (const Account *account, 1175 time64 *postpone_date); 1176 /** DOCUMENT ME! */ 1177 void xaccAccountSetReconcilePostponeDate (Account *account, 1178 time64 postpone_date); 1179 1180 /** DOCUMENT ME! */ 1181 gboolean xaccAccountGetReconcilePostponeBalance (const Account *account, 1182 gnc_numeric *balance); 1183 /** DOCUMENT ME! */ 1184 void xaccAccountSetReconcilePostponeBalance (Account *account, 1185 gnc_numeric balance); 1186 1187 /** DOCUMENT ME! */ 1188 void xaccAccountClearReconcilePostpone (Account *account); 1189 /** @} */ 1190 1191 1192 /** DOCUMENT ME! */ 1193 typedef enum 1194 { 1195 PLACEHOLDER_NONE, 1196 PLACEHOLDER_THIS, 1197 PLACEHOLDER_CHILD, 1198 } GNCPlaceholderType; 1199 1200 /** @name Account Placeholder flag 1201 @{ 1202 */ 1203 1204 /** Get the "placeholder" flag for an account. If this flag is set 1205 * then the account may not be modified by the user. 1206 * 1207 * @param account The account whose flag should be retrieved. 1208 * 1209 * @return The current state of the account's "placeholder" flag. */ 1210 gboolean xaccAccountGetPlaceholder (const Account *account); 1211 1212 /** Set the "placeholder" flag for an account. If this flag is set 1213 * then the account may not be modified by the user. 1214 * 1215 * @param account The account whose flag should be retrieved. 1216 * 1217 * @param val The new state for the account's "placeholder" flag. */ 1218 void xaccAccountSetPlaceholder (Account *account, gboolean val); 1219 1220 /** @name Account Append Text flag 1221 @{ 1222 */ 1223 1224 /** Get the "import-append-text" flag for an account. This is the saved 1225 * state of the Append checkbox in the "Generic import transaction matcher" 1226 * used to set the initial state of the Append checkbox next time this 1227 * account is imported. 1228 * 1229 * @param account The account whose flag should be retrieved. 1230 * 1231 * @return The current state of the account's "import-append-text" flag. */ 1232 gboolean xaccAccountGetAppendText (const Account *account); 1233 1234 /** Set the "import-append-text" flag for an account. This is the saved 1235 * state of the Append checkbox in the "Generic import transaction matcher" 1236 * used to set the initial state of the Append checkbox next time this 1237 * account is imported. 1238 * 1239 * @param account The account whose flag should be retrieved. 1240 * 1241 * @param val The new state for the account's "import-append-text" flag. */ 1242 void xaccAccountSetAppendText (Account *account, gboolean val); 1243 1244 /** Get the "opening-balance" flag for an account. If this flag is set 1245 * then the account is used for opening balance transactions. 1246 * 1247 * @param account The account whose flag should be retrieved. 1248 * 1249 * @return The current state of the account's "opening-balance" flag. */ 1250 gboolean xaccAccountGetIsOpeningBalance (const Account *account); 1251 1252 /** Set the "opening-balance" flag for an account. If this flag is set 1253 * then the account is used for opening balance transactions. 1254 * 1255 * @param account The account whose flag should be set. 1256 * 1257 * @param val The new state for the account's "opening-balance" flag. */ 1258 void xaccAccountSetIsOpeningBalance (Account *account, gboolean val); 1259 1260 /** Returns PLACEHOLDER_NONE if account is NULL or neither account nor 1261 * any descendant of account is a placeholder. If account is a 1262 * placeholder, returns PLACEHOLDER_THIS. Otherwise, if any 1263 * descendant of account is a placeholder, return PLACEHOLDER_CHILD. 1264 */ 1265 GNCPlaceholderType xaccAccountGetDescendantPlaceholder(const Account *account); 1266 /** @} */ 1267 1268 /** @name Account Hidden flag 1269 @{ 1270 */ 1271 1272 /** Get the "hidden" flag for an account. If this flag is set then 1273 * the account (and any children) will be hidden from the user unless 1274 * they explicitly ask to see them. 1275 * 1276 * @param acc The account whose flag should be retrieved. 1277 * 1278 * @return The current state of the account's "hidden" flag. */ 1279 gboolean xaccAccountGetHidden (const Account *acc); 1280 1281 /** Set the "hidden" flag for an account. If this flag is set then 1282 * the account (and any children) will be hidden from the user unless 1283 * they explicitly ask to see them. 1284 * 1285 * @param acc The account whose flag should be retrieved. 1286 * 1287 * @param val The new state for the account's "hidden" flag. */ 1288 void xaccAccountSetHidden (Account *acc, gboolean val); 1289 1290 /** Should this account be "hidden". If this flag is set for this 1291 * account (or any parent account) then the account should be hidden 1292 * from the user unless they explicitly ask to see it. This function 1293 * is different from the xaccAccountGetHidden() function because it 1294 * checks the flag in parent accounts in addition to this account. 1295 * 1296 * @param acc The account whose flag should be retrieved. 1297 * 1298 * @return Whether or not this account should be "hidden". */ 1299 gboolean xaccAccountIsHidden (const Account *acc); 1300 /** @} */ 1301 1302 /** @name Account Auto Interest flag 1303 @{ 1304 */ 1305 1306 /** Get the "auto interest" flag for an account. If this flag is set then 1307 * the account (and any children) will trigger an interest transfer after reconciling. 1308 * 1309 * @param acc The account whose flag should be retrieved. 1310 * 1311 * @return The current state of the account's "auto interest" flag. */ 1312 gboolean xaccAccountGetAutoInterest (const Account *acc); 1313 1314 /** Set the "auto interest" flag for an account. If this flag is set then 1315 * the account (and any children) will trigger an interest transfer after reconciling. 1316 * 1317 * @param acc The account whose flag should be retrieved. 1318 * 1319 * @param val The new state for the account's "auto interest" flag. */ 1320 void xaccAccountSetAutoInterest (Account *acc, gboolean val); 1321 1322 /** @} */ 1323 1324 1325 /** @name Account Tax related getters/setters 1326 @{ 1327 */ 1328 1329 /** DOCUMENT ME! */ 1330 gboolean xaccAccountGetTaxRelated (const Account *account); 1331 /** DOCUMENT ME! */ 1332 void xaccAccountSetTaxRelated (Account *account, gboolean tax_related); 1333 /** DOCUMENT ME! */ 1334 const char * xaccAccountGetTaxUSCode (const Account *account); 1335 /** DOCUMENT ME! */ 1336 void xaccAccountSetTaxUSCode (Account *account, const char *code); 1337 /** DOCUMENT ME! */ 1338 const char * xaccAccountGetTaxUSPayerNameSource (const Account *account); 1339 /** DOCUMENT ME! */ 1340 void xaccAccountSetTaxUSPayerNameSource (Account *account, const char *source); 1341 /** DOCUMENT ME! */ 1342 gint64 xaccAccountGetTaxUSCopyNumber (const Account *account); 1343 /** DOCUMENT ME! */ 1344 void xaccAccountSetTaxUSCopyNumber (Account *account, gint64 copy_number); 1345 /** @} */ 1346 1347 /** @name Account type debit/credit string getters 1348 @ { * 1349 */ 1350 1351 /** Get the debit string associated with this account type */ 1352 const char *gnc_account_get_debit_string (GNCAccountType acct_type); 1353 /** Get the credit string associated with this account type */ 1354 const char *gnc_account_get_credit_string (GNCAccountType acct_type); 1355 1356 /** @} */ 1357 1358 1359 /** @name Account marking 1360 @{ 1361 */ 1362 /** Set a mark on the account. The meaning of this mark is 1363 * completely undefined. Its presented here as a utility for the 1364 * programmer, to use as desired. Handy for performing customer traversals 1365 * over the account tree. The mark is *not* stored in the database/file 1366 * format. When accounts are newly created, the mark is set to zero. 1367 */ 1368 void xaccAccountSetMark (Account *account, short mark); 1369 1370 /** Get the mark set by xaccAccountSetMark 1371 short xaccAccountGetMark (const Account *account); 1372 */ 1373 /** The xaccClearMark will find the root account, and clear the mark in 1374 * the entire account tree. */ 1375 void xaccClearMark (Account *account, short val); 1376 1377 /** The xaccClearMarkDown will clear the mark only in this and in 1378 * sub-accounts.*/ 1379 void xaccClearMarkDown (Account *account, short val); 1380 /** @} */ 1381 1382 /** @name Staged Traversal 1383 1384 * The following functions provide support for "staged traversals" 1385 * over all of the transactions in an account or group. The idea 1386 * is to be able to perform a sequence of traversals ("stages"), 1387 * and perform an operation on each transaction exactly once 1388 * for that stage. 1389 * 1390 * Only transactions whose current "stage" is less than the 1391 * stage of the current traversal will be affected, and they will 1392 * be "brought up" to the current stage when they are processed. 1393 * 1394 * For example, you could perform a stage 1 traversal of all the 1395 * transactions in an account, and then perform a stage 1 traversal of 1396 * the transactions in a second account. Presuming the traversal of 1397 * the first account didn't abort prematurely, any transactions shared 1398 * by both accounts would be ignored during the traversal of the 1399 * second account since they had been processed while traversing the 1400 * first account. 1401 * 1402 * However, if you had traversed the second account using a stage 1403 * of 2, then all the transactions in the second account would have 1404 * been processed. 1405 * 1406 * Traversal can be aborted by having the callback function return 1407 * a non-zero value. The traversal is aborted immediately, and the 1408 * non-zero value is returned. Note that an aborted traversal can 1409 * be restarted; no information is lost due to an abort. 1410 * 1411 * The initial impetus for this particular approach came from 1412 * generalizing a mark/sweep practice that was already being 1413 * used in FileIO.c. 1414 * 1415 * Note that currently, there is a hard limit of 256 stages, which 1416 * can be changed by enlarging "marker" in the transaction struct. 1417 * 1418 @{ 1419 */ 1420 /** gnc_account_tree_begin_staged_transaction_traversals() 1421 * resets the traversal marker inside every transactions of every 1422 * account in the account tree originating with the specified node. 1423 * This is done so that a new sequence of staged traversals can 1424 * begin. 1425 */ 1426 void gnc_account_tree_begin_staged_transaction_traversals(Account *acc); 1427 1428 /** xaccSplitsBeginStagedTransactionTraversals() resets the traversal 1429 * marker for each transaction which is a parent of one of the 1430 * splits in the list. 1431 */ 1432 void xaccSplitsBeginStagedTransactionTraversals(SplitList *splits); 1433 1434 /** xaccAccountBeginStagedTransactionTraversals() resets the traversal 1435 * marker for each transaction which is a parent of one of the 1436 * splits in the account. 1437 */ 1438 void xaccAccountBeginStagedTransactionTraversals(const Account *account); 1439 1440 /** xaccTransactionTraverse() checks the stage of the given transaction. 1441 * If the transaction hasn't reached the given stage, the transaction 1442 * is updated to that stage and the function returns TRUE. Otherwise 1443 * no change is made and the function returns FALSE. 1444 */ 1445 gboolean xaccTransactionTraverse(Transaction *trans, int stage); 1446 1447 /** xaccAccountStagedTransactionTraversal() calls @a thunk on each 1448 * transaction in account @a a whose current marker is less than the 1449 * given @a stage and updates each transaction's marker to be @a stage. 1450 * The traversal will stop if @a thunk returns a non-zero value. 1451 * xaccAccountStagedTransactionTraversal() function will return zero 1452 * or the non-zero value returned by @a thunk. 1453 * This API does not handle handle recursive traversals. 1454 * 1455 * \warning For performance reasons, the transaction callback @a thunk 1456 * must never destroy any of the transaction's splits, nor assign any 1457 * of them to a different account. <b>To do so risks a crash.</b> 1458 */ 1459 1460 int xaccAccountStagedTransactionTraversal(const Account *a, 1461 unsigned int stage, 1462 TransactionCallback thunk, 1463 void *data); 1464 1465 /** gnc_account_tree_staged_transaction_traversal() calls @a thunk on each 1466 * transaction in the group whose current marker is less than the 1467 * given @a stage and updates each transaction's marker to be @a stage. 1468 * The traversal will stop if @a thunk returns a non-zero value. 1469 * gnc_account_tree_staged_transaction_traversal() function will return zero 1470 * or the non-zero value returned by @a thunk. This 1471 * API does not handle handle recursive traversals. 1472 * 1473 * \warning For performance reasons, the transaction callback @a thunk 1474 * must never destroy any of the transaction's splits, nor assign any 1475 * of them to a different account. <b>To do so risks a crash.</b> 1476 */ 1477 1478 int gnc_account_tree_staged_transaction_traversal(const Account *account, 1479 unsigned int stage, 1480 TransactionCallback thunk, 1481 void *data); 1482 1483 /** Traverse all of the transactions in the given account group. 1484 * Continue processing IF @a proc returns 0. This function 1485 * will descend recursively to traverse transactions in the 1486 * children of the accounts in the group. 1487 * 1488 * @a Proc will be called exactly once for each transaction that is 1489 * pointed to by at least one split in any account in the hierarchy 1490 * topped by the root Account @a acc. 1491 * 1492 * The result of this function will be 0 IF every relevant 1493 * transaction was traversed exactly once; otherwise, the return 1494 * value is the last non-zero value returned by the callback. 1495 * 1496 * \warning For performance reasons, the transaction callback @a proc 1497 * must never destroy any of the transaction's splits, nor assign any 1498 * of them to a different account. <b>To do so risks a crash.</b> 1499 * 1500 * \warning The traversal occurs only over the transactions that 1501 * are locally cached in the local gnucash engine. If the gnucash 1502 * engine is attached to a remote database, the database may contain 1503 * (many) transactions that are not mirrored in the local cache. 1504 * This routine will not cause an SQL database query to be performed; 1505 * it will not traverse transactions present only in the remote 1506 * database. 1507 * 1508 * Note that this routine is just a trivial wrapper for 1509 * 1510 * gnc_account_tree_begin_staged_transaction_traversals(g); 1511 * gnc_account_tree_staged_transaction_traversal(g, 42, proc, data); 1512 */ 1513 1514 int xaccAccountTreeForEachTransaction(Account *acc, 1515 TransactionCallback proc, void *data); 1516 1517 /** Obtain an ImportMatchMap object from an Account or a Book 1518 */ 1519 GncImportMatchMap *gnc_account_imap_create_imap (Account *acc); 1520 1521 /* Look up an Account in the map non-Baysian 1522 */ 1523 Account* gnc_account_imap_find_account (GncImportMatchMap *imap, const char* category, 1524 const char *key); 1525 1526 /* Store an Account in the map non Baysian 1527 */ 1528 void gnc_account_imap_add_account (GncImportMatchMap *imap, const char *category, 1529 const char *key, Account *acc); 1530 1531 /* Remove a reference to an Account in the map non Baysian 1532 */ 1533 void gnc_account_imap_delete_account (GncImportMatchMap *imap, const char *category, 1534 const char *key); 1535 1536 /** Look up an Account in the map using Baysian 1537 */ 1538 Account* gnc_account_imap_find_account_bayes (GncImportMatchMap *imap, GList* tokens); 1539 1540 /** Updates the imap for a given account using a list of tokens 1541 */ 1542 void gnc_account_imap_add_account_bayes (GncImportMatchMap *imap, GList* tokens, 1543 Account *acc); 1544 1545 typedef struct imap_info 1546 { 1547 Account *source_account; 1548 Account *map_account; 1549 GList *list; 1550 char *head; 1551 char *category; 1552 char *match_string; 1553 char *count; 1554 }GncImapInfo; 1555 1556 /** Returns a GList of structure imap_info of all Bayesian mappings for 1557 * required Account 1558 */ 1559 GList *gnc_account_imap_get_info_bayes (Account *acc); 1560 1561 /** Returns a GList of structure imap_info of all Non Bayesian mappings for 1562 * required Account 1563 */ 1564 GList *gnc_account_imap_get_info (Account *acc, const char *category); 1565 1566 /** Returns the text string pointed to by head and category for the Account, free 1567 * the returned text 1568 */ 1569 gchar *gnc_account_get_map_entry (Account *acc, const char *head, const char *category); 1570 1571 /** Delete the entry for Account pointed to by head,category and match_string, 1572 * if empty is TRUE then use delete if empty 1573 */ 1574 void gnc_account_delete_map_entry (Account *acc, char *head, char *category, 1575 char *match_string, gboolean empty); 1576 1577 /** Delete all bayes entries for Account 1578 */ 1579 void gnc_account_delete_all_bayes_maps (Account *acc); 1580 1581 /** Reset the flag that indicates the function imap_convert_bayes_to_flat 1582 * has been run 1583 */ 1584 void gnc_account_reset_convert_bayes_to_flat (void); 1585 1586 /** @} */ 1587 1588 1589 /** @name Deprecated Routines. 1590 @{ 1591 */ 1592 1593 /** @deprecated The current API associates only one thing with an 1594 * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch 1595 * it. 1596 * 1597 * These two funcs take control of their gnc_commodity args. Don't free */ 1598 void DxaccAccountSetCurrency (Account *account, gnc_commodity *currency); 1599 1600 /** @deprecated The current API associates only one thing with an 1601 * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch 1602 * it. */ 1603 gnc_commodity * DxaccAccountGetCurrency (const Account *account); 1604 1605 /** Set the timezone to be used when interpreting the results from a 1606 * given Finance::Quote backend. Unfortunately, the upstream sources 1607 * don't label their output, so the user has to specify this bit. 1608 * 1609 * @deprecated Price quote information is now stored on the 1610 * commodity, not the account. */ 1611 1612 void dxaccAccountSetQuoteTZ (Account *account, const char *tz); 1613 /** Get the timezone to be used when interpreting the results from a 1614 * given Finance::Quote backend. Unfortunately, the upstream sources 1615 * don't label their output, so the user has to specify this 1616 * bit. This function uses a static char*. 1617 * 1618 * @deprecated Price quote information is now stored on the 1619 * commodity, not the account. */ 1620 const char * dxaccAccountGetQuoteTZ (const Account *account); 1621 /** @} */ 1622 1623 1624 /** @name Account parameter names 1625 @{ 1626 */ 1627 #define ACCOUNT_KVP "kvp" 1628 #define ACCOUNT_NAME_ "name" 1629 #define ACCOUNT_CODE_ "code" 1630 #define ACCOUNT_DESCRIPTION_ "desc" 1631 #define ACCOUNT_COLOR_ "color" 1632 #define ACCOUNT_FILTER_ "filter" 1633 #define ACCOUNT_SORT_ORDER_ "sort-order" 1634 #define ACCOUNT_SORT_REVERSED_ "sort-reversed" 1635 #define ACCOUNT_NOTES_ "notes" 1636 #define ACCOUNT_BALANCE_ "balance" 1637 #define ACCOUNT_NOCLOSING_ "noclosing" 1638 #define ACCOUNT_OPENING_BALANCE_ "opening-balance" 1639 #define ACCOUNT_CLEARED_ "cleared" 1640 #define ACCOUNT_RECONCILED_ "reconciled" 1641 #define ACCOUNT_PRESENT_ "present" 1642 #define ACCOUNT_FUTURE_MINIMUM_ "future-minimum" 1643 #define ACCOUNT_TAX_RELATED "tax-related-p" 1644 #define ACCOUNT_TYPE_ "account-type" 1645 #define ACCOUNT_SCU "smallest-commodity-unit" 1646 #define ACCOUNT_NSCU "non-standard-scu" 1647 #define ACCOUNT_PARENT "parent-account" 1648 1649 /** @} */ 1650 1651 /** This is the type-override when you want to match all accounts. Used 1652 * in the gnome-search parameter list. Be careful when you use this. */ 1653 #define ACCOUNT_MATCH_ALL_TYPE "account-match-all" 1654 1655 #ifdef __cplusplus 1656 } /* extern "C" */ 1657 #endif 1658 1659 #endif /* XACC_ACCOUNT_H */ 1660 /** @} */ 1661 /** @} */ 1662