Instance
[Class: Getting and setting entity values.]

Files
file	qofinstance.h
	Object instance holds common fields that most QofObjects use.
Defines
#define	QOF_INSTANCE(object)   ((QofInstance *)(object))
Typedefs
typedef struct QofInstance_s	QofInstance
Functions
void	qof_instance_init (QofInstance *, QofIdType, QofBook *)
void	qof_instance_release (QofInstance *inst)
QofBook *	qof_instance_get_book (QofInstance *)
const GUID *	qof_instance_get_guid (QofInstance *)
KvpFrame *	qof_instance_get_slots (QofInstance *)
QofTime *	qof_instance_get_update_time (QofInstance *inst)
gint	qof_instance_version_cmp (QofInstance *left, QofInstance *right)
gboolean	qof_instance_is_dirty (QofInstance *)
void	qof_instance_set_dirty (QofInstance *inst)
	Set the dirty flag.
gboolean	qof_instance_check_edit (QofInstance *inst)
gboolean	qof_instance_do_free (QofInstance *inst)
void	qof_instance_mark_free (QofInstance *inst)
QofInstance *	qof_instance_create (QofIdType type, QofBook *book)
void	qof_instance_gemini (QofInstance *to, QofInstance *from)
QofInstance *	qof_instance_lookup_twin (QofInstance *src, QofBook *book)

---

Detailed Description

Qof Instances are a derived type of QofEntity. The Instance adds some common features and functions that most objects will want to use.

---

Function Documentation

void qof_instance_gemini	(	QofInstance *	to,
		QofInstance *	from
	)

Pair things up. This routine inserts a kvp value into each instance containing the guid of the other. In this way, if one has one of the pair, one can always find the other by looking up it's guid. Typically, you will want to use qof_instance_lookup_twin() to find the twin. (The current implementation assumes the two instances belong to different books, and will not add gemini kvp's unless the books differ. Note that the gemini kvp includes the book guid as well, so that the right book can be found.

Definition at line 212 of file qofinstance.c.

{
    QofTime *qt;

    /* Books must differ for a gemini to be meaningful */
    if (!from || !to || (from->book == to->book))
        return;

    qt = qof_time_get_current ();

    /* Make a note of where the copy came from */
    qof_kvp_bag_add (to->kvp_data, "gemini", qt,
        "inst_guid", &from->entity.guid,
        "book_guid", &from->book->inst.entity.guid, NULL);
    qof_kvp_bag_add (from->kvp_data, "gemini", qt,
        "inst_guid", &to->entity.guid,
        "book_guid", &to->book->inst.entity.guid, NULL);

    to->dirty = TRUE;
}

QofBook* qof_instance_get_book

(

QofInstance *

)

Return the book pointer

Definition at line 87 of file qofinstance.c.

{
    if (!inst)
        return NULL;
    return inst->book;
}

const GUID* qof_instance_get_guid

(

QofInstance *

)

Return the GUID of this instance

Definition at line 79 of file qofinstance.c.

{
    if (!inst)
        return NULL;
    return &inst->entity.guid;
}

KvpFrame* qof_instance_get_slots

(

QofInstance *

)

Return the pointer to the kvp_data

Definition at line 95 of file qofinstance.c.

{
    if (!inst)
        return NULL;
    return inst->kvp_data;
}

QofTime* qof_instance_get_update_time

(

QofInstance *

inst

)

Return the last time this instance was modified. If QofInstances are used with the QofObject storage backends, then the instance update times are reserved for use by the backend, for managing multi-user updates. Non-backend code should not set the update times.

Definition at line 103 of file qofinstance.c.

{
    if (!inst)
    {
        QofTime *time;

        time = qof_time_get_current ();
        return time;
    }
    return inst->update_time;
}

void qof_instance_init	(	QofInstance *	,
		QofIdType	,
		QofBook *
	)

Initialise the memory associated with an instance

Definition at line 53 of file qofinstance.c.

{
    QofCollection *col;

    inst->book = book;
    inst->kvp_data = kvp_frame_new ();
    inst->update_time = qof_time_get_current ();
    inst->editlevel = 0;
    inst->do_free = FALSE;
    inst->dirty = FALSE;

    col = qof_book_get_collection (book, type);
    qof_entity_init (&inst->entity, type, col);
}

gboolean qof_instance_is_dirty

(

QofInstance *

)

Return value of is_dirty flag

Definition at line 128 of file qofinstance.c.

{
    QofCollection *coll;

    if (!inst)
    {
        return FALSE;
    }
    coll = inst->entity.collection;
    if (qof_collection_is_dirty (coll))
    {
        return inst->dirty;
    }
    inst->dirty = FALSE;
    return FALSE;
}

QofInstance* qof_instance_lookup_twin	(	QofInstance *	src,
		QofBook *	book
	)

The qof_instance_lookup_twin() routine will find the "twin" of this instance 'src' in the given other 'book' (if the twin exists).

When instances are gemini'ed or cloned, both of the pair are marked with the guid of thier copy, thus allowing the sibling-copy of an instance to be found. Since the sibling may end up in a different book, we need a way of finding it, given only that we know the book, and that we know its twin.

That's what this routine does. Given some book 'book', and an instance 'src', it will find the sibling instance of 'src' that is in 'book', and return it. If not found, it returns NULL. This routine uses the 'gemini' kvp values to do its work.

Definition at line 234 of file qofinstance.c.

{
    QofCollection *col;
    KvpFrame *fr;
    GUID *twin_guid;
    QofInstance *twin;

    if (!src || !target_book)
        return NULL;
    ENTER (" ");

    fr = qof_kvp_bag_find_by_guid (src->kvp_data, "gemini",
        "book_guid", &target_book->inst.entity.guid);

    twin_guid = kvp_frame_get_guid (fr, "inst_guid");

    col = qof_book_get_collection (target_book, src->entity.e_type);
    twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);

    LEAVE (" found twin=%p", twin);
    return twin;
}

void qof_instance_release

(

QofInstance *

inst

)

release the data associated with this instance. Dont actually free the memory associated with the instance.

Definition at line 69 of file qofinstance.c.

{
    kvp_frame_delete (inst->kvp_data);
    inst->editlevel = 0;
    inst->do_free = FALSE;
    inst->dirty = FALSE;
    qof_entity_release (&inst->entity);
}

void qof_instance_set_dirty

(

QofInstance *

inst

)

Set the dirty flag.

Sets this instance AND the collection as dirty.

Definition at line 146 of file qofinstance.c.

{
    QofCollection *coll;

    inst->dirty = TRUE;
    coll = inst->entity.collection;
    qof_collection_mark_dirty (coll);
}

gint qof_instance_version_cmp	(	QofInstance *	left,
		QofInstance *	right
	)

Compare two instances, based on thier last update times. Returns a negative, zero or positive value, respectively, if 'left' is earlier, same as or later than 'right'. Accepts NULL pointers, NULL's are by definition earlier than any value.

Definition at line 116 of file qofinstance.c.

{
    if (!left && !right)
        return 0;
    if (!left)
        return -1;
    if (!right)
        return +1;
    return qof_time_cmp (left->update_time, right->update_time);
}