GnuCash Engine: Core, Non-GUI Accounting Functions

Detailed Description

The GnuCash Engine provides a set of objects and classes that encapsulate typical financial accounting concepts. The GnuCash GUI is expected to manipulate these objects through the provided engine API.

Files

file gnc-engine.h

All type declarations for the whole Gnucash engine.

Modules

Business

Account

Cap Gains

Commodities

Lots: Core Function for AR/AP, Inventory, Stock Lots, Cap Gains

Price Database

Prices

Accounting Periods

Accounting Policy (FIFO/LIFO)

Scheduled/Periodic/Recurring Transactions

Data Validation

Financial Transactions

Transaction Logging

Lookup Accounts and Subaccounts by name or code

Account * gnc_account_lookup_by_name (const Account *parent, const char *name)

Account * gnc_account_lookup_by_full_name (const Account *any_account, const gchar *name)

Account * gnc_account_lookup_by_code (const Account *parent, const char *code)

GNCAccountType conversion/checking

const char * xaccAccountTypeEnumAsString (GNCAccountType type)

gboolean xaccAccountStringToType (const char *str, GNCAccountType *type)

GNCAccountType xaccAccountStringToEnum (const char *str)

const char * xaccAccountGetTypeStr (GNCAccountType type)

GNCAccountType xaccAccountGetTypeFromStr (const gchar *str)

guint32 xaccParentAccountTypesCompatibleWith (GNCAccountType type)

gboolean xaccAccountTypesCompatible (GNCAccountType parent_type, GNCAccountType child_type)

guint32 xaccAccountTypesValid (void)

Account split/transaction list management

SplitList * xaccAccountGetSplitList (const Account *account)

void xaccAccountMoveAllSplits (Account *accfrom, Account *accto)

gint xaccAccountForEachTransaction (const Account *account, TransactionCallback proc, void *data)

Transaction * xaccAccountFindTransByDesc (const Account *account, const char *description)

Split * xaccAccountFindSplitByDesc (const Account *account, const char *description)

#define xaccAccountInsertSplit(acc, s)   xaccSplitSetAccount((s), (acc))

Account lots

void xaccAccountInsertLot (Account *, GNCLot *)

void xaccAccountRemoveLot (Account *, GNCLot *)

LotList * xaccAccountGetLotList (const Account *account)

gpointer xaccAccountForEachLot (const Account *acc, gpointer(*proc)(GNCLot *lot, gpointer user_data), gpointer user_data)

LotList * xaccAccountFindOpenLots (const Account *acc, gboolean(*match_func)(GNCLot *lot, gpointer user_data), gpointer user_data, GCompareFunc sort_func)

Account Reconciliation information getters/setters

gboolean xaccAccountGetReconcileLastDate (const Account *account, time_t *last_date)

void xaccAccountSetReconcileLastDate (Account *account, time_t last_date)

gboolean xaccAccountGetReconcileLastInterval (const Account *account, int *months, int *days)

void xaccAccountSetReconcileLastInterval (Account *account, int months, int days)

gboolean xaccAccountGetReconcilePostponeDate (const Account *account, time_t *postpone_date)

void xaccAccountSetReconcilePostponeDate (Account *account, time_t postpone_date)

gboolean xaccAccountGetReconcilePostponeBalance (const Account *account, gnc_numeric *balance)

void xaccAccountSetReconcilePostponeBalance (Account *account, gnc_numeric balance)

void xaccAccountClearReconcilePostpone (Account *account)

Account Placeholder flag

gboolean xaccAccountGetPlaceholder (const Account *account)

void xaccAccountSetPlaceholder (Account *account, gboolean val)

GNCPlaceholderType xaccAccountGetDescendantPlaceholder (const Account *account)

Account Hidden flag

gboolean xaccAccountGetHidden (const Account *acc)

void xaccAccountSetHidden (Account *acc, gboolean val)

gboolean xaccAccountIsHidden (const Account *acc)

Account Tax related getters/setters

gboolean xaccAccountGetTaxRelated (const Account *account)

void xaccAccountSetTaxRelated (Account *account, gboolean tax_related)

const char * xaccAccountGetTaxUSCode (const Account *account)

void xaccAccountSetTaxUSCode (Account *account, const char *code)

const char * xaccAccountGetTaxUSPayerNameSource (const Account *account)

void xaccAccountSetTaxUSPayerNameSource (Account *account, const char *source)

Account marking

void xaccAccountSetMark (Account *account, short mark)

short xaccAccountGetMark (const Account *account)

void xaccClearMark (Account *account, short val)

void xaccClearMarkDown (Account *account, short val)

Staged Traversal

The following functions provide support for "staged traversals" over all of the transactions in an account or group. The idea is to be able to perform a sequence of traversals ("stages"), and perform an operation on each transaction exactly once for that stage.
Only transactions whose current "stage" is less than the stage of the current traversal will be affected, and they will be "brought up" to the current stage when they are processed.
For example, you could perform a stage 1 traversal of all the transactions in an account, and then perform a stage 1 traversal of the transactions in a second account. Presuming the traversal of the first account didn't abort prematurely, any transactions shared by both accounts would be ignored during the traversal of the second account since they had been processed while traversing the first account.
However, if you had traversed the second account using a stage of 2, then all the transactions in the second account would have been processed.
Traversal can be aborted by having the callback function return a non-zero value. The traversal is aborted immediately, and the non-zero value is returned. Note that an aborted traversal can be restarted; no information is lost due to an abort.
The initial impetus for this particular approach came from generalizing a mark/sweep practice that was already being used in FileIO.c.
Note that currently, there is a hard limit of 256 stages, which can be changed by enlarging "marker" in the transaction struct.

void gnc_account_tree_begin_staged_transaction_traversals (Account *acc)

void xaccSplitsBeginStagedTransactionTraversals (SplitList *splits)

void xaccAccountBeginStagedTransactionTraversals (const Account *account)

gboolean xaccTransactionTraverse (Transaction *trans, int stage)

gboolean xaccSplitTransactionTraverse (Split *split, int stage)

int xaccAccountStagedTransactionTraversal (const Account *a, unsigned int stage, TransactionCallback thunk, void *data)

int gnc_account_tree_staged_transaction_traversal (const Account *account, unsigned int stage, TransactionCallback thunk, void *data)

int xaccAccountTreeForEachTransaction (Account *acc, TransactionCallback proc, void *data)

Deprecated Routines.

void DxaccAccountSetCurrency (Account *account, gnc_commodity *currency)

gnc_commodity * DxaccAccountGetCurrency (const Account *account)

void dxaccAccountSetQuoteTZ (Account *account, const char *tz)

const char * dxaccAccountGetQuoteTZ (const Account *account)

Account parameter names

#define ACCOUNT_KVP   "kvp"

#define ACCOUNT_NAME_   "name"

#define ACCOUNT_CODE_   "code"

#define ACCOUNT_DESCRIPTION_   "desc"

#define ACCOUNT_NOTES_   "notes"

#define ACCOUNT_BALANCE_   "balance"

#define ACCOUNT_CLEARED_   "cleared"

#define ACCOUNT_RECONCILED_   "reconciled"

#define ACCOUNT_PRESENT_   "present"

#define ACCOUNT_FUTURE_MINIMUM_   "future-minimum"

#define ACCOUNT_TAX_RELATED   "tax-related-p"

#define ACCOUNT_TYPE_   "account-type"

#define ACCOUNT_SCU   "smallest-commodity-unit"

#define ACCOUNT_NSCU   "non-standard-scu"

#define ACCOUNT_PARENT   "parent-account"

QofLogModule identifiers

#define GNC_MOD_ROOT   "gnc"

#define GNC_MOD_ENGINE   "gnc.engine"

#define GNC_MOD_ACCOUNT   "gnc.account"

#define GNC_MOD_SX   "gnc.engine.sx"

#define GNC_MOD_QUERY   "gnc.query"

#define GNC_MOD_SCRUB   "gnc.scrub"

#define GNC_MOD_LOT   "gnc.lots"

#define GNC_MOD_COMMODITY   "gnc.commodity"

#define GNC_MOD_BACKEND   "gnc.backend"

#define GNC_MOD_PRICE   "gnc.pricedb"

#define GNC_MOD_BUSINESS   "gnc.business"

#define GNC_MOD_IO   "gnc.io"

#define GNC_MOD_BOOK   "gnc.book-period"

#define GNC_MOD_GUI   "gnc.gui"

#define GNC_MOD_GUI_SX   "gnc.gui.sx"

#define GNC_MOD_GUILE   "gnc.guile"

#define GNC_MOD_LEDGER   "gnc.ledger"

#define GNC_MOD_REGISTER   "gnc.register"

#define GNC_MOD_HTML   "gnc.html"

#define GNC_MOD_PREFS   "gnc.pref"

#define GNC_MOD_IMPORT   "gnc.import"

#define GNC_MOD_DRUID   "gnc.druids"

#define GNC_MOD_TEST   "gnc.tests"

#define GNC_MOD_BUDGET   "gnc.budget"

Defines

#define ACCOUNT_MATCH_ALL_TYPE   "account-match-all"

#define GNC_ID_NONE   QOF_ID_NONE

IDENTIFIERS GUID Identifiers can be used to reference Accounts, Transactions, Splits and other objects. These Gnucash types are referred to as Gnucash entities. GUID Identifiers are globally-unique and permanent, i.e., once an entity has been assigned an identifier, it retains that same identifier for its lifetime.

Identifiers are 'typed' with strings. The ids used in gnucash are defined below. An id with type GNC_ID_NONE does not refer to any entity, although that may change as new ids are created. An id with type GNC_ID_NULL does not refer to any entity, and will never refer to any entity. An identifier with any other type may refer to an actual entity, but that is not guaranteed. If an id does refer to an entity, the type of the entity will match the type of the identifier.

#define GNC_ID_BOOK   QOF_ID_BOOK

#define GNC_ID_SESSION   QOF_ID_SESSION

#define GNC_ID_NULL   QOF_ID_NULL

#define GNC_ID_ACCOUNT   "Account"

#define GNC_ID_COMMODITY   "Commodity"

#define GNC_ID_COMMODITY_NAMESPACE   "CommodityNamespace"

#define GNC_ID_COMMODITY_TABLE   "CommodityTable"

#define GNC_ID_LOT   "Lot"

#define GNC_ID_PERIOD   "Period"

#define GNC_ID_PRICE   "Price"

#define GNC_ID_PRICEDB   "PriceDB"

#define GNC_ID_SPLIT   "Split"

#define GNC_ID_BUDGET   "Budget"

#define GNC_ID_SCHEDXACTION   "SchedXaction"

#define GNC_ID_SXES   "SchedXactions"

#define GNC_ID_SXTG   "SXTGroup"

#define GNC_ID_SXTT   "SXTTrans"

#define GNC_ID_TRANS   "Trans"

Typedefs

typedef account_s Account

Account in Gnucash. This is the typename for an account. The actual structure is defined in the private header AccountP.h, but no one outside the engine should include that file. Instead, access that data only through the functions in Account.h .

typedef split_s Split

Split in Gnucash. A "split" is more commonly refered to as a "entry" in a "transaction". Each split belongs to one Account and one Transaction. The split is one out of several parts a Transaction is divided into.

typedef transaction_s Transaction

Transaction in Gnucash. A Transaction is a piece of business done; the transfer of money from one account to one or more other accounts. Each Transaction is divided into one or more Splits (usually two).

typedef gnc_commodity_s gnc_commodity

An article that is bought and sold. A Commodity is the most general term of what an account keeps track of. Usually this is a monetary currency, but it can also be a stock share or even a precious metal. Every account keeps track of exactly one gnc_commodity.

typedef gnc_commodity_namespace_s gnc_commodity_namespace

A gnc_commodity_namespace is an collection of commodities.

typedef gnc_commodity_table_s gnc_commodity_table

A gnc_commodity_table is a database of commodity info.

typedef gnc_lot_struct GNCLot

Identifies that something sold at one time was bought at another. A GNCLot provides a way of tracking physical items as they are bought and sold in different transactions. By identifying the individual, underlying physical objects, it provides the needed framework for implementing depreciation, capital gains, inventory control and invoices.

typedef gnc_price_s GNCPrice

Price of commodity on a given date. A GNCPrice encapsulates price information: the cost of a commodity expressed as a currency, on a given date. It also holds info about the provenance of the price: where it came from, its general validity.

typedef gnc_quote_source_s gnc_quote_source

typedef GList AccountList

typedef GList LotList

typedef GList SplitList

typedef GList TransList

typedef GList AccountGUIDList

typedef GList BookGUIDList

typedef gint(*) SplitCallback (Split *s, gpointer data)

typedef gint(*) TransactionCallback (Transaction *t, void *data)

typedef void(*) gnc_engine_init_hook_t (int, char **)

Enumerations

enum GNCPlaceholderType { PLACEHOLDER_NONE, PLACEHOLDER_THIS, PLACEHOLDER_CHILD }

Functions

unsigned int gnucash_major_version (void)

unsigned int gnucash_minor_version (void)

unsigned int gnucash_micro_version (void)

void gnc_engine_init (int argc, char **argv)

void gnc_engine_shutdown (void)

gboolean gnc_engine_is_initialized (void)

void gnc_log_default (void)

void gnc_engine_add_init_hook (gnc_engine_init_hook_t hook)

Define Documentation

#define ACCOUNT_MATCH_ALL_TYPE "account-match-all"

This is the type-override when you want to match all accounts. Used in the gnome-search parameter list. Be careful when you use this.

Definition at line 1421 of file Account.h.

#define xaccAccountInsertSplit	(	acc,
		s		)	xaccSplitSetAccount((s), (acc))

The xaccAccountInsertSplit() method will insert the indicated split into the indicated account. If the split already belongs to another account, it will be removed from that account first.

Definition at line 967 of file Account.h.

Typedef Documentation

typedef GList AccountGUIDList

GList of GUIDs of a Account

Definition at line 207 of file gnc-engine.h.

typedef GList AccountList

GList of Account

Definition at line 199 of file gnc-engine.h.

typedef GList BookGUIDList

GList of GUIDs of a GNCBook

Definition at line 209 of file gnc-engine.h.

typedef struct gnc_commodity_s gnc_commodity

An article that is bought and sold. A Commodity is the most general term of what an account keeps track of. Usually this is a monetary currency, but it can also be a stock share or even a precious metal. Every account keeps track of exactly one gnc_commodity.

(Up to version 1.6.x, we used to have currencies and securities. Now these concepts have been merged into this gnc_commodity. See the comments at xaccAccountSetCommodity() for more about that.)

This is the typename for a gnc_commodity. The actual structure is defined in a private source file. For accessing that data, only use the functions in gnc-commodity.h .

Definition at line 171 of file gnc-engine.h.

typedef void(* ) gnc_engine_init_hook_t(int, char **)

Function type for init hooks in the engine.

Definition at line 216 of file gnc-engine.h.

typedef struct gnc_lot_struct GNCLot

Identifies that something sold at one time was bought at another. A GNCLot provides a way of tracking physical items as they are bought and sold in different transactions. By identifying the individual, underlying physical objects, it provides the needed framework for implementing depreciation, capital gains, inventory control and invoices.

See the file src/doc/lots.txt for implmentation overview.

Definition at line 188 of file gnc-engine.h.

typedef GList LotList

GList of GNCLots

Definition at line 201 of file gnc-engine.h.

typedef struct split_s Split

Split in Gnucash. A "split" is more commonly refered to as a "entry" in a "transaction". Each split belongs to one Account and one Transaction. The split is one out of several parts a Transaction is divided into.

This is the typename for a split. The actual structure is defined in the private header TransactionP.h, but no one outside the engine should include that file. Instead, access that data only through the functions in Transaction.h .

Definition at line 144 of file gnc-engine.h.

typedef GList SplitList

GList of Split

Definition at line 203 of file gnc-engine.h.

typedef struct transaction_s Transaction

Transaction in Gnucash. A Transaction is a piece of business done; the transfer of money from one account to one or more other accounts. Each Transaction is divided into one or more Splits (usually two).

This is the typename for a transaction. The actual structure is defined in the private header TransactionP.h, but no one outside the engine should include that file. Instead, access that data only through the functions in Transaction.h .

Definition at line 155 of file gnc-engine.h.

typedef GList TransList

GList of Transaction

Definition at line 205 of file gnc-engine.h.

Enumeration Type Documentation

enum GNCPlaceholderType

DOCUMENT ME!

Enumerator:

PLACEHOLDER_NONE
PLACEHOLDER_THIS
PLACEHOLDER_CHILD

Definition at line 1110 of file Account.h.

01111   {
01112   PLACEHOLDER_NONE,
01113   PLACEHOLDER_THIS,
01114   PLACEHOLDER_CHILD,
01115   } GNCPlaceholderType;

Function Documentation

gnc_commodity* DxaccAccountGetCurrency ( const Account * account )

Deprecated:: The current API associates only one thing with an account: the 'commodity'. Use xaccAccountGetCommodity() to fetch it.

Definition at line 2807 of file Account.c.

02808 {
02809   KvpValue *v;
02810   const char *s;
02811   gnc_commodity_table *table;
02812 
02813   if (!acc) return NULL;
02814 
02815   v = kvp_frame_get_slot(acc->inst.kvp_data, "old-currency");
02816   if (!v) return NULL;
02817 
02818   s = kvp_value_get_string (v);
02819   if (!s) return NULL;
02820 
02821   table = gnc_commodity_table_get_table (qof_instance_get_book(acc));
02822 
02823   return gnc_commodity_table_lookup_unique (table, s);
02824 }

const char* dxaccAccountGetQuoteTZ ( const Account * account )

Get the timezone to be used when interpreting the results from a given Finance::Quote backend. Unfortunately, the upstream sources don't label their output, so the user has to specify this bit.

Deprecated:: Price quote information is now stored on the commodity, not the account.

Definition at line 4109 of file Account.c.

04110 {
04111   if (!acc) return NULL;
04112 
04113   if (xaccAccountIsPriced(acc)) {
04114       KvpValue *value = kvp_frame_get_slot(acc->inst.kvp_data, "old-quote-tz");
04115       if(value) return (kvp_value_get_string(value));
04116   }
04117   return NULL;
04118 }

void DxaccAccountSetCurrency	(	Account *	account,
		gnc_commodity *	currency
	)

Deprecated:: The current API associates only one thing with an account: the 'commodity'. Use xaccAccountGetCommodity() to fetch it.

These two funcs take control of their gnc_commodity args. Don't free

Definition at line 2193 of file Account.c.

02194 {
02195   QofBook *book;
02196   const char *string;
02197   gnc_commodity *commodity;
02198 
02199   if ((!acc) || (!currency)) return;
02200 
02201   xaccAccountBeginEdit(acc);
02202   string = gnc_commodity_get_unique_name (currency);
02203   kvp_frame_set_slot_nc(acc->inst.kvp_data, "old-currency",
02204                         kvp_value_new_string(string));
02205   mark_account (acc);
02206   xaccAccountCommitEdit(acc);
02207 
02208   commodity = DxaccAccountGetCurrency (acc);
02209   if (!commodity)
02210   {
02211     book = qof_instance_get_book(acc);
02212     gnc_commodity_table_insert (gnc_commodity_table_get_table (book), currency);
02213   }
02214 }

void dxaccAccountSetQuoteTZ	(	Account *	account,
		const char *	tz
	)

Set the timezone to be used when interpreting the results from a given Finance::Quote backend. Unfortunately, the upstream sources don't label their output, so the user has to specify this bit.

Deprecated:: Price quote information is now stored on the commodity, not the account.

Definition at line 4090 of file Account.c.

04091 {
04092   if (!acc) return;
04093 
04094   xaccAccountBeginEdit(acc);
04095   if (xaccAccountIsPriced(acc)) {
04096       kvp_frame_set_slot_nc(acc->inst.kvp_data,
04097                             "old-quote-tz",
04098                             tz ? kvp_value_new_string(tz) : NULL);
04099       mark_account (acc);
04100   }
04101   qof_instance_set_dirty(&acc->inst);
04102   xaccAccountCommitEdit(acc);
04103 }

Account* gnc_account_lookup_by_code	(	const Account *	parent,
		const char *	code
	)

The gnc_account_lookup_full_name() subroutine works like gnc_account_lookup_by_name, but uses the account code.

Definition at line 2523 of file Account.c.

02524 {
02525   AccountPrivate *cpriv, *ppriv;
02526   Account *child, *result;
02527   GList *node;
02528 
02529   g_return_val_if_fail(GNC_IS_ACCOUNT(parent), NULL);
02530   g_return_val_if_fail(code, NULL);
02531 
02532   /* first, look for accounts hanging off the current node */
02533   ppriv = GET_PRIVATE(parent);
02534   for (node = ppriv->children; node; node = node->next)
02535   {
02536     child = node->data;
02537     cpriv = GET_PRIVATE(child);
02538     if (safe_strcmp(cpriv->accountCode, code) == 0)
02539       return child;
02540   }
02541 
02542   /* if we are still here, then we haven't found the account yet.
02543    * Recursively search each of the child accounts next */
02544   for (node = ppriv->children; node; node = node->next)
02545   {
02546     child = node->data;
02547     result = gnc_account_lookup_by_code (child, code);
02548     if (result)
02549       return result;
02550   }
02551 
02552   return NULL;
02553 }

Account* gnc_account_lookup_by_full_name	(	const Account *	any_account,
		const gchar *	name
	)

The gnc_account_lookup_full_name() subroutine works like gnc_account_lookup_by_name, but uses fully-qualified names using the given separator.

Definition at line 2599 of file Account.c.

02601 {
02602   const AccountPrivate *rpriv;
02603   const Account *root;
02604   Account *found;
02605   gchar **names;
02606 
02607   g_return_val_if_fail(GNC_IS_ACCOUNT(any_acc), NULL);
02608   g_return_val_if_fail(name, NULL);
02609 
02610   root = any_acc;
02611   rpriv = GET_PRIVATE(root);
02612   while (rpriv->parent) {
02613     root = rpriv->parent;
02614     rpriv = GET_PRIVATE(root);
02615   }
02616   names = g_strsplit(name, gnc_get_account_separator_string(), -1);
02617   found = gnc_account_lookup_by_full_name_helper(root, names);
02618   g_strfreev(names);
02619   return found;
02620 }

Account* gnc_account_lookup_by_name	(	const Account *	parent,
		const char *	name
	)

The gnc_account_lookup_by_name() subroutine fetches the account by name from the descendants of the specified account. The immediate children are searched first. If there is no match,, then a recursive search of all descendants is performed looking for a match.

Returns:: A pointer to the account with the specified name, or NULL if the account was not found.

Definition at line 2490 of file Account.c.

02491 {
02492   AccountPrivate *cpriv, *ppriv;
02493   Account *child, *result;
02494   GList *node;
02495 
02496   g_return_val_if_fail(GNC_IS_ACCOUNT(parent), NULL);
02497   g_return_val_if_fail(name, NULL);
02498 
02499   /* first, look for accounts hanging off the current node */
02500   ppriv = GET_PRIVATE(parent);
02501   for (node = ppriv->children; node; node = node->next)
02502   {
02503     child = node->data;
02504     cpriv = GET_PRIVATE(child);
02505     if (safe_strcmp(cpriv->accountName, name) == 0)
02506       return child;
02507   }
02508 
02509   /* if we are still here, then we haven't found the account yet.
02510    * Recursively search each of the child accounts next */
02511   for (node = ppriv->children; node; node = node->next)
02512   {
02513     child = node->data;
02514     result = gnc_account_lookup_by_name (child, name);
02515     if (result)
02516       return result;
02517   }
02518 
02519   return NULL;
02520 }

void gnc_account_tree_begin_staged_transaction_traversals ( Account * acc )

gnc_account_tree_begin_staged_transaction_traversals() resets the traversal marker inside every transactions of every account in the account tree originating with the specified node. This is done so that a new sequence of staged traversals can begin.

Definition at line 4425 of file Account.c.

04426 {
04427   GList *descendants;
04428 
04429   descendants = gnc_account_get_descendants(account);
04430   g_list_foreach(descendants, (GFunc)do_one_account, NULL);
04431   g_list_free(descendants);
04432 }

int gnc_account_tree_staged_transaction_traversal	(	const Account *	account,
		unsigned int	stage,
		TransactionCallback	thunk,
		void *	data
	)

gnc_account_tree_staged_transaction_traversal() calls thunk on each transaction in the group whose current marker is less than the given stage and updates each transaction's marker to be stage. The traversal will stop if thunk returns a non-zero value. gnc_account_tree_staged_transaction_traversal() function will return zero or the non-zero value returned by thunk. This API does not handle handle recursive traversals.

Warning:: For performance reasons, the transaction callback thunk must never destroy any of the transaction's splits, nor assign any of them to a different account. To do so risks a crash.

Definition at line 4472 of file Account.c.

04476 {
04477   const AccountPrivate *priv;
04478   GList *acc_p, *split_p;
04479   Transaction *trans;
04480   Split *s;
04481   int retval;
04482 
04483   if (!acc) return 0;
04484 
04485   /* depth first traversal */
04486   priv = GET_PRIVATE(acc);
04487   for (acc_p = priv->children; acc_p; acc_p = g_list_next(acc_p)) {
04488     retval = gnc_account_tree_staged_transaction_traversal(acc_p->data, stage,
04489                                                    thunk, cb_data);
04490     if (retval) return retval;
04491   }
04492 
04493   /* Now this account */
04494   for(split_p = priv->splits; split_p; split_p = g_list_next(split_p)) {
04495     s = split_p->data;
04496     trans = s->parent;   
04497     if (trans && (trans->marker < stage)) {
04498       trans->marker = stage;
04499       if (thunk) {
04500         retval = thunk(trans, cb_data);
04501         if (retval) return retval;
04502       }
04503     }
04504   }
04505 
04506   return 0;
04507 }

void gnc_engine_add_init_hook ( gnc_engine_init_hook_t hook )

Pass a function pointer to gnc_engine_add_init_hook and it will be called during the evaluation of gnc_engine_init

Definition at line 146 of file gnc-engine.c.

00146                                                    {
00147   engine_init_hooks = g_list_append(engine_init_hooks, (gpointer)h);
00148 }

void gnc_engine_init	(	int	argc,
		char **	argv
	)

gnc_engine_init should be called before gnc engine functions can be used - see also qof_init for a method that does not require Guile.

Definition at line 73 of file gnc-engine.c.

00074 {
00075   static struct {
00076     const gchar* lib;
00077     gboolean required;
00078   } libs[] = {
00079 #if defined( HAVE_DBI_DBI_H )
00080     { "gncmod-backend-dbi", TRUE },
00081 #endif
00082 //    { "gncmod-backend-gda", TRUE },
00083     { "gncmod-backend-xml", TRUE },
00084     { NULL, FALSE } }, *lib;
00085   gnc_engine_init_hook_t hook;
00086   GList * cur;
00087   gchar *pkglibdir;
00088 
00089   if (1 == engine_is_initialized) return;
00090 
00091   /* initialize QOF */
00092   qof_init();
00093   qof_set_alt_dirty_mode(TRUE);
00094 
00095   /* Now register our core types */
00096   cashobjects_register();
00097 
00098   pkglibdir = gnc_path_get_pkglibdir ();
00099   for (lib = libs; lib->lib ; lib++)
00100   {
00101       if (qof_load_backend_library(pkglibdir, lib->lib))
00102       {
00103           engine_is_initialized = 1;
00104       }
00105       else
00106       {
00107           g_warning("failed to load %s from %s\n", lib->lib, pkglibdir);
00108           /* If this is a required library, stop now! */
00109           if (lib->required)
00110           {
00111               g_critical("required library %s not found.\n", lib->lib);
00112           }
00113       }
00114   }
00115   g_free (pkglibdir);
00116 
00117   /* call any engine hooks */
00118   for (cur = engine_init_hooks; cur; cur = cur->next)
00119   {
00120     hook = (gnc_engine_init_hook_t)cur->data;
00121 
00122     if (hook)
00123       (*hook)(argc, argv);
00124   }
00125 }

gboolean gnc_engine_is_initialized ( void )

check the engine is fully initialized

Definition at line 151 of file gnc-engine.c.

00152 {
00153     return (engine_is_initialized == 1) ? TRUE : FALSE;
00154 }

void gnc_engine_shutdown ( void )

Called to shutdown the engine, see also qof_close for use without Guile.

Definition at line 133 of file gnc-engine.c.

00134 {
00135   qof_log_shutdown();
00136   qof_close();
00137   engine_is_initialized = 0;
00138 }

void gnc_log_default ( void )

enable default log modules

Definition at line 161 of file gnc-engine.c.

00162 {
00163         qof_log_set_default(QOF_LOG_WARNING);
00164     qof_log_set_level(GNC_MOD_ROOT, QOF_LOG_WARNING);
00165         qof_log_set_level(GNC_MOD_TEST, QOF_LOG_DEBUG);
00166 }

unsigned int gnucash_major_version ( void )

GnuCash version number infomation.

Definition at line 50 of file gnc-engine.c.

00051 {
00052   return GNUCASH_MAJOR_VERSION;
00053 }

unsigned int gnucash_micro_version ( void )

GnuCash version number infomation.

Definition at line 62 of file gnc-engine.c.

00063 {
00064   return GNUCASH_MICRO_VERSION;
00065 }

unsigned int gnucash_minor_version ( void )

GnuCash version number infomation.

Definition at line 56 of file gnc-engine.c.

00057 {
00058   return GNUCASH_MINOR_VERSION;
00059 }

void xaccAccountBeginStagedTransactionTraversals ( const Account * account )

xaccAccountBeginStagedTransactionTraversals() resets the traversal marker for each transaction which is a parent of one of the splits in the account.

Definition at line 4379 of file Account.c.

04380 {
04381     AccountPrivate *priv;
04382 
04383     if (!account)
04384         return;
04385     priv = GET_PRIVATE(account);
04386     xaccSplitsBeginStagedTransactionTraversals(priv->splits);
04387 }

void xaccAccountClearReconcilePostpone ( Account * account )

DOCUMENT ME!

Definition at line 3982 of file Account.c.

03983 {
03984   if (!acc) return;
03985 
03986   xaccAccountBeginEdit (acc);
03987   kvp_frame_set_value (acc->inst.kvp_data, "reconcile-info/postpone", NULL);
03988   mark_account (acc);
03989   xaccAccountCommitEdit (acc);
03990 }

LotList* xaccAccountFindOpenLots	(	const Account *	acc,
		gboolean()(GNCLot lot, gpointer user_data)	match_func,
		gpointer	user_data,
		GCompareFunc	sort_func
	)

Find a list of open lots that match the match_func. Sort according to sort_func. If match_func is NULL, then all open lots are returned. If sort_func is NULL, then the returned list has no particular order. The caller must free to returned list.

Definition at line 3380 of file Account.c.

03384 {
03385   AccountPrivate *priv;
03386   GList *lot_list;
03387   GList *retval = NULL;
03388 
03389   g_return_val_if_fail(GNC_IS_ACCOUNT(acc), NULL);
03390 
03391   priv = GET_PRIVATE(acc);
03392   for (lot_list = priv->lots; lot_list; lot_list = lot_list->next) {
03393     GNCLot *lot = lot_list->data;


Files
file	gnc-engine.h
	All type declarations for the whole Gnucash engine.
Modules
	Business
	Account
	Cap Gains
	Commodities
	Lots: Core Function for AR/AP, Inventory, Stock Lots, Cap Gains
	Price Database
	Prices
	Accounting Periods
	Accounting Policy (FIFO/LIFO)
	Scheduled/Periodic/Recurring Transactions
	Data Validation
	Financial Transactions
	Transaction Logging
Lookup Accounts and Subaccounts by name or code
Account *	gnc_account_lookup_by_name (const Account parent, const char name)
Account *	gnc_account_lookup_by_full_name (const Account any_account, const gchar name)
Account *	gnc_account_lookup_by_code (const Account parent, const char code)
GNCAccountType conversion/checking
const char *	xaccAccountTypeEnumAsString (GNCAccountType type)
gboolean	xaccAccountStringToType (const char str, GNCAccountType type)
GNCAccountType	xaccAccountStringToEnum (const char *str)
const char *	xaccAccountGetTypeStr (GNCAccountType type)
GNCAccountType	xaccAccountGetTypeFromStr (const gchar *str)
guint32	xaccParentAccountTypesCompatibleWith (GNCAccountType type)
gboolean	xaccAccountTypesCompatible (GNCAccountType parent_type, GNCAccountType child_type)
guint32	xaccAccountTypesValid (void)
Account split/transaction list management
SplitList *	xaccAccountGetSplitList (const Account *account)
void	xaccAccountMoveAllSplits (Account accfrom, Account accto)
gint	xaccAccountForEachTransaction (const Account account, TransactionCallback proc, void data)
Transaction *	xaccAccountFindTransByDesc (const Account account, const char description)
Split *	xaccAccountFindSplitByDesc (const Account account, const char description)
#define	xaccAccountInsertSplit(acc, s) xaccSplitSetAccount((s), (acc))
Account lots
void	xaccAccountInsertLot (Account , GNCLot )
void	xaccAccountRemoveLot (Account , GNCLot )
LotList *	xaccAccountGetLotList (const Account *account)
gpointer	xaccAccountForEachLot (const Account acc, gpointer(proc)(GNCLot *lot, gpointer user_data), gpointer user_data)
LotList *	xaccAccountFindOpenLots (const Account acc, gboolean(match_func)(GNCLot *lot, gpointer user_data), gpointer user_data, GCompareFunc sort_func)
Account Reconciliation information getters/setters
gboolean	xaccAccountGetReconcileLastDate (const Account account, time_t last_date)
void	xaccAccountSetReconcileLastDate (Account *account, time_t last_date)
gboolean	xaccAccountGetReconcileLastInterval (const Account account, int months, int *days)
void	xaccAccountSetReconcileLastInterval (Account *account, int months, int days)
gboolean	xaccAccountGetReconcilePostponeDate (const Account account, time_t postpone_date)
void	xaccAccountSetReconcilePostponeDate (Account *account, time_t postpone_date)
gboolean	xaccAccountGetReconcilePostponeBalance (const Account account, gnc_numeric balance)
void	xaccAccountSetReconcilePostponeBalance (Account *account, gnc_numeric balance)
void	xaccAccountClearReconcilePostpone (Account *account)
Account Placeholder flag
gboolean	xaccAccountGetPlaceholder (const Account *account)
void	xaccAccountSetPlaceholder (Account *account, gboolean val)
GNCPlaceholderType	xaccAccountGetDescendantPlaceholder (const Account *account)
Account Hidden flag
gboolean	xaccAccountGetHidden (const Account *acc)
void	xaccAccountSetHidden (Account *acc, gboolean val)
gboolean	xaccAccountIsHidden (const Account *acc)
Account Tax related getters/setters
gboolean	xaccAccountGetTaxRelated (const Account *account)
void	xaccAccountSetTaxRelated (Account *account, gboolean tax_related)
const char *	xaccAccountGetTaxUSCode (const Account *account)
void	xaccAccountSetTaxUSCode (Account account, const char code)
const char *	xaccAccountGetTaxUSPayerNameSource (const Account *account)
void	xaccAccountSetTaxUSPayerNameSource (Account account, const char source)
Account marking
void	xaccAccountSetMark (Account *account, short mark)
short	xaccAccountGetMark (const Account *account)
void	xaccClearMark (Account *account, short val)
void	xaccClearMarkDown (Account *account, short val)
Staged Traversal
The following functions provide support for "staged traversals" over all of the transactions in an account or group. The idea is to be able to perform a sequence of traversals ("stages"), and perform an operation on each transaction exactly once for that stage. Only transactions whose current "stage" is less than the stage of the current traversal will be affected, and they will be "brought up" to the current stage when they are processed. For example, you could perform a stage 1 traversal of all the transactions in an account, and then perform a stage 1 traversal of the transactions in a second account. Presuming the traversal of the first account didn't abort prematurely, any transactions shared by both accounts would be ignored during the traversal of the second account since they had been processed while traversing the first account. However, if you had traversed the second account using a stage of 2, then all the transactions in the second account would have been processed. Traversal can be aborted by having the callback function return a non-zero value. The traversal is aborted immediately, and the non-zero value is returned. Note that an aborted traversal can be restarted; no information is lost due to an abort. The initial impetus for this particular approach came from generalizing a mark/sweep practice that was already being used in FileIO.c. Note that currently, there is a hard limit of 256 stages, which can be changed by enlarging "marker" in the transaction struct.
void	gnc_account_tree_begin_staged_transaction_traversals (Account *acc)
void	xaccSplitsBeginStagedTransactionTraversals (SplitList *splits)
void	xaccAccountBeginStagedTransactionTraversals (const Account *account)
gboolean	xaccTransactionTraverse (Transaction *trans, int stage)
gboolean	xaccSplitTransactionTraverse (Split *split, int stage)
int	xaccAccountStagedTransactionTraversal (const Account a, unsigned int stage, TransactionCallback thunk, void data)
int	gnc_account_tree_staged_transaction_traversal (const Account account, unsigned int stage, TransactionCallback thunk, void data)
int	xaccAccountTreeForEachTransaction (Account acc, TransactionCallback proc, void data)
Deprecated Routines.
void	DxaccAccountSetCurrency (Account account, gnc_commodity currency)
gnc_commodity *	DxaccAccountGetCurrency (const Account *account)
void	dxaccAccountSetQuoteTZ (Account account, const char tz)
const char *	dxaccAccountGetQuoteTZ (const Account *account)
Account parameter names
#define	ACCOUNT_KVP "kvp"
#define	ACCOUNT_NAME_ "name"
#define	ACCOUNT_CODE_ "code"
#define	ACCOUNT_DESCRIPTION_ "desc"
#define	ACCOUNT_NOTES_ "notes"
#define	ACCOUNT_BALANCE_ "balance"
#define	ACCOUNT_CLEARED_ "cleared"
#define	ACCOUNT_RECONCILED_ "reconciled"
#define	ACCOUNT_PRESENT_ "present"
#define	ACCOUNT_FUTURE_MINIMUM_ "future-minimum"
#define	ACCOUNT_TAX_RELATED "tax-related-p"
#define	ACCOUNT_TYPE_ "account-type"
#define	ACCOUNT_SCU "smallest-commodity-unit"
#define	ACCOUNT_NSCU "non-standard-scu"
#define	ACCOUNT_PARENT "parent-account"
QofLogModule identifiers

#define	GNC_MOD_ROOT "gnc"
#define	GNC_MOD_ENGINE "gnc.engine"
#define	GNC_MOD_ACCOUNT "gnc.account"
#define	GNC_MOD_SX "gnc.engine.sx"
#define	GNC_MOD_QUERY "gnc.query"
#define	GNC_MOD_SCRUB "gnc.scrub"
#define	GNC_MOD_LOT "gnc.lots"
#define	GNC_MOD_COMMODITY "gnc.commodity"
#define	GNC_MOD_BACKEND "gnc.backend"
#define	GNC_MOD_PRICE "gnc.pricedb"
#define	GNC_MOD_BUSINESS "gnc.business"
#define	GNC_MOD_IO "gnc.io"
#define	GNC_MOD_BOOK "gnc.book-period"
#define	GNC_MOD_GUI "gnc.gui"
#define	GNC_MOD_GUI_SX "gnc.gui.sx"
#define	GNC_MOD_GUILE "gnc.guile"
#define	GNC_MOD_LEDGER "gnc.ledger"
#define	GNC_MOD_REGISTER "gnc.register"
#define	GNC_MOD_HTML "gnc.html"
#define	GNC_MOD_PREFS "gnc.pref"
#define	GNC_MOD_IMPORT "gnc.import"
#define	GNC_MOD_DRUID "gnc.druids"
#define	GNC_MOD_TEST "gnc.tests"
#define	GNC_MOD_BUDGET "gnc.budget"
Defines
#define	ACCOUNT_MATCH_ALL_TYPE "account-match-all"
#define	GNC_ID_NONE QOF_ID_NONE
	IDENTIFIERS GUID Identifiers can be used to reference Accounts, Transactions, Splits and other objects. These Gnucash types are referred to as Gnucash entities. GUID Identifiers are globally-unique and permanent, i.e., once an entity has been assigned an identifier, it retains that same identifier for its lifetime. Identifiers are 'typed' with strings. The ids used in gnucash are defined below. An id with type GNC_ID_NONE does not refer to any entity, although that may change as new ids are created. An id with type GNC_ID_NULL does not refer to any entity, and will never refer to any entity. An identifier with any other type may refer to an actual entity, but that is not guaranteed. If an id does refer to an entity, the type of the entity will match the type of the identifier.
#define	GNC_ID_BOOK QOF_ID_BOOK
#define	GNC_ID_SESSION QOF_ID_SESSION
#define	GNC_ID_NULL QOF_ID_NULL
#define	GNC_ID_ACCOUNT "Account"
#define	GNC_ID_COMMODITY "Commodity"
#define	GNC_ID_COMMODITY_NAMESPACE "CommodityNamespace"
#define	GNC_ID_COMMODITY_TABLE "CommodityTable"
#define	GNC_ID_LOT "Lot"
#define	GNC_ID_PERIOD "Period"
#define	GNC_ID_PRICE "Price"
#define	GNC_ID_PRICEDB "PriceDB"
#define	GNC_ID_SPLIT "Split"
#define	GNC_ID_BUDGET "Budget"
#define	GNC_ID_SCHEDXACTION "SchedXaction"
#define	GNC_ID_SXES "SchedXactions"
#define	GNC_ID_SXTG "SXTGroup"
#define	GNC_ID_SXTT "SXTTrans"
#define	GNC_ID_TRANS "Trans"
Typedefs
typedef account_s	Account
	Account in Gnucash. This is the typename for an account. The actual structure is defined in the private header AccountP.h, but no one outside the engine should include that file. Instead, access that data only through the functions in Account.h .
typedef split_s	Split
	Split in Gnucash. A "split" is more commonly refered to as a "entry" in a "transaction". Each split belongs to one Account and one Transaction. The split is one out of several parts a Transaction is divided into.
typedef transaction_s	Transaction
	Transaction in Gnucash. A Transaction is a piece of business done; the transfer of money from one account to one or more other accounts. Each Transaction is divided into one or more Splits (usually two).
typedef gnc_commodity_s	gnc_commodity
	An article that is bought and sold. A Commodity is the most general term of what an account keeps track of. Usually this is a monetary currency, but it can also be a stock share or even a precious metal. Every account keeps track of exactly one gnc_commodity.
typedef gnc_commodity_namespace_s	gnc_commodity_namespace
	A gnc_commodity_namespace is an collection of commodities.
typedef gnc_commodity_table_s	gnc_commodity_table
	A gnc_commodity_table is a database of commodity info.
typedef gnc_lot_struct	GNCLot
	Identifies that something sold at one time was bought at another. A GNCLot provides a way of tracking physical items as they are bought and sold in different transactions. By identifying the individual, underlying physical objects, it provides the needed framework for implementing depreciation, capital gains, inventory control and invoices.
typedef gnc_price_s	GNCPrice
	Price of commodity on a given date. A GNCPrice encapsulates price information: the cost of a commodity expressed as a currency, on a given date. It also holds info about the provenance of the price: where it came from, its general validity.
typedef gnc_quote_source_s	gnc_quote_source
typedef GList	AccountList
typedef GList	LotList
typedef GList	SplitList
typedef GList	TransList
typedef GList	AccountGUIDList
typedef GList	BookGUIDList
typedef gint(*)	SplitCallback (Split *s, gpointer data)
typedef gint(*)	TransactionCallback (Transaction t, void data)
typedef void(*)	gnc_engine_init_hook_t (int, char **)
Enumerations
enum	GNCPlaceholderType { PLACEHOLDER_NONE, PLACEHOLDER_THIS, PLACEHOLDER_CHILD }
Functions
unsigned int	gnucash_major_version (void)
unsigned int	gnucash_minor_version (void)
unsigned int	gnucash_micro_version (void)
void	gnc_engine_init (int argc, char **argv)
void	gnc_engine_shutdown (void)
gboolean	gnc_engine_is_initialized (void)
void	gnc_log_default (void)
void	gnc_engine_add_init_hook (gnc_engine_init_hook_t hook)