Transaction.h File Reference

API for Transactions and Splits (journal entries) More...

#include <time.h>
#include "gnc-commodity.h"
#include "gnc-engine.h"
#include "gnc-pricedb.h"
#include "Split.h"

Go to the source code of this file.

Macros
#define	GNC_TYPE_TRANSACTION   (gnc_transaction_get_type ())
#define	GNC_TRANSACTION(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_TRANSACTION, Transaction))
#define	GNC_TRANSACTION_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_TRANSACTION, TransactionClass))
#define	GNC_IS_TRANSACTION(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_TRANSACTION))
#define	GNC_IS_TRANSACTION_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_TRANSACTION))
#define	GNC_TRANSACTION_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_TRANSACTION, TransactionClass))
#define	GNC_IS_TRANS(obj)   GNC_IS_TRANSACTION(obj)
#define	GNC_TRANS(obj)   GNC_TRANSACTION(obj)
#define	RECONCILED_MATCH_TYPE   "reconciled-match"
#define	xaccTransGetBook(X)   qof_instance_get_book (QOF_INSTANCE(X))
#define	xaccTransGetGUID(X)   qof_entity_get_guid(QOF_INSTANCE(X))
Transaction Type field values
#define	TXN_TYPE_UNCACHED   '?' /** Transaction type not yet cached */
#define	TXN_TYPE_NONE   '\0'
	No transaction type.
#define	TXN_TYPE_INVOICE   'I'
	Transaction is an invoice.
#define	TXN_TYPE_PAYMENT   'P'
	Transaction is a payment.
#define	TXN_TYPE_LINK   'L'
	Transaction is a link between (invoice and payment) lots.
Transaction Parameter names
#define	TRANS_KVP   "kvp"
#define	TRANS_NUM   "num"
#define	TRANS_DESCRIPTION   "desc"
#define	TRANS_DATE_ENTERED   "date-entered"
#define	TRANS_DATE_POSTED   "date-posted"
#define	TRANS_DATE_DUE   "date-due"
#define	TRANS_IMBALANCE   "trans-imbalance"
#define	TRANS_IS_BALANCED   "trans-balanced?"
#define	TRANS_IS_CLOSING   "trans-is-closing?"
#define	TRANS_NOTES   "notes"
#define	TRANS_DOCLINK   "doclink"
#define	TRANS_TYPE   "type"
#define	TRANS_VOID_STATUS   "void-p"
#define	TRANS_VOID_REASON   "void-reason"
#define	TRANS_VOID_TIME   "void-time"
#define	TRANS_SPLITLIST   "split-list" /* for guid_match_all */

Functions
GType	gnc_transaction_get_type (void)
void	xaccTransRecordPrice (Transaction *trans, PriceSource source)
	The xaccTransRecordPrice() method iterates through the splits and and record the non-currency equivalent prices in the price database. More...
Transaction date setters/getters
void	xaccTransSetDate (Transaction *trans, int day, int mon, int year)
	The xaccTransSetDate() method does the same thing as xaccTransSetDate[Posted]Secs(), but takes a convenient day-month-year format. More...
void	xaccTransSetDatePostedGDate (Transaction *trans, GDate date)
	This method modifies posted date of the transaction, specified by a GDate. More...
void	xaccTransSetDatePostedSecs (Transaction *trans, time64 time)
	The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)). More...
void	xaccTransSetDatePostedSecsNormalized (Transaction *trans, time64 time)
	This function sets the posted date of the transaction, specified by a time64 (see ctime(3)). More...
void	xaccTransSetDateEnteredSecs (Transaction *trans, time64 time)
	Modify the date of when the transaction was entered. More...
void	xaccTransSetDateDue (Transaction *trans, time64 time)
	Dates and txn-type for A/R and A/P "invoice" postings.
time64	xaccTransGetDate (const Transaction *trans)
	Retrieve the posted date of the transaction. More...
time64	xaccTransRetDatePosted (const Transaction *trans)
	Retrieve the posted date of the transaction. More...
GDate	xaccTransGetDatePostedGDate (const Transaction *trans)
	Retrieve the posted date of the transaction. More...
time64	xaccTransGetDateEntered (const Transaction *trans)
	Retrieve the date of when the transaction was entered. More...
time64	xaccTransRetDateEntered (const Transaction *trans)
	Retrieve the date of when the transaction was entered. More...
time64	xaccTransRetDateDue (const Transaction *trans)
	Dates and txn-type for A/R and A/P "invoice" postings.
Transaction voiding
void	xaccTransVoid (Transaction *transaction, const char *reason)
	xaccTransVoid voids a transaction. More...
void	xaccTransUnvoid (Transaction *transaction)
	xaccTransUnvoid restores a voided transaction to its original state. More...
Transaction *	xaccTransReverse (Transaction *transaction)
	xaccTransReverse creates a Transaction that reverses the given transaction by inverting all the numerical values in the given transaction. More...
Transaction *	xaccTransGetReversedBy (const Transaction *trans)
	Returns the transaction that reversed the given transaction. More...
gboolean	xaccTransGetVoidStatus (const Transaction *transaction)
	Retrieve information on whether or not a transaction has been voided. More...
const char *	xaccTransGetVoidReason (const Transaction *transaction)
	Returns the user supplied textual reason why a transaction was voided. More...
time64	xaccTransGetVoidTime (const Transaction *tr)
	Returns the time that a transaction was voided. More...

Transaction creation and editing
#define	xaccTransLookupDirect(g, b)   xaccTransLookup(&(g),b)
Transaction *	xaccMallocTransaction (QofBook *book)
	The xaccMallocTransaction() will malloc memory and initialize it. More...
void	xaccTransDestroy (Transaction *trans)
	Destroys a transaction. More...
Transaction *	xaccTransClone (const Transaction *t)
	The xaccTransClone() method will create a complete copy of an existing transaction.
Transaction *	xaccTransCloneNoKvp (const Transaction *t)
	The xaccTransCloneNoKvp() method will create a complete copy of an existing transaction except that the KVP slots will be empty.
gboolean	xaccTransEqual (const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits, gboolean check_balances, gboolean assume_ordered)
	Equality. More...
void	xaccTransBeginEdit (Transaction *trans)
	The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of its component splits. More...
void	xaccTransCommitEdit (Transaction *trans)
	The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are complete and should be made permanent. More...
void	xaccTransRollbackEdit (Transaction *trans)
	The xaccTransRollbackEdit() routine rejects all edits made, and sets the transaction back to where it was before the editing started. More...
gboolean	xaccTransIsOpen (const Transaction *trans)
	The xaccTransIsOpen() method returns TRUE if the transaction is open for editing. More...
Transaction *	xaccTransLookup (const GncGUID *guid, QofBook *book)
	The xaccTransLookup() subroutine will return the transaction associated with the given id, or NULL if there is no such transaction. More...
Transaction *	xaccTransCopyToClipBoard (const Transaction *from_trans)
	Copy a transaction to the 'clipboard' transaction using dupe_transaction. More...
void	xaccTransCopyOnto (const Transaction *from_trans, Transaction *to_trans)
	Copy a transaction to another using the function below without changing any account information.
void	xaccTransCopyFromClipBoard (const Transaction *from_trans, Transaction *to_trans, const Account *from_acc, Account *to_acc, gboolean no_date)
	This function explicitly must robustly handle some unusual input. More...
Split *	xaccTransFindSplitByAccount (const Transaction *trans, const Account *acc)
void	xaccTransScrubGains (Transaction *trans, Account *gain_acc)
	The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction, with the end-goal of setting up a consistent set of gains/losses for all the splits in the transaction. More...
guint	gnc_book_count_transactions (QofBook *book)

Transaction general getters/setters
#define	xaccTransAppendSplit(t, s)   xaccSplitSetParent((s), (t))
	Add a split to the transaction. More...
gboolean	xaccTransUseTradingAccounts (const Transaction *trans)
	Determine whether this transaction should use commodity trading accounts.
void	xaccTransSortSplits (Transaction *trans)
	Sorts the splits in a transaction, putting the debits first, followed by the credits.
void	xaccTransSetTxnType (Transaction *trans, char type)
	Set the Transaction Type: note the type will be saved into the Transaction kvp property as a backward compatibility measure, for previous GnuCash versions whose xaccTransGetTxnType reads from the kvp slots. More...
char	xaccTransGetTxnType (Transaction *trans)
	Returns the Transaction Type: note this type will be derived from the transaction splits, returning TXN_TYPE_NONE, TXN_TYPE_INVOICE, TXN_TYPE_LINK, or TXN_TYPE_PAYMENT according to heuristics. More...
void	xaccTransSetNum (Transaction *trans, const char *num)
	Sets the transaction Number (or ID) field; rather than use this function directly, see 'gnc_set_num_action' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
void	xaccTransSetDescription (Transaction *trans, const char *desc)
	Sets the transaction Description.
void	xaccTransSetDocLink (Transaction *trans, const char *doclink)
	Sets the transaction Document Link.
void	xaccTransSetNotes (Transaction *trans, const char *notes)
	Sets the transaction Notes. More...
const char *	xaccTransGetNum (const Transaction *trans)
	Gets the transaction Number (or ID) field; rather than use this function directly, see 'gnc_get_num_action' and 'gnc_get_action_num' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
const char *	xaccTransGetDescription (const Transaction *trans)
	Gets the transaction Description.
const char *	xaccTransGetDocLink (const Transaction *trans)
	Gets the transaction Document Link.
const char *	xaccTransGetNotes (const Transaction *trans)
	Gets the transaction Notes. More...
void	xaccTransSetIsClosingTxn (Transaction *trans, gboolean is_closing)
	Sets whether or not this transaction is a "closing transaction".
gboolean	xaccTransGetIsClosingTxn (const Transaction *trans)
	Returns whether this transaction is a "closing transaction".
void	xaccTransClearSplits (Transaction *trans)
	Remove all splits from the transaction. More...
Split *	xaccTransGetSplit (const Transaction *trans, int i)
	Return a pointer to the indexed split in this transaction's split list. More...
int	xaccTransGetSplitIndex (const Transaction *trans, const Split *split)
	Inverse of xaccTransGetSplit()
SplitList *	xaccTransGetSplitList (const Transaction *trans)
	The xaccTransGetSplitList() method returns a GList of the splits in a transaction. More...
SplitList *	xaccTransGetPaymentAcctSplitList (const Transaction *trans)
	The xaccTransGetPaymentAcctSplitList() method returns a GList of the splits in a transaction that belong to an account which is considered a valid account for business payments. More...
SplitList *	xaccTransGetAPARAcctSplitList (const Transaction *trans, gboolean strict)
	The xaccTransGetAPARSplitList() method returns a GList of the splits in a transaction that belong to an AR or AP account. More...
gboolean	xaccTransStillHasSplit (const Transaction *trans, const Split *s)
Split *	xaccTransGetFirstPaymentAcctSplit (const Transaction *trans)
	The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an account which is considered a valid account for business payments. More...
Split *	xaccTransGetFirstAPARAcctSplit (const Transaction *trans, gboolean strict)
	The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an AR or AP account. More...
void	xaccTransSetReadOnly (Transaction *trans, const char *reason)
	Set the transaction to be ReadOnly by setting a non-NULL value as "reason". More...
void	xaccTransClearReadOnly (Transaction *trans)
const char *	xaccTransGetReadOnly (Transaction *trans)
	Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text. More...
gboolean	xaccTransIsReadonlyByPostedDate (const Transaction *trans)
	Returns TRUE if this Transaction is read-only because its posted-date is older than the "auto-readonly" threshold of this book. More...
int	xaccTransCountSplits (const Transaction *trans)
	Returns the number of splits in this transaction. More...
gboolean	xaccTransHasReconciledSplits (const Transaction *trans)
	FIXME: document me.
gboolean	xaccTransHasReconciledSplitsByAccount (const Transaction *trans, const Account *account)
	FIXME: document me.
gboolean	xaccTransHasSplitsInState (const Transaction *trans, const char state)
	FIXME: document me.
gboolean	xaccTransHasSplitsInStateByAccount (const Transaction *trans, const char state, const Account *account)
	FIXME: document me.
gnc_commodity *	xaccTransGetCurrency (const Transaction *trans)
	Returns the valuation commodity of this transaction. More...
void	xaccTransSetCurrency (Transaction *trans, gnc_commodity *curr)
	Set the commodity of this transaction. More...
gnc_numeric	xaccTransGetImbalanceValue (const Transaction *trans)
	The xaccTransGetImbalanceValue() method returns the total value of the transaction. More...
MonetaryList *	xaccTransGetImbalance (const Transaction *trans)
	The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency for which the balance is not zero. More...
gboolean	xaccTransIsBalanced (const Transaction *trans)
	Returns true if the transaction is balanced according to the rules currently in effect. More...
gnc_numeric	xaccTransGetAccountValue (const Transaction *trans, const Account *account)
	The xaccTransGetAccountValue() method returns the total value applied to a particular account. More...
gnc_numeric	xaccTransGetAccountAmount (const Transaction *trans, const Account *account)
	Same as xaccTransGetAccountValue, but uses the Account's commodity. More...
gnc_numeric	xaccTransGetAccountConvRate (const Transaction *txn, const Account *acc)
gnc_numeric	xaccTransGetAccountBalance (const Transaction *trans, const Account *account)
	Get the account balance for the specified account after the last split in the specified transaction. More...
int	xaccTransOrder (const Transaction *ta, const Transaction *tb)
	The xaccTransOrder(ta,tb) method is useful for sorting. More...
int	xaccTransOrder_num_action (const Transaction *ta, const char *actna, const Transaction *tb, const char *actnb)
	The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting. More...

Detailed Description

API for Transactions and Splits (journal entries)

Author

Copyright (C) 1997 Robin D. Clark

Copyright (C) 1997-2001 Linas Vepstas linas.nosp@m.@lin.nosp@m.as.or.nosp@m.g

Definition in file Transaction.h.