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)
QofBookqof_instance_get_book (QofInstance *)
const GUIDqof_instance_get_guid (QofInstance *)
KvpFrameqof_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)
QofInstanceqof_instance_create (QofIdType type, QofBook *book)
void qof_instance_gemini (QofInstance *to, QofInstance *from)
QofInstanceqof_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 198 of file qofinstance.c.

00199 {
00200   time_t now;
00201 
00202   /* Books must differ for a gemini to be meaningful */
00203   if (!from || !to || (from->book == to->book)) return;
00204 
00205   now = time(0);
00206 
00207   /* Make a note of where the copy came from */
00208   gnc_kvp_bag_add (to->kvp_data, "gemini", now,
00209                                   "inst_guid", &from->entity.guid,
00210                                   "book_guid", &from->book->inst.entity.guid,
00211                                   NULL);
00212   gnc_kvp_bag_add (from->kvp_data, "gemini", now,
00213                                   "inst_guid", &to->entity.guid,
00214                                   "book_guid", &to->book->inst.entity.guid,
00215                                   NULL);
00216 
00217   to->dirty = TRUE;
00218 }

QofBook* qof_instance_get_book QofInstance  ) 
 

Return the book pointer

Definition at line 87 of file qofinstance.c.

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

const GUID* qof_instance_get_guid QofInstance  ) 
 

Return the GUID of this instance

Definition at line 80 of file qofinstance.c.

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

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 101 of file qofinstance.c.

00102 {
00103         if (!inst)
00104         {
00105                 Timespec ts = {0,-1};
00106                 return ts;
00107         }
00108         return inst->last_update;
00109 }

KvpFrame* qof_instance_get_slots QofInstance  ) 
 

Return the pointer to the kvp_data

Definition at line 94 of file qofinstance.c.

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

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->last_update.tv_sec = 0;
00060         inst->last_update.tv_nsec = -1;
00061         inst->editlevel = 0;
00062         inst->do_free = FALSE;
00063         inst->dirty = FALSE;
00064 
00065         col = qof_book_get_collection (book, type);
00066         qof_entity_init (&inst->entity, type, col);
00067 }

gboolean qof_instance_is_dirty QofInstance  ) 
 

Return value of is_dirty flag

Definition at line 125 of file qofinstance.c.

00126 {
00127         QofCollection *coll;
00128 
00129         if (!inst) { return FALSE; }
00130         coll = inst->entity.collection;
00131         if(qof_collection_is_dirty(coll)) { return inst->dirty; }
00132         inst->dirty = FALSE;
00133         return FALSE;
00134 }

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 221 of file qofinstance.c.

00222 {
00223         QofCollection *col;
00224         KvpFrame *fr;
00225         GUID * twin_guid;
00226         QofInstance * twin;
00227 
00228         if (!src || !target_book) return NULL;
00229         ENTER (" ");
00230 
00231         fr = gnc_kvp_bag_find_by_guid (src->kvp_data, "gemini",
00232                                      "book_guid", &target_book->inst.entity.guid);
00233 
00234         twin_guid = kvp_frame_get_guid (fr, "inst_guid");
00235 
00236         col = qof_book_get_collection (target_book, src->entity.e_type);
00237         twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);
00238 
00239         LEAVE (" found twin=%p", twin);
00240         return twin;
00241 }

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 70 of file qofinstance.c.

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

void qof_instance_set_dirty QofInstance inst  ) 
 

Set the dirty flag.

Sets this instance AND the collection as dirty.

Definition at line 137 of file qofinstance.c.

00138 {
00139         QofCollection *coll;
00140 
00141         inst->dirty = TRUE;
00142         coll = inst->entity.collection;
00143         qof_collection_mark_dirty(coll);
00144 }

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 112 of file qofinstance.c.

00113 {
00114         if (!left && !right) return 0;
00115         if (!left) return -1;
00116         if (!right) return +1;
00117         if (left->last_update.tv_sec < right->last_update.tv_sec) return -1;
00118         if (left->last_update.tv_sec > right->last_update.tv_sec) return +1;
00119         if (left->last_update.tv_nsec < right->last_update.tv_nsec) return -1;
00120         if (left->last_update.tv_nsec > right->last_update.tv_nsec) return +1;
00121         return 0;
00122 }


Generated on Fri May 12 17:57:22 2006 for QOF by  doxygen 1.4.4