QOF: Instance

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.

00213 {
00214     QofTime *qt;
00215 
00216     /* Books must differ for a gemini to be meaningful */
00217     if (!from || !to || (from->book == to->book))
00218         return;
00219 
00220     qt = qof_time_get_current ();
00221 
00222     /* Make a note of where the copy came from */
00223     qof_kvp_bag_add (to->kvp_data, "gemini", qt,
00224         "inst_guid", &from->entity.guid,
00225         "book_guid", &from->book->inst.entity.guid, NULL);
00226     qof_kvp_bag_add (from->kvp_data, "gemini", qt,
00227         "inst_guid", &to->entity.guid,
00228         "book_guid", &to->book->inst.entity.guid, NULL);
00229 
00230     to->dirty = TRUE;
00231 }

QofBook* qof_instance_get_book ( QofInstance * )

Return the book pointer

Definition at line 87 of file qofinstance.c.

00088 {
00089     if (!inst)
00090         return NULL;
00091     return inst->book;
00092 }

const GUID* qof_instance_get_guid ( QofInstance * )

Return the GUID of this instance

Definition at line 79 of file qofinstance.c.

00080 {
00081     if (!inst)
00082         return NULL;
00083     return &inst->entity.guid;
00084 }

KvpFrame* qof_instance_get_slots ( QofInstance * )

Return the pointer to the kvp_data

Definition at line 95 of file qofinstance.c.

00096 {
00097     if (!inst)
00098         return NULL;
00099     return inst->kvp_data;
00100 }

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.

00104 {
00105     if (!inst)
00106     {
00107         QofTime *time;
00108 
00109         time = qof_time_get_current ();
00110         return time;
00111     }
00112     return inst->update_time;
00113 }

void qof_instance_init	(	QofInstance *	,
		QofIdType	,
		QofBook *
	)

Initialise the memory associated with an instance

Definition at line 53 of file qofinstance.c.

00054 {
00055     QofCollection *col;
00056 
00057     inst->book = book;
00058     inst->kvp_data = kvp_frame_new ();
00059     inst->update_time = qof_time_get_current ();
00060     inst->editlevel = 0;
00061     inst->do_free = FALSE;
00062     inst->dirty = FALSE;
00063 
00064     col = qof_book_get_collection (book, type);
00065     qof_entity_init (&inst->entity, type, col);
00066 }

gboolean qof_instance_is_dirty ( QofInstance * )

Return value of is_dirty flag

Definition at line 128 of file qofinstance.c.

00129 {
00130     QofCollection *coll;
00131 
00132     if (!inst)
00133     {
00134         return FALSE;
00135     }
00136     coll = inst->entity.collection;
00137     if (qof_collection_is_dirty (coll))
00138     {
00139         return inst->dirty;
00140     }
00141     inst->dirty = FALSE;
00142     return FALSE;
00143 }

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.

00235 {
00236     QofCollection *col;
00237     KvpFrame *fr;
00238     GUID *twin_guid;
00239     QofInstance *twin;
00240 
00241     if (!src || !target_book)
00242         return NULL;
00243     ENTER (" ");
00244 
00245     fr = qof_kvp_bag_find_by_guid (src->kvp_data, "gemini",
00246         "book_guid", &target_book->inst.entity.guid);
00247 
00248     twin_guid = kvp_frame_get_guid (fr, "inst_guid");
00249 
00250     col = qof_book_get_collection (target_book, src->entity.e_type);
00251     twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);
00252 
00253     LEAVE (" found twin=%p", twin);
00254     return twin;
00255 }

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.

00070 {
00071     kvp_frame_delete (inst->kvp_data);
00072     inst->editlevel = 0;
00073     inst->do_free = FALSE;
00074     inst->dirty = FALSE;
00075     qof_entity_release (&inst->entity);
00076 }

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.

00147 {
00148     QofCollection *coll;
00149 
00150     inst->dirty = TRUE;
00151     coll = inst->entity.collection;
00152     qof_collection_mark_dirty (coll);
00153 }

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.

00117 {
00118     if (!left && !right)
00119         return 0;
00120     if (!left)
00121         return -1;
00122     if (!right)
00123         return +1;
00124     return qof_time_cmp (left->update_time, right->update_time);
00125 }


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)

Instance
[Class: Getting and setting entity values.]

Detailed Description

Files

Defines

Typedefs

Functions

Function Documentation