Instance
[Entity: Types, Identity and Instance Framework]

---

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.

Files
file	qofinstance.h
	Object instance holds common fields that most gnucash objects use.
Defines
#define	QOF_INSTANCE(object)   ((QofInstance *)(object))
Typedefs
typedef 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 *)
Timespec	qof_instance_get_last_update (QofInstance *inst)
int	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)

---

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 200 of file qofinstance.c. { time_t now; /* Books must differ for a gemini to be meaningful */ if (!from || !to || (from->book == to->book)) return; now = time(0); /* Make a note of where the copy came from */ gnc_kvp_bag_add (to->kvp_data, "gemini", now, "inst_guid", &from->entity.guid, "book_guid", &from->book->inst.entity.guid, NULL); gnc_kvp_bag_add (from->kvp_data, "gemini", now, "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 89 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 82 of file qofinstance.c. { if (!inst) return NULL; return &inst->entity.guid; }

Timespec qof_instance_get_last_update (  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) { Timespec ts = {0,-1}; return ts; } return inst->last_update; }

KvpFrame* qof_instance_get_slots (  QofInstance *   )

Return the pointer to the kvp_data Definition at line 96 of file qofinstance.c. { if (!inst) return NULL; return inst->kvp_data; }

void qof_instance_init (  QofInstance *  , QofIdType  , QofBook *  )

Initialise the memory associated with an instance Definition at line 55 of file qofinstance.c. { QofCollection *col; inst->book = book; inst->kvp_data = kvp_frame_new(); inst->last_update.tv_sec = 0; inst->last_update.tv_nsec = -1; 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 127 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 223 of file qofinstance.c. { QofCollection *col; KvpFrame *fr; GUID * twin_guid; QofInstance * twin; if (!src || !target_book) return NULL; ENTER (" "); fr = gnc_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 72 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 139 of file qofinstance.c. { QofCollection *coll; inst->dirty = TRUE; coll = inst->entity.collection; qof_collection_mark_dirty(coll); }

int 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 114 of file qofinstance.c. { if (!left && !right) return 0; if (!left) return -1; if (!right) return +1; if (left->last_update.tv_sec < right->last_update.tv_sec) return -1; if (left->last_update.tv_sec > right->last_update.tv_sec) return +1; if (left->last_update.tv_nsec < right->last_update.tv_nsec) return -1; if (left->last_update.tv_nsec > right->last_update.tv_nsec) return +1; return 0; }

---