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"
#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"

Typedefs
typedef struct _gncOwner	GncOwner

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)
GncGUID	gncOwnerRetGUID (GncOwner *owner)
const GncOwner *	gncOwnerGetEndOwner (const GncOwner *owner)
const GncGUID *	gncOwnerGetEndGUID (const GncOwner *owner)
void	gncOwnerAttachToLot (const GncOwner *owner, GNCLot *lot)
gboolean	gncOwnerLotMatchOwnerFunc (GNCLot *lot, gpointer user_data)
gint	gncOwnerLotsSortFunc (GNCLot *lotA, GNCLot *lotB)
gboolean	gncOwnerGetOwnerFromLot (GNCLot *lot, GncOwner *owner)
gboolean	gncOwnerGetOwnerFromTypeGuid (QofBook *book, GncOwner *owner, QofIdType type, GncGUID *guid)
GNCLot *	gncOwnerCreatePaymentLot (const GncOwner *owner, Transaction *txn, Account *posted_acc, Account *xfer_acc, gnc_numeric amount, gnc_numeric exch, Timespec date, const char *memo, const char *num)
void	gncOwnerAutoApplyPaymentsWithLots (const GncOwner *owner, GList *lots)
void	gncOwnerApplyPayment (const GncOwner *owner, Transaction *txn, GList *lots, Account *posted_acc, Account *xfer_acc, gnc_numeric amount, gnc_numeric exch, Timespec date, const char *memo, const char *num, gboolean auto_pay)
Split *	gncOwnerFindOffsettingSplit (GNCLot *pay_lot, gnc_numeric target_value)
gboolean	gncOwnerReduceSplitTo (Split *split, gnc_numeric target_value)
void	gncOwnerSetLotLinkMemo (Transaction *ll_txn)
GList *	gncOwnerGetAccountTypesList (const GncOwner *owner)
GList *	gncOwnerGetCommoditiesList (const GncOwner *owner)
gnc_numeric	gncOwnerGetBalanceInCurrency (const GncOwner *owner, const gnc_commodity *report_currency)
GncOwner *	gncOwnerNew (void)
void	gncOwnerFree (GncOwner *owner)
void	gncOwnerBeginEdit (GncOwner *owner)
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)
QofInstance *	qofOwnerGetOwner (const GncOwner *owner)
void	qofOwnerSetEntity (GncOwner *owner, QofInstance *ent)
gboolean	GNC_IS_OWNER (QofInstance *ent)
QofIdTypeConst	gncOwnerTypeToQofIdType (GncOwnerType t)
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)
gboolean	gncOwnerIsValid (const GncOwner *owner)
gpointer	gncOwnerGetUndefined (const GncOwner *owner)
GncCustomer *	gncOwnerGetCustomer (const GncOwner *owner)
GncJob *	gncOwnerGetJob (const GncOwner *owner)
GncVendor *	gncOwnerGetVendor (const GncOwner *owner)
GncEmployee *	gncOwnerGetEmployee (const GncOwner *owner)
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)
int	gncOwnerGCompareFunc (const GncOwner *a, const GncOwner *b)
int	gncOwnerCompare (const GncOwner *a, const GncOwner *b)

Detailed Description

Macro Definition Documentation

#define OWNER_TYPE_STRING   "type-string"

Allows the type to be handled externally.

Definition at line 309 of file gncOwner.h.

Function Documentation

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 330 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));
}

void gncOwnerApplyPayment	(	const GncOwner *	owner,
		Transaction *	txn,
		GList *	lots,
		Account *	posted_acc,
		Account *	xfer_acc,
		gnc_numeric	amount,
		gnc_numeric	exch,
		Timespec	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 1348 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 there's a real amount to transfer create a lot for this payment */
    if (!gnc_numeric_zero_p (amount))
        payment_lot = gncOwnerCreatePaymentLot (owner, txn, posted_acc, xfer_acc,
                                                amount, exch, date, memo, num);

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

    /* 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);
}

void gncOwnerAttachToLot	(	const GncOwner *	owner,
		GNCLot *	lot
	)

Attach an owner to a lot

Definition at line 600 of file gncOwner.c.

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

    gnc_lot_begin_edit (lot);

    qof_instance_set (QOF_INSTANCE (lot),
                      GNC_OWNER_TYPE, (gint64)gncOwnerGetType (owner),
                      GNC_OWNER_GUID, gncOwnerGetGUID (owner),
                      NULL);
    gnc_lot_commit_edit (lot);
}

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 1199 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);

    }
}

void gncOwnerBeginEdit

(

GncOwner *

owner

)

These are convenience wrappers around gnc{Vender,Customer,Job,Employee}* functions. This allows you to begin edit, destroy commit edit an owner without knowing its type.

Definition at line 73 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;
    }
    }
}

int gncOwnerCompare	(	const GncOwner *	a,
		const GncOwner *	b
	)

Sort on name

Definition at line 568 of file gncOwner.c.

{
    if (!a && !b) return 0;
    if (!a && b) return 1;
    if (a && !b) return -1;

    if (a->type != b->type)
        return (a->type - b->type);

    switch (a->type)
    {
    case GNC_OWNER_NONE:
    case GNC_OWNER_UNDEFINED:
    default:
        return 0;
    case GNC_OWNER_CUSTOMER:
        return gncCustomerCompare (a->owner.customer, b->owner.customer);
    case GNC_OWNER_VENDOR:
        return gncVendorCompare (a->owner.vendor, b->owner.vendor);
    case GNC_OWNER_EMPLOYEE:
        return gncEmployeeCompare (a->owner.employee, b->owner.employee);
    case GNC_OWNER_JOB:
        return gncJobCompare (a->owner.job, b->owner.job);
    }
}

GNCLot* gncOwnerCreatePaymentLot	(	const GncOwner *	owner,
		Transaction *	txn,
		Account *	posted_acc,
		Account *	xfer_acc,
		gnc_numeric	amount,
		gnc_numeric	exch,
		Timespec	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 701 of file gncOwner.c.

{
    QofBook *book;
    Split *split;
    const char *name;
    gnc_commodity *commodity;
    Split *xfer_split = NULL;
    GNCLot *payment_lot;

    /* 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));
    commodity = gncOwnerGetCurrency (owner);
//    reverse = use_reversed_payment_amounts(owner);

    if (txn)
    {
        /* Pre-existing transaction was specified. We completely clear it,
         * except for the split in the transfer account, unless the
         * transaction can't be reused (wrong currency, wrong transfer account).
         * In that case, the transaction is simply removed and an new
         * one created. */

        xfer_split = xaccTransFindSplitByAccount(txn, xfer_acc);

        if (xaccTransGetCurrency(txn) != gncOwnerGetCurrency (owner))
        {
            g_message("Uh oh, mismatching currency/commodity between selected transaction and owner. We fall back to manual creation of a new transaction.");
            xfer_split = NULL;
        }

        if (!xfer_split)
        {
            g_message("Huh? Asset account not found anymore. Fully deleting old txn and now creating a new one.");

            xaccTransBeginEdit (txn);
            xaccTransDestroy (txn);
            xaccTransCommitEdit (txn);

            txn = NULL;
        }
        else
        {
            int i = 0;
            xaccTransBeginEdit (txn);
            while (i < xaccTransCountSplits(txn))
            {
                Split *split = xaccTransGetSplit (txn, i);
                if (split == xfer_split)
                {
                    gnc_set_num_action (NULL, split, num, _("Payment"));
                    ++i;
                }
                else
                {
                    xaccSplitDestroy(split);
                }
            }
            /* Note: don't commit transaction now - that would insert an imbalance split.*/
        }
    }

    /* Create the transaction if we don't have one yet */
    if (!txn)
    {
        txn = xaccMallocTransaction (book);
        xaccTransBeginEdit (txn);
    }

    /* Insert a split for the transfer account if we don't have one yet */
    if (!xfer_split)
    {

        /* Set up the transaction */
        xaccTransSetDescription (txn, name ? name : "");
        /* set per book option */
        xaccTransSetCurrency (txn, commodity);
        xaccTransSetDateEnteredSecs (txn, gnc_time (NULL));
        xaccTransSetDatePostedTS (txn, &date);


        /* The split for the transfer account */
        split = xaccMallocSplit (book);
        xaccSplitSetMemo (split, memo);
        /* set per book option */
        gnc_set_num_action (NULL, split, num, _("Payment"));
        xaccAccountBeginEdit (xfer_acc);
        xaccAccountInsertSplit (xfer_acc, split);
        xaccAccountCommitEdit (xfer_acc);
        xaccTransAppendSplit (txn, split);

        if (gnc_commodity_equal(xaccAccountGetCommodity(xfer_acc), commodity))
        {
            xaccSplitSetBaseValue (split, amount, commodity);
        }
        else
        {
            /* Need to value the payment in terms of the owner commodity */
            gnc_numeric payment_value = gnc_numeric_mul(amount,
                                        exch, GNC_DENOM_AUTO, GNC_HOW_RND_ROUND_HALF_UP);

            xaccSplitSetAmount(split, amount);
            xaccSplitSetValue(split, payment_value);
        }
    }

    /* Add a split in the post account */
    split = xaccMallocSplit (book);
    xaccSplitSetMemo (split, memo);
    /* set per book option */
    gnc_set_num_action (NULL, split, num, _("Payment"));
    xaccAccountBeginEdit (posted_acc);
    xaccAccountInsertSplit (posted_acc, split);
    xaccAccountCommitEdit (posted_acc);
    xaccTransAppendSplit (txn, split);
    xaccSplitSetBaseValue (split, gnc_numeric_neg (amount), commodity);

    /* 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 */
    gnc_set_num_action (txn, NULL, num, _("Payment"));
    xaccTransSetTxnType (txn, TXN_TYPE_PAYMENT);

    /* Commit this new transaction */
    xaccTransCommitEdit (txn);

    return payment_lot;
}

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 382 of file gncOwner.c.

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

Split* gncOwnerFindOffsettingSplit	(	GNCLot *	pay_lot,
		gnc_numeric	target_value
	)

Helper function to find a split in lot that best offsets target_value 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 value is preferred over larger abs value
2. larger abs value is preferred over smaller abs value
3. if previous and new candidate are in the same value category, prefer real payment splits over lot link splits
4. if previous and new candiate are of same split type prefer biggest abs value.

Definition at line 848 of file gncOwner.c.

{
    SplitList *ls_iter = NULL;
    Split *best_split = NULL;
    gnc_numeric best_val = { 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;
        Transaction *txn;
        gnc_numeric split_value;
        gint new_flags = 0;
        gint val_cmp = 0;

        if (!split)
            continue;


        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 value we want to offset
        split_value = xaccSplitGetValue (split);
        if (gnc_numeric_positive_p (target_value) == gnc_numeric_positive_p (split_value))
            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.
        val_cmp = gnc_numeric_compare (gnc_numeric_abs (split_value),
                                       gnc_numeric_abs (target_value));
        if (val_cmp == 0)
            new_flags += is_equal;
        else if (val_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_value),
                                  gnc_numeric_abs (best_val)) > 0))
        {
            // The new split is a better match than what we found so far
            best_split = split;
            best_flags = new_flags;
            best_val   = split_value;
        }
    }

    return best_split;
}

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

Definition at line 389 of file gncOwner.c.

{
    if (gncOwnerEqual (a, b))
        return 0;
    else
        return 1;
}

GList* gncOwnerGetAccountTypesList

(

const GncOwner *

owner

)

Returns a GList of account-types based on the owner type

Definition at line 1383 of file gncOwner.c.

{
    g_return_val_if_fail (owner, NULL);

    switch (gncOwnerGetType (owner))
    {
    case GNC_OWNER_CUSTOMER:
        return (g_list_prepend (NULL, (gpointer)ACCT_TYPE_RECEIVABLE));
    case GNC_OWNER_VENDOR:
    case GNC_OWNER_EMPLOYEE:
        return (g_list_prepend (NULL, (gpointer)ACCT_TYPE_PAYABLE));
        break;
    default:
        return (g_list_prepend (NULL, (gpointer)ACCT_TYPE_NONE));
    }
}

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.

Definition at line 1417 of file gncOwner.c.

{
    gnc_numeric balance = gnc_numeric_zero ();
    GList *acct_list, *acct_node, *acct_types, *lot_list = NULL, *lot_node;
    QofBook *book;
    gnc_commodity *owner_currency;
    GNCPriceDB *pdb;

    g_return_val_if_fail (owner, gnc_numeric_zero ());

    /* Get account list */
    book       = qof_instance_get_book (qofOwnerGetOwner (owner));
    acct_list  = gnc_account_get_descendants (gnc_book_get_root_account (book));
    acct_types = gncOwnerGetAccountTypesList (owner);
    owner_currency = gncOwnerGetCurrency (owner);

    /* For each account */
    for (acct_node = acct_list; acct_node; acct_node = acct_node->next)
    {
        Account *account = acct_node->data;

        /* Check if this account can have lots for the owner, otherwise skip to next */
        if (g_list_index (acct_types, (gpointer)xaccAccountGetType (account))
                == -1)
            continue;


        if (!gnc_commodity_equal (owner_currency, xaccAccountGetCommodity (account)))
            continue;

        /* Get a list of open lots for this owner and account */
        lot_list = xaccAccountFindOpenLots (account, gncOwnerLotMatchOwnerFunc,
                                            (gpointer)owner, NULL);
        /* For each lot */
        for (lot_node = lot_list; lot_node; lot_node = lot_node->next)
        {
            GNCLot *lot = lot_node->data;
            gnc_numeric lot_balance = gnc_lot_get_balance (lot);
            GncInvoice *invoice = gncInvoiceGetInvoiceFromLot(lot);
            if (invoice)
               balance = gnc_numeric_add (balance, lot_balance,
                                          gnc_commodity_get_fraction (owner_currency), GNC_HOW_RND_ROUND_HALF_UP);
        }
    }

    pdb = gnc_pricedb_get_db (book);

    if (report_currency)
        balance = gnc_pricedb_convert_balance_latest_price (
                      pdb, balance, owner_currency, report_currency);

    return balance;
}

GList* gncOwnerGetCommoditiesList

(

const GncOwner *

owner

)

Returns a GList of currencies associated with the owner

Definition at line 1401 of file gncOwner.c.

{
    g_return_val_if_fail (owner, NULL);
    g_return_val_if_fail (gncOwnerGetCurrency(owner), NULL);

    return (g_list_prepend (NULL, gncOwnerGetCurrency(owner)));
}

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 347 of file gncOwner.c.

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

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 368 of file gncOwner.c.

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

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 550 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);
    }
}

const GncGUID* gncOwnerGetGUID

(

const GncOwner *

owner

)

Get the GncGUID of the immediate owner

Definition at line 496 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:
        return qof_instance_get_guid (QOF_INSTANCE(owner->owner.customer));
    case GNC_OWNER_JOB:
        return qof_instance_get_guid (QOF_INSTANCE(owner->owner.job));
    case GNC_OWNER_VENDOR:
        return qof_instance_get_guid (QOF_INSTANCE(owner->owner.vendor));
    case GNC_OWNER_EMPLOYEE:
        return qof_instance_get_guid (QOF_INSTANCE(owner->owner.employee));
    }
}

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 354 of file gncOwner.c.

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

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 614 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:
        return FALSE;
    }

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

GncOwnerType gncOwnerGetType

(

const GncOwner *

owner

)

Returns the GncOwnerType of this owner. (Not to be confused with qofOwnerGetType().)

Definition at line 201 of file gncOwner.c.

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

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 340 of file gncOwner.c.

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

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 361 of file gncOwner.c.

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

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 650 of file gncOwner.c.

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

gboolean gncOwnerLotMatchOwnerFunc	(	GNCLot *	lot,
		gpointer	user_data
	)

Helper function used to filter a list of lots by owner.

Definition at line 657 of file gncOwner.c.

{
    const GncOwner *req_owner = user_data;
    GncOwner lot_owner;
    const GncOwner *end_owner;
    GncInvoice *invoice = gncInvoiceGetInvoiceFromLot (lot);

    /* Determine the owner associated to the lot */
    if (invoice)
        /* Invoice lots */
        end_owner = gncOwnerGetEndOwner (gncInvoiceGetOwner (invoice));
    else if (gncOwnerGetOwnerFromLot (lot, &lot_owner))
        /* Pre-payment lots */
        end_owner = gncOwnerGetEndOwner (&lot_owner);
    else
        return FALSE;

    /* Is this a lot for the requested owner ? */
    return gncOwnerEqual (end_owner, req_owner);
}

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 679 of file gncOwner.c.

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

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

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

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

    return timespec_cmp (&da, &db);
}

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 58 of file gncOwner.c.

{
    GncOwner *o;

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

gboolean gncOwnerReduceSplitTo	(	Split *	split,
		gnc_numeric	target_value
	)

Helper function to reduce the value of a split to target_value. 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 914 of file gncOwner.c.

{
    gnc_numeric split_val = xaccSplitGetValue (split);
    gnc_numeric rem_val;
    Split *rem_split;
    Transaction *txn;
    GNCLot *lot;

    if (gnc_numeric_positive_p (split_val) != gnc_numeric_positive_p (target_value))
        return FALSE; // Split and target value have to be of the same sign

    if (gnc_numeric_equal (split_val, target_value))
        return FALSE; // Split already has the target value

    rem_val = gnc_numeric_sub (split_val, target_value, GNC_DENOM_AUTO, GNC_HOW_DENOM_LCD); // note: values are of opposite sign
    rem_split = xaccMallocSplit (xaccSplitGetBook (split));
    xaccSplitCopyOnto (split, rem_split);
    xaccSplitSetValue (rem_split, rem_val);

    txn = xaccSplitGetParent (split);
    xaccTransBeginEdit (txn);
    xaccSplitSetValue (split, target_value);
    xaccSplitSetParent (rem_split, txn);
    xaccTransCommitEdit (txn);

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

    return TRUE;
}

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 946 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_insert_sorted (titles, title, (GCompareFunc)g_strcmp0);
        splits = g_list_prepend (splits, split); // splits don't need to be sorted
    }

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

    // 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);
}

QofIdTypeConst gncOwnerTypeToQofIdType

(

GncOwnerType

t

)

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

Definition at line 213 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;
}

QofInstance* qofOwnerGetOwner

(

const GncOwner *

owner

)

return the owner itself as an entity.

Definition at line 253 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;
}

QofIdTypeConst qofOwnerGetType

(

const GncOwner *

owner

)

return the type for the collection.

Definition at line 208 of file gncOwner.c.

{
    return gncOwnerTypeToQofIdType(owner->type);
}

void qofOwnerSetEntity	(	GncOwner *	owner,
		QofInstance *	ent
	)

set the owner from the entity.

Definition at line 297 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;
    }
}