Owner

Files
file	gncOwner.h
	Business Interface: Object OWNERs.

Data Structures
struct	GncOwner
struct	GncOwner

Macros
#define	GNC_ID_OWNER   "gncOwner"
#define	OWNER_TYPE   "type"
#define	OWNER_TYPE_STRING   "type-string"
	Allows the type to be handled externally. More...
#define	OWNER_CUSTOMER   "customer"
#define	OWNER_JOB   "job"
#define	OWNER_VENDOR   "vendor"
#define	OWNER_EMPLOYEE   "employee"
#define	OWNER_PARENT   "parent"
#define	OWNER_PARENTG   "parent-guid"
#define	OWNER_NAME   "name"
#define	OWNER_FROM_LOT   "owner-from-lot"

Enumerations
enum	GncOwnerType {   GNC_OWNER_NONE, GNC_OWNER_UNDEFINED, GNC_OWNER_CUSTOMER, GNC_OWNER_JOB,   GNC_OWNER_VENDOR, GNC_OWNER_EMPLOYEE }

Functions
void	gncOwnerCopy (const GncOwner *src, GncOwner *dest)
const GncGUID *	gncOwnerGetGUID (const GncOwner *owner)
	Get the GncGUID of the immediate owner.
GncGUID	gncOwnerRetGUID (GncOwner *owner)
const GncOwner *	gncOwnerGetEndOwner (const GncOwner *owner)
	Get the "parent" Owner or GncGUID thereof. More...
const GncGUID *	gncOwnerGetEndGUID (const GncOwner *owner)
void	gncOwnerAttachToLot (const GncOwner *owner, GNCLot *lot)
	Attach an owner to a lot.
gboolean	gncOwnerLotMatchOwnerFunc (GNCLot *lot, gpointer user_data)
	Helper function used to filter a list of lots by owner.
gint	gncOwnerLotsSortFunc (GNCLot *lotA, GNCLot *lotB)
	Helper function used to sort lots by date. More...
gboolean	gncOwnerGetOwnerFromLot (GNCLot *lot, GncOwner *owner)
	Get the owner from the lot. More...
gboolean	gncOwnerGetOwnerFromTxn (Transaction *txn, GncOwner *owner)
	Convenience function to get the owner from a transaction. More...
gboolean	gncOwnerGetOwnerFromTypeGuid (QofBook *book, GncOwner *owner, QofIdType type, GncGUID *guid)
GNCLot *	gncOwnerCreatePaymentLotSecs (const GncOwner *owner, Transaction **preset_txn, Account *posted_acc, Account *xfer_acc, gnc_numeric amount, gnc_numeric exch, time64 date, const char *memo, const char *num)
	Create a lot for a payment to the owner using the other parameters passed in. More...
void	gncOwnerAutoApplyPaymentsWithLots (const GncOwner *owner, GList *lots)
	Given a list of lots, try to balance as many of them as possible by creating balancing transactions between them. More...
void	gncOwnerApplyPaymentSecs (const GncOwner *owner, Transaction **preset_txn, GList *lots, Account *posted_acc, Account *xfer_acc, gnc_numeric amount, gnc_numeric exch, time64 date, const char *memo, const char *num, gboolean auto_pay)
	A convenience function to apply a payment to the owner. More...
Split *	gncOwnerFindOffsettingSplit (GNCLot *lot, gnc_numeric target_amount)
	Helper function to find a split in lot that best offsets target_amount Obviously it should be of opposite sign. More...
gboolean	gncOwnerReduceSplitTo (Split *split, gnc_numeric target_amount)
	Helper function to reduce the amount of a split to target_amount. More...
void	gncOwnerSetLotLinkMemo (Transaction *ll_txn)
	To help a user understand what a lot link transaction does, we set the memo to name all documents involved in the link. More...
GList *	gncOwnerGetAccountTypesList (const GncOwner *owner)
	Returns a GList of account-types based on the owner type.
GList *	gncOwnerGetCommoditiesList (const GncOwner *owner)
	Returns a GList of currencies associated with the owner.
gnc_numeric	gncOwnerGetBalanceInCurrency (const GncOwner *owner, const gnc_commodity *report_currency)
	Given an owner, extract the open balance from the owner and then convert it to the desired currency.
GncOwner *	gncOwnerNew (void)
	These two functions are mainly for the convenience of scheme code. More...
void	gncOwnerFree (GncOwner *owner)
void	gncOwnerBeginEdit (GncOwner *owner)
	These are convenience wrappers around gnc{Vendor,Customer,Job,Employee}* functions. More...
void	gncOwnerCommitEdit (GncOwner *owner)
void	gncOwnerDestroy (GncOwner *owner)

QOF handling
Whilst GncOwner is not a formal QOF object, these functions are still expected to be useful in making GncOwner transparent to QOF as they can be used by objects like GncInvoice.
QofIdTypeConst	qofOwnerGetType (const GncOwner *owner)
	return the type for the collection. More...
const char *	gncOwnerGetTypeString (const GncOwner *owner)
	return the type for the owner as an untranslated string. More...
QofInstance *	qofOwnerGetOwner (const GncOwner *owner)
	return the owner itself as an entity. More...
void	qofOwnerSetEntity (GncOwner *owner, QofInstance *ent)
	set the owner from the entity. More...
gboolean	GNC_IS_OWNER (QofInstance *ent)
	Check if entity is an owner kind. More...
QofIdTypeConst	gncOwnerTypeToQofIdType (GncOwnerType t)
	Returns the QofIdType of the given GncOwnerType, or NULL if no suitable one exists. More...
gboolean	gncOwnerRegister (void)

Setup routines
void	gncOwnerInitUndefined (GncOwner *owner, gpointer obj)
void	gncOwnerInitCustomer (GncOwner *owner, GncCustomer *customer)
void	gncOwnerInitJob (GncOwner *owner, GncJob *job)
void	gncOwnerInitVendor (GncOwner *owner, GncVendor *vendor)
void	gncOwnerInitEmployee (GncOwner *owner, GncEmployee *employee)

Get routines.
GncOwnerType	gncOwnerGetType (const GncOwner *owner)
	Returns the GncOwnerType of this owner. More...
gboolean	gncOwnerIsValid (const GncOwner *owner)
	Returns TRUE if the given owner is one of the valid objects. More...
gpointer	gncOwnerGetUndefined (const GncOwner *owner)
	If the given owner is of type GNC_OWNER_UNDEFINED, returns the undefined pointer, which is usually NULL. More...
GncCustomer *	gncOwnerGetCustomer (const GncOwner *owner)
	If the given owner is of type GNC_OWNER_CUSTOMER, returns the pointer to the customer object. More...
GncJob *	gncOwnerGetJob (const GncOwner *owner)
	If the given owner is of type GNC_OWNER_JOB, returns the pointer to the job object. More...
GncVendor *	gncOwnerGetVendor (const GncOwner *owner)
	If the given owner is of type GNC_OWNER_VENDOR, returns the pointer to the vendor object. More...
GncEmployee *	gncOwnerGetEmployee (const GncOwner *owner)
	If the given owner is of type GNC_OWNER_EMPLOYEE, returns the pointer to the employee object. More...
const char *	gncOwnerGetID (const GncOwner *owner)
const char *	gncOwnerGetName (const GncOwner *owner)
GncAddress *	gncOwnerGetAddr (const GncOwner *owner)
gboolean	gncOwnerGetActive (const GncOwner *owner)
gnc_commodity *	gncOwnerGetCurrency (const GncOwner *owner)

Set routines.
void	gncOwnerSetActive (const GncOwner *owner, gboolean active)

Comparison routines.
gboolean	gncOwnerEqual (const GncOwner *a, const GncOwner *b)
	Assess equality by checking. More...
int	gncOwnerGCompareFunc (const GncOwner *a, const GncOwner *b)
	Same as gncOwnerEqual, but returns 0 if equal to be used as a GList custom compare function.
int	gncOwnerCompare (const GncOwner *a, const GncOwner *b)
	Sort on name.

Detailed Description

Macro Definition Documentation

OWNER_TYPE_STRING

#define OWNER_TYPE_STRING   "type-string"

Allows the type to be handled externally.

Definition at line 325 of file gncOwner.h.

Function Documentation

GNC_IS_OWNER()

gboolean GNC_IS_OWNER

(

QofInstance *

ent

)

Check if entity is an owner kind.

This function conveniently imitates the various GNC_IS_ checks on the other gnucash objects even though an owner is not really a true object.

Definition at line 352 of file gncOwner.c.

{
    if (!ent)
        return FALSE;

    return (GNC_IS_VENDOR(ent) ||
            GNC_IS_CUSTOMER(ent) ||
            GNC_IS_EMPLOYEE(ent) ||
            GNC_IS_JOB(ent));
}

gncOwnerApplyPaymentSecs()

void gncOwnerApplyPaymentSecs	(	const GncOwner *	owner,
		Transaction **	preset_txn,
		GList *	lots,
		Account *	posted_acc,
		Account *	xfer_acc,
		gnc_numeric	amount,
		gnc_numeric	exch,
		time64	date,
		const char *	memo,
		const char *	num,
		gboolean	auto_pay
	)

A convenience function to apply a payment to the owner.

It creates a lot for a payment, optionally based on an existing transaction and then tries to balance it with the list of document/payment lots passed in. If not lots were given, all open lots for the owner are considered.

This code is actually a convenience wrapper around gncOwnerCreatePaymentLot and gncOwnerAutoApplyPaymentsWithLots. See their descriptions for more details on what happens exactly.

Definition at line 1405 of file gncOwner.c.

{
    GNCLot *payment_lot = NULL;
    GList *selected_lots = NULL;

    /* Verify our arguments */
    if (!owner || !posted_acc
               || (!xfer_acc && !gnc_numeric_zero_p (amount)) ) return;
    g_return_if_fail (owner->owner.undefined);

    if (lots)
        selected_lots = lots;
    else if (auto_pay)
        selected_lots = xaccAccountFindOpenLots (posted_acc, gncOwnerLotMatchOwnerFunc,
                        (gpointer)owner, NULL);

    /* If there's a real amount to transfer create a lot for this payment */
    if (!gnc_numeric_zero_p (amount))
        payment_lot = gncOwnerCreatePaymentLotSecs (owner, preset_txn,
                                                    posted_acc, xfer_acc,
                                                    amount, exch, date, memo,
                                                    num);

    /* And link the selected lots and the payment lot together as well
     * as possible.  If the payment was bigger than the selected
     * documents/overpayments, only part of the payment will be
     * used. Similarly if more documents were selected than the
     * payment value set, not all documents will be marked as paid. */
    if (payment_lot)
        selected_lots = g_list_prepend (selected_lots, payment_lot);

    gncOwnerAutoApplyPaymentsWithLots (owner, selected_lots);
    g_list_free (selected_lots);
}

gncOwnerAutoApplyPaymentsWithLots()

void gncOwnerAutoApplyPaymentsWithLots	(	const GncOwner *	owner,
		GList *	lots
	)

Given a list of lots, try to balance as many of them as possible by creating balancing transactions between them.

This can be used to automatically link invoices to payments (to "mark" invoices as paid) or to credit notes or the other way around.

The function starts with the first lot in the list and tries to create balancing transactions to the remainder of the lots in the list. If it reaches the end of the list, it will find the next still open lot in the list and tries to balance it with all lots that follow it (the ones that precede it are either already closed or not suitable or they would have been processed in a previous iteration).

By intelligently sorting the list of lots, you can play with the order of precedence in which the lots should be processed. For example, by sorting the oldest invoice lots first, the code will attempt to balance these first.

Some restrictions:

• the algorithm is lazy: it will create the smallest balancing transaction(s) possible, not the largest ones. Since the process is iterative, you will have balanced the maximum amount possible in the end, but it may be done in several transactions instead of only one big one.
• the balancing transactions only work within one account. If a balancing lot is from another account than the lot currently being balanced, it will be skipped during balance evaluation. However if there is a mix of lots from two different accounts, the algorithm will still attempt to match all lots per account.
• the calling function is responsible for the memory management of the lots list. If it created the list, it should properly free it as well.

Definition at line 1256 of file gncOwner.c.

{
    GList *left_iter;

    /* General note: in the code below the term "payment" can
     * both mean a true payment or a document of
     * the opposite sign (invoice vs credit note) relative to
     * the lot being processed. In general this function will
     * perform a balancing action on a set of lots, so you
     * will also find frequent references to balancing instead. */

    /* Payments can only be applied when at least an owner
     * and a list of lots to use are given */
    if (!owner) return;
    if (!lots) return;

    for (left_iter = lots; left_iter; left_iter = left_iter->next)
    {
        GNCLot *left_lot = left_iter->data;
        gnc_numeric left_lot_bal;
        gboolean left_lot_has_doc;
        gboolean left_modified = FALSE;
        Account *acct;
        GList *right_iter;

        /* Only attempt to apply payments to open lots.
         * Note that due to the iterative nature of this function lots
         * in the list may become empty/closed before they are evaluated as
         * base lot, so we should check this for each lot. */
        if (!left_lot)
            continue;
        if (gnc_lot_count_splits (left_lot) == 0)
        {
            gnc_lot_destroy (left_lot);
            left_iter->data = NULL;
            continue;
        }
        if (gnc_lot_is_closed (left_lot))
            continue;

        acct = gnc_lot_get_account (left_lot);
        xaccAccountBeginEdit (acct);

        left_lot_bal = gnc_lot_get_balance (left_lot);
        left_lot_has_doc = (gncInvoiceGetInvoiceFromLot (left_lot) != NULL);

        /* Attempt to offset left_lot with any of the remaining lots. To do so
         * iterate over the remaining lots adding lot links or moving payments
         * around.
         */
        for (right_iter = left_iter->next; right_iter; right_iter = right_iter->next)
        {
            GNCLot *right_lot = right_iter->data;
            gnc_numeric right_lot_bal;
            gboolean right_lot_has_doc;

            /* Only attempt to use open lots to balance the base lot.
             * Note that due to the iterative nature of this function lots
             * in the list may become empty/closed before they are evaluated as
             * base lot, so we should check this for each lot. */
            if (!right_lot)
                continue;
            if (gnc_lot_count_splits (right_lot) == 0)
            {
                gnc_lot_destroy (right_lot);
                right_iter->data = NULL;
                continue;
            }
            if (gnc_lot_is_closed (right_lot))
                continue;

            /* Balancing transactions for invoice/payments can only happen
             * in the same account. */
            if (acct != gnc_lot_get_account (right_lot))
                continue;


            /* Only attempt to balance if the base lot and balancing lot are
             * of the opposite sign. (Otherwise we would increase the balance
             * of the lot - Duh */
            right_lot_bal = gnc_lot_get_balance (right_lot);
            if (gnc_numeric_positive_p (left_lot_bal) == gnc_numeric_positive_p (right_lot_bal))
                continue;

            /* Ok we found two lots than can (partly) offset each other.
             * Depending on the lot types, a different action is needed to accomplish this.
             * 1. Both lots are document lots (invoices/credit notes)
             *    -> Create a lot linking transaction between the lots
             * 2. Both lots are payment lots (lots without a document attached)
             *    -> Use part of the bigger lot to the close the smaller lot
             * 3. One document lot with one payment lot
             *    -> Use (part of) the payment to offset (part of) the document lot,
             *       Which one will be closed depends on which is the bigger one
             */
            right_lot_has_doc = (gncInvoiceGetInvoiceFromLot (right_lot) != NULL);
            if (left_lot_has_doc && right_lot_has_doc)
                gncOwnerCreateLotLink (left_lot, right_lot, owner);
            else if (!left_lot_has_doc && !right_lot_has_doc)
            {
                gint cmp = gnc_numeric_compare (gnc_numeric_abs (left_lot_bal),
                                                gnc_numeric_abs (right_lot_bal));
                if (cmp >= 0)
                    gncOwnerOffsetLots (left_lot, right_lot, owner);
                else
                    gncOwnerOffsetLots (right_lot, left_lot, owner);
            }
            else
            {
                GNCLot *doc_lot = left_lot_has_doc ? left_lot : right_lot;
                GNCLot *pay_lot = left_lot_has_doc ? right_lot : left_lot;
                // Ok, let's try to move a payment from pay_lot to doc_lot
                gncOwnerOffsetLots (pay_lot, doc_lot, owner);
            }

            /* If we get here, then right_lot was modified
             * If the lot has a document, send an event for send an event for it as well
             * so it gets potentially updated as paid */

            {
                GncInvoice *this_invoice = gncInvoiceGetInvoiceFromLot(right_lot);
                if (this_invoice)
                    qof_event_gen (QOF_INSTANCE(this_invoice), QOF_EVENT_MODIFY, NULL);
            }
            left_modified = TRUE;
        }

        /* If left_lot was modified and the lot has a document,
         * send an event for send an event for it as well
         * so it gets potentially updated as paid */
        if (left_modified)
        {
            GncInvoice *this_invoice = gncInvoiceGetInvoiceFromLot(left_lot);
            if (this_invoice)
                qof_event_gen (QOF_INSTANCE(this_invoice), QOF_EVENT_MODIFY, NULL);
        }
        xaccAccountCommitEdit (acct);

    }
}

gncOwnerBeginEdit()

void gncOwnerBeginEdit

(

GncOwner *

owner

)

These are convenience wrappers around gnc{Vendor,Customer,Job,Employee}* functions.

This allows you to begin edit, destroy commit edit an owner without knowing its type.

Definition at line 72 of file gncOwner.c.

{
    if (!owner) return;
    switch (owner->type)
    {
    case GNC_OWNER_NONE :
    case GNC_OWNER_UNDEFINED :
        break;
    case GNC_OWNER_CUSTOMER :
    {
        gncCustomerBeginEdit(owner->owner.customer);
        break;
    }
    case GNC_OWNER_JOB :
    {
        gncJobBeginEdit(owner->owner.job);
        break;
    }
    case GNC_OWNER_VENDOR :
    {
        gncVendorBeginEdit(owner->owner.vendor);
        break;
    }
    case GNC_OWNER_EMPLOYEE :
    {
        gncEmployeeBeginEdit(owner->owner.employee);
        break;
    }
    }
}

gncOwnerCreatePaymentLotSecs()

GNCLot* gncOwnerCreatePaymentLotSecs	(	const GncOwner *	owner,
		Transaction **	preset_txn,
		Account *	posted_acc,
		Account *	xfer_acc,
		gnc_numeric	amount,
		gnc_numeric	exch,
		time64	date,
		const char *	memo,
		const char *	num
	)

Create a lot for a payment to the owner using the other parameters passed in.

If a transaction is set, this transaction will be reused if possible (meaning, if the transaction currency matches the owner's currency and if the transaction has (at least?) one split in the transfer account).

Definition at line 750 of file gncOwner.c.

{
    QofBook *book;
    Split *split;
    const char *name;
    gnc_commodity *post_comm, *xfer_comm;
    Split *xfer_split = NULL;
    Transaction *txn = NULL;
    GNCLot *payment_lot;
    gnc_numeric xfer_amount = gnc_numeric_zero();
    gnc_numeric txn_value = gnc_numeric_zero();

    /* Verify our arguments */
    if (!owner || !posted_acc || !xfer_acc) return NULL;
    g_return_val_if_fail (owner->owner.undefined != NULL, NULL);

    /* Compute the ancillary data */
    book = gnc_account_get_book (posted_acc);
    name = gncOwnerGetName (gncOwnerGetEndOwner ((GncOwner*)owner));
    post_comm = xaccAccountGetCommodity (posted_acc);
    xfer_comm = xaccAccountGetCommodity (xfer_acc);

//    reverse = use_reversed_payment_amounts(owner);

    if (preset_txn && *preset_txn)
        txn = *preset_txn;

    if (txn)
    {
        int i = 0;

        /* Pre-existing transaction was specified. We completely clear it,
         * except for a pre-existing transfer split. We're very conservative
         * in preserving that one as it may have been reconciled already. */
        xfer_split = xaccTransFindSplitByAccount(txn, xfer_acc);
        xaccTransBeginEdit (txn);
        while (i < xaccTransCountSplits(txn))
        {
            Split *split = xaccTransGetSplit (txn, i);
            if (split == xfer_split)
                ++i;
            else
                xaccSplitDestroy(split);
        }
        /* Note: don't commit transaction now - that would insert an imbalance split.*/
    }
    else
    {
        txn = xaccMallocTransaction (book);
        xaccTransBeginEdit (txn);
    }

    /* Complete transaction setup */
    xaccTransSetDescription (txn, name ? name : "");
    if (!gnc_commodity_equal(xaccTransGetCurrency (txn), post_comm) &&
        !gnc_commodity_equal (xaccTransGetCurrency (txn), xfer_comm))
        xaccTransSetCurrency (txn, xfer_comm);

    /* With all commodities involved known, define split amounts and txn value.
     * - post amount (amount passed in as parameter) is always in post_acct commodity,
     * - xfer amount requires conversion if the xfer account has a different
     *   commodity than the post account.
     * - txn value requires conversion if the post account has a different
     *   commodity than the transaction */
    if (gnc_commodity_equal(post_comm, xfer_comm))
        xfer_amount = amount;
    else
        xfer_amount = gnc_numeric_mul (amount, exch, GNC_DENOM_AUTO,
                                       GNC_HOW_RND_ROUND_HALF_UP);

    if (gnc_commodity_equal(post_comm, xaccTransGetCurrency (txn)))
        txn_value = amount;
    else
        txn_value = gnc_numeric_mul (amount, exch, GNC_DENOM_AUTO,
                                      GNC_HOW_RND_ROUND_HALF_UP);

    /* Insert a split for the transfer account if we don't have one yet */
    if (!xfer_split)
    {
        /* The split for the transfer account */
        xfer_split = xaccMallocSplit (book);
        xaccSplitSetMemo (xfer_split, memo);
        /* set per book option */
        gnc_set_num_action (NULL, xfer_split, num, _("Payment"));
        xaccAccountBeginEdit (xfer_acc);
        xaccAccountInsertSplit (xfer_acc, xfer_split);
        xaccAccountCommitEdit (xfer_acc);
        xaccTransAppendSplit (txn, xfer_split);

        xaccSplitSetAmount(xfer_split, xfer_amount); /* Payment in xfer account currency */
        xaccSplitSetValue(xfer_split, txn_value); /* Payment in transaction currency */
    }
    /* For a pre-existing xfer split, let's check if the amount and value
     * have changed. If so, update them and unreconcile. */
    else if (!gnc_numeric_equal (xaccSplitGetAmount (xfer_split), xfer_amount) ||
             !gnc_numeric_equal (xaccSplitGetValue (xfer_split), txn_value))
    {
        xaccSplitSetAmount (xfer_split, xfer_amount);
        xaccSplitSetValue (xfer_split, txn_value);
        xaccSplitSetReconcile (xfer_split, NREC);
    }

    /* Add a split in the post account */
    split = xaccMallocSplit (book);
    xaccSplitSetMemo (split, memo);
    /* set per book option */
    xaccSplitSetAction (split, _("Payment"));
    xaccAccountBeginEdit (posted_acc);
    xaccAccountInsertSplit (posted_acc, split);
    xaccAccountCommitEdit (posted_acc);
    xaccTransAppendSplit (txn, split);
    xaccSplitSetAmount (split, gnc_numeric_neg (amount));
    xaccSplitSetValue (split, gnc_numeric_neg (txn_value));

    /* Create a new lot for the payment */
    payment_lot = gnc_lot_new (book);
    gncOwnerAttachToLot (owner, payment_lot);
    gnc_lot_add_split (payment_lot, split);

    /* Mark the transaction as a payment */
    xaccTransSetNum (txn, num);
    xaccTransSetTxnType (txn, TXN_TYPE_PAYMENT);

    /* Set date for transaction */
    xaccTransSetDateEnteredSecs (txn, gnc_time (NULL));
    xaccTransSetDatePostedSecs (txn, date);

    /* Commit this new transaction */
    xaccTransCommitEdit (txn);
    if (preset_txn)
        *preset_txn = txn;

    return payment_lot;
}

gncOwnerEqual()

gboolean gncOwnerEqual	(	const GncOwner *	a,
		const GncOwner *	b
	)

Assess equality by checking.

• if both owner objects refer to the same owner type
• and if the owner reference points to the same {vendor/customer/employee} in memory

Definition at line 404 of file gncOwner.c.

{
    if (!a || !b) return FALSE;
    if (gncOwnerGetType (a) != gncOwnerGetType (b)) return FALSE;
    return (a->owner.undefined == b->owner.undefined);
}

gncOwnerFindOffsettingSplit()

Split* gncOwnerFindOffsettingSplit	(	GNCLot *	lot,
		gnc_numeric	target_amount
	)

Helper function to find a split in lot that best offsets target_amount Obviously it should be of opposite sign.

If there are more splits of opposite sign the following criteria are used in order of preference:

1. exact match in abs amount is preferred over larger abs amount
2. larger abs amount is preferred over smaller abs amount
3. if previous and new candidate are in the same amount category, prefer real payment splits over lot link splits
4. if previous and new candidate are of same split type prefer biggest abs amount.

Definition at line 896 of file gncOwner.c.

{
    SplitList *ls_iter = NULL;
    Split *best_split = NULL;
    gnc_numeric best_amt = { 0, 1};
    gint best_flags = 0;

    if (!lot)
        return NULL;

    for (ls_iter = gnc_lot_get_split_list (lot); ls_iter; ls_iter = ls_iter->next)
    {
        Split *split = ls_iter->data;

        if (!split)
            continue;


        Transaction *txn = xaccSplitGetParent (split);
        if (!txn)
        {
            // Ooops - the split doesn't belong to any transaction !
            // This is not expected so issue a warning and continue with next split
            PWARN("Encountered a split in a payment lot that's not part of any transaction. "
                  "This is unexpected! Skipping split %p.", split);
            continue;
        }

        // Check if this split has the opposite sign of the target amount we want to offset
        gnc_numeric split_amount = xaccSplitGetAmount (split);
        if (gnc_numeric_positive_p (target_amount) == gnc_numeric_positive_p (split_amount))
            continue;

        // Ok we have found a split that potentially can offset the target value
        // Let's see if it's better than what we have found already.
        gint amt_cmp = gnc_numeric_compare (gnc_numeric_abs (split_amount),
                                            gnc_numeric_abs (target_amount));
        gint new_flags = 0;
        if (amt_cmp == 0)
            new_flags += is_equal;
        else if (amt_cmp > 0)
            new_flags += is_more;
        else
            new_flags += is_less;

        if (xaccTransGetTxnType (txn) != TXN_TYPE_LINK)
            new_flags += is_pay_split;

        if ((new_flags >= best_flags) &&
            (gnc_numeric_compare (gnc_numeric_abs (split_amount),
                                  gnc_numeric_abs (best_amt)) > 0))
        {
            // The new split is a better match than what we found so far
            best_split = split;
            best_flags = new_flags;
            best_amt   = split_amount;
        }
    }

    return best_split;
}

gncOwnerGetCustomer()

GncCustomer* gncOwnerGetCustomer

(

const GncOwner *

owner

)

If the given owner is of type GNC_OWNER_CUSTOMER, returns the pointer to the customer object.

Otherwise returns NULL.

Definition at line 369 of file gncOwner.c.

{
    if (!owner) return NULL;
    if (owner->type != GNC_OWNER_CUSTOMER) return NULL;
    return owner->owner.customer;
}

gncOwnerGetEmployee()

GncEmployee* gncOwnerGetEmployee

(

const GncOwner *

owner

)

If the given owner is of type GNC_OWNER_EMPLOYEE, returns the pointer to the employee object.

Otherwise returns NULL.

Definition at line 390 of file gncOwner.c.

{
    if (!owner) return NULL;
    if (owner->type != GNC_OWNER_EMPLOYEE) return NULL;
    return owner->owner.employee;
}

gncOwnerGetEndOwner()

const GncOwner* gncOwnerGetEndOwner

(

const GncOwner *

owner

)

Get the "parent" Owner or GncGUID thereof.

The "parent" owner is the Customer or Vendor, or the Owner of a Job

Definition at line 572 of file gncOwner.c.

{
    if (!owner) return NULL;
    switch (owner->type)
    {
    case GNC_OWNER_NONE:
    case GNC_OWNER_UNDEFINED:
    default:
        return NULL;
    case GNC_OWNER_CUSTOMER:
    case GNC_OWNER_VENDOR:
    case GNC_OWNER_EMPLOYEE:
        return owner;
    case GNC_OWNER_JOB:
        return gncJobGetOwner (owner->owner.job);
    }
}

gncOwnerGetJob()

GncJob* gncOwnerGetJob

(

const GncOwner *

owner

)

If the given owner is of type GNC_OWNER_JOB, returns the pointer to the job object.

Otherwise returns NULL.

Definition at line 376 of file gncOwner.c.

{
    if (!owner) return NULL;
    if (owner->type != GNC_OWNER_JOB) return NULL;
    return owner->owner.job;
}

gncOwnerGetOwnerFromLot()

gboolean gncOwnerGetOwnerFromLot	(	GNCLot *	lot,
		GncOwner *	owner
	)

Get the owner from the lot.

If an owner is found in the lot, fill in "owner" and return TRUE. Otherwise return FALSE.

Definition at line 636 of file gncOwner.c.

{
    GncGUID *guid = NULL;
    QofBook *book;
    GncOwnerType type = GNC_OWNER_NONE;
    guint64 type64 = 0;

    if (!lot || !owner) return FALSE;

    book = gnc_lot_get_book (lot);
    qof_instance_get (QOF_INSTANCE (lot),
              GNC_OWNER_TYPE, &type64,
              GNC_OWNER_GUID, &guid,
              NULL);
    type = (GncOwnerType) type64;
    switch (type)
    {
    case GNC_OWNER_CUSTOMER:
        gncOwnerInitCustomer (owner, gncCustomerLookup (book, guid));
        break;
    case GNC_OWNER_VENDOR:
        gncOwnerInitVendor (owner, gncVendorLookup (book, guid));
        break;
    case GNC_OWNER_EMPLOYEE:
        gncOwnerInitEmployee (owner, gncEmployeeLookup (book, guid));
        break;
    case GNC_OWNER_JOB:
        gncOwnerInitJob (owner, gncJobLookup (book, guid));
        break;
    default:
        guid_free (guid);
        return FALSE;
    }

    guid_free (guid);
    return (owner->owner.undefined != NULL);
}

gncOwnerGetOwnerFromTxn()

gboolean gncOwnerGetOwnerFromTxn	(	Transaction *	txn,
		GncOwner *	owner
	)

Convenience function to get the owner from a transaction.

Transactions don't really have an owner. What this function will do it figure out whether the transaction is part of a business transaction (either a posted invoice/bill/voucher/credit note or a payment transaction) and use the business object behind it to extract owner information.

Definition at line 674 of file gncOwner.c.

{
    Split *apar_split = NULL;

    if (!txn || !owner) return FALSE;

    if (xaccTransGetTxnType (txn) == TXN_TYPE_NONE)
        return FALSE;

    apar_split = xaccTransGetFirstAPARAcctSplit (txn, TRUE);
    if (apar_split)
    {
        GNCLot *lot = xaccSplitGetLot (apar_split);
        GncInvoice *invoice = gncInvoiceGetInvoiceFromLot (lot);
        if (invoice)
            gncOwnerCopy (gncInvoiceGetOwner (invoice), owner);
        else if (!gncOwnerGetOwnerFromLot (lot, owner))
                return FALSE;

        return TRUE; // Got owner from either invoice or lot
    }

    return FALSE;
}

gncOwnerGetType()

GncOwnerType gncOwnerGetType

(

const GncOwner *

owner

)

Returns the GncOwnerType of this owner.

(Not to be confused with qofOwnerGetType().)

Definition at line 200 of file gncOwner.c.

{
    if (!owner) return GNC_OWNER_NONE;
    return owner->type;
}

gncOwnerGetTypeString()

const char* gncOwnerGetTypeString

(

const GncOwner *

owner

)

return the type for the owner as an untranslated string.

Definition at line 206 of file gncOwner.c.

{
    GncOwnerType type = gncOwnerGetType(owner);
    switch (type)
    {
    case GNC_OWNER_NONE:
        return N_("None");
    case GNC_OWNER_UNDEFINED:
        return N_("Undefined");
    case GNC_OWNER_CUSTOMER:
        return N_("Customer");
    case GNC_OWNER_JOB:
        return N_("Job");
    case GNC_OWNER_VENDOR:
        return N_("Vendor");
    case GNC_OWNER_EMPLOYEE:
        return N_("Employee");
    default:
        PWARN ("Unknown owner type");
        return NULL;
    }
}

gncOwnerGetUndefined()

gpointer gncOwnerGetUndefined

(

const GncOwner *

owner

)

If the given owner is of type GNC_OWNER_UNDEFINED, returns the undefined pointer, which is usually NULL.

Otherwise returns NULL.

Definition at line 362 of file gncOwner.c.

{
    if (!owner) return NULL;
    if (owner->type != GNC_OWNER_UNDEFINED) return NULL;
    return owner->owner.undefined;
}

gncOwnerGetVendor()

GncVendor* gncOwnerGetVendor

(

const GncOwner *

owner

)

If the given owner is of type GNC_OWNER_VENDOR, returns the pointer to the vendor object.

Otherwise returns NULL.

Definition at line 383 of file gncOwner.c.

{
    if (!owner) return NULL;
    if (owner->type != GNC_OWNER_VENDOR) return NULL;
    return owner->owner.vendor;
}

gncOwnerIsValid()

gboolean gncOwnerIsValid

(

const GncOwner *

owner

)

Returns TRUE if the given owner is one of the valid objects.

Returns FALSE if the owner is (still) undefined, or if it is NULL.

Definition at line 699 of file gncOwner.c.

{
    if (!owner) return FALSE;
    return (owner->owner.undefined != NULL);
}

gncOwnerLotsSortFunc()

gint gncOwnerLotsSortFunc	(	GNCLot *	lotA,
		GNCLot *	lotB
	)

Helper function used to sort lots by date.

If the lot is linked to an invoice, use the invoice posted date, otherwise use the lot's opened date.

Definition at line 728 of file gncOwner.c.

{
    GncInvoice *ia, *ib;
    time64 da, db;

    ia = gncInvoiceGetInvoiceFromLot (lotA);
    ib = gncInvoiceGetInvoiceFromLot (lotB);

    if (ia)
        da = gncInvoiceGetDateDue (ia);
    else
        da = xaccTransRetDatePosted (xaccSplitGetParent (gnc_lot_get_earliest_split (lotA)));

    if (ib)
        db = gncInvoiceGetDateDue (ib);
    else
        db = xaccTransRetDatePosted (xaccSplitGetParent (gnc_lot_get_earliest_split (lotB)));

    return (da > db) - (da < db);
}

gncOwnerNew()

GncOwner* gncOwnerNew

(

void

)

These two functions are mainly for the convenience of scheme code.

Normal C code has no need to ever use these two functions, and rather can just use a GncOwner directly and just pass around a pointer to it.

Definition at line 57 of file gncOwner.c.

{
    GncOwner *o;

    o = g_new0 (GncOwner, 1);
    o->type = GNC_OWNER_NONE;
    return o;
}

gncOwnerReduceSplitTo()

gboolean gncOwnerReduceSplitTo	(	Split *	split,
		gnc_numeric	target_amount
	)

Helper function to reduce the amount of a split to target_amount.

To make sure the split's parent transaction remains balanced a second split will be created with the remainder. Similarly if the split was part of a (business) lot, the remainder split will be added to the same lot to keep the lot's balance unchanged.

Definition at line 959 of file gncOwner.c.

{
    gnc_numeric split_amt = xaccSplitGetAmount (split);
    if (gnc_numeric_positive_p (split_amt) != gnc_numeric_positive_p (target_amount))
        return FALSE; // Split and target amount have to be of the same sign

    if (gnc_numeric_equal (split_amt, target_amount))
        return FALSE; // Split already has the target amount

    if (gnc_numeric_zero_p (split_amt))
        return FALSE; // We can't reduce a split that already has zero amount

    Transaction *txn = xaccSplitGetParent (split);
    xaccTransBeginEdit (txn);

    /* Calculate new value for reduced split. This can be different from
     * the reduced split's new amount (when account and transaction
     * commodity differ) */
    gnc_numeric split_val = xaccSplitGetValue (split);
    gnc_numeric exch = gnc_numeric_div (split_val, split_amt,
                                        GNC_DENOM_AUTO, GNC_HOW_DENOM_LCD);

    gint64 txn_comm_fraction = gnc_commodity_get_fraction (xaccTransGetCurrency (txn));
    gnc_numeric target_val = gnc_numeric_mul (target_amount, exch,
                                              txn_comm_fraction,
                                              GNC_HOW_RND_ROUND_HALF_UP);
    xaccSplitSetAmount (split, target_amount);
    xaccSplitSetValue (split, target_val);

    /* Calculate amount and value for remainder split.
     * Note we calculate the remaining value by subtracting the new target value
     * from the original split's value rather than multiplying the remaining
     * amount with the exchange rate to avoid imbalances due to rounding errors. */
    gnc_numeric rem_amt = gnc_numeric_sub (split_amt, target_amount, GNC_DENOM_AUTO, GNC_HOW_DENOM_FIXED);
    gnc_numeric rem_val = gnc_numeric_sub (split_val, target_val, GNC_DENOM_AUTO, GNC_HOW_DENOM_FIXED);

    Split *rem_split = xaccMallocSplit (xaccSplitGetBook (split));
    xaccSplitCopyOnto (split, rem_split);
    xaccSplitSetAmount (rem_split, rem_amt);
    xaccSplitSetValue (rem_split, rem_val);
    xaccSplitSetParent (rem_split, txn);

    xaccTransCommitEdit (txn);

    GNCLot *lot = xaccSplitGetLot (split);
    gnc_lot_add_split (lot, rem_split);

    return TRUE;
}

gncOwnerSetLotLinkMemo()

void gncOwnerSetLotLinkMemo

(

Transaction *

ll_txn

)

To help a user understand what a lot link transaction does, we set the memo to name all documents involved in the link.

The function below calculates this memo and sets it for all splits in the lot link transaction.

Definition at line 1010 of file gncOwner.c.

{
    gchar *memo_prefix = _("Offset between documents: ");
    gchar *new_memo;
    SplitList *lts_iter;
    SplitList *splits = NULL, *siter;
    GList *titles = NULL, *titer;

    if (!ll_txn)
        return;

    if (xaccTransGetTxnType (ll_txn) != TXN_TYPE_LINK)
        return;

    // Find all splits in the lot link transaction that are also in a document lot
    for (lts_iter = xaccTransGetSplitList (ll_txn); lts_iter; lts_iter = lts_iter->next)
    {
        Split *split = lts_iter->data;
        GNCLot *lot;
        GncInvoice *invoice;
        gchar *title;

        if (!split)
            continue;

        lot = xaccSplitGetLot (split);
        if (!lot)
            continue;

        invoice = gncInvoiceGetInvoiceFromLot (lot);
        if (!invoice)
            continue;

        title = g_strdup_printf ("%s %s", gncInvoiceGetTypeString (invoice), gncInvoiceGetID (invoice));

        titles = g_list_prepend (titles, title);
        splits = g_list_prepend (splits, split); // splits don't need to be sorted
    }

    if (!titles)
        return; // We didn't find document lots

    titles = g_list_sort (titles, (GCompareFunc)g_strcmp0);

    // Create the memo as we'd want it to be
    new_memo = g_strconcat (memo_prefix, titles->data, NULL);
    for (titer = titles->next; titer; titer = titer->next)
    {
        gchar *tmp_memo = g_strconcat (new_memo, " - ", titer->data, NULL);
        g_free (new_memo);
        new_memo = tmp_memo;
    }
    g_list_free_full (titles, g_free);

    // Update the memos of all the splits we found previously (if needed)
    for (siter = splits; siter; siter = siter->next)
    {
        if (g_strcmp0 (xaccSplitGetMemo (siter->data), new_memo) != 0)
            xaccSplitSetMemo (siter->data, new_memo);
    }

    g_list_free (splits);
    g_free (new_memo);
}

gncOwnerTypeToQofIdType()

QofIdTypeConst gncOwnerTypeToQofIdType

(

GncOwnerType

t

)

Returns the QofIdType of the given GncOwnerType, or NULL if no suitable one exists.

Definition at line 235 of file gncOwner.c.

{
    QofIdTypeConst type = NULL;
    switch (t)
    {
    case GNC_OWNER_NONE :
    {
        type = NULL;
        break;
    }
    case GNC_OWNER_UNDEFINED :
    {
        type = NULL;
        break;
    }
    case GNC_OWNER_CUSTOMER :
    {
        type = GNC_ID_CUSTOMER;
        break;
    }
    case GNC_OWNER_JOB :
    {
        type = GNC_ID_JOB;
        break;
    }
    case GNC_OWNER_VENDOR :
    {
        type = GNC_ID_VENDOR;
        break;
    }
    case GNC_OWNER_EMPLOYEE :
    {
        type = GNC_ID_EMPLOYEE;
        break;
    }
    }
    return type;
}

qofOwnerGetOwner()

QofInstance* qofOwnerGetOwner

(

const GncOwner *

owner

)

return the owner itself as an entity.

Definition at line 275 of file gncOwner.c.

{
    QofInstance *ent;

    if (!owner)
    {
        return NULL;
    }
    ent = NULL;
    switch (owner->type)
    {
    case GNC_OWNER_NONE :
    {
        break;
    }
    case GNC_OWNER_UNDEFINED :
    {
        break;
    }
    case GNC_OWNER_CUSTOMER :
    {
        ent = QOF_INSTANCE(owner->owner.customer);
        break;
    }
    case GNC_OWNER_JOB :
    {
        ent = QOF_INSTANCE(owner->owner.job);
        break;
    }
    case GNC_OWNER_VENDOR :
    {
        ent = QOF_INSTANCE(owner->owner.vendor);
        break;
    }
    case GNC_OWNER_EMPLOYEE :
    {
        ent = QOF_INSTANCE(owner->owner.employee);
        break;
    }
    }
    return ent;
}

qofOwnerGetType()

QofIdTypeConst qofOwnerGetType

(

const GncOwner *

owner

)

return the type for the collection.

Definition at line 230 of file gncOwner.c.

{
    return gncOwnerTypeToQofIdType(owner->type);
}

qofOwnerSetEntity()

void qofOwnerSetEntity	(	GncOwner *	owner,
		QofInstance *	ent
	)

set the owner from the entity.

Definition at line 319 of file gncOwner.c.

{
    if (!owner || !ent)
    {
        return;
    }
    if (0 == g_strcmp0(ent->e_type, GNC_ID_CUSTOMER))
    {
        owner->type = GNC_OWNER_CUSTOMER;
        gncOwnerInitCustomer(owner, (GncCustomer*)ent);
    }
    else if (0 == g_strcmp0(ent->e_type, GNC_ID_JOB))
    {
        owner->type = GNC_OWNER_JOB;
        gncOwnerInitJob(owner, (GncJob*)ent);
    }
    else if (0 == g_strcmp0(ent->e_type, GNC_ID_VENDOR))
    {
        owner->type = GNC_OWNER_VENDOR;
        gncOwnerInitVendor(owner, (GncVendor*)ent);
    }
    else if (0 == g_strcmp0(ent->e_type, GNC_ID_EMPLOYEE))
    {
        owner->type = GNC_OWNER_EMPLOYEE;
        gncOwnerInitEmployee(owner, (GncEmployee*)ent);
    }
    else
    {
        owner->type = GNC_OWNER_NONE;
        owner->owner.undefined = NULL;
    }
}