QOF  0.7.5

Files

file  qofinstance.h
 Object instance holds common fields that most QofObjects use.
 

Macros

#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)
 
QofBookqof_instance_get_book (QofInstance *)
 
const GUIDqof_instance_get_guid (QofInstance *)
 
KvpFrameqof_instance_get_slots (QofInstance *)
 
QofTimeqof_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. More...
 
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)
 

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.

213 {
214  QofTime *qt;
215 
216  /* Books must differ for a gemini to be meaningful */
217  if (!from || !to || (from->book == to->book))
218  return;
219 
220  qt = qof_time_get_current ();
221 
222  /* Make a note of where the copy came from */
223  qof_kvp_bag_add (to->kvp_data, "gemini", qt,
224  "inst_guid", &from->entity.guid,
225  "book_guid", &from->book->inst.entity.guid, NULL);
226  qof_kvp_bag_add (from->kvp_data, "gemini", qt,
227  "inst_guid", &to->entity.guid,
228  "book_guid", &to->book->inst.entity.guid, NULL);
229 
230  to->dirty = TRUE;
231 }
QofBook* qof_instance_get_book ( QofInstance )

Return the book pointer

Definition at line 87 of file qofinstance.c.

88 {
89  if (!inst)
90  return NULL;
91  return inst->book;
92 }
const GUID* qof_instance_get_guid ( QofInstance )

Return the GUID of this instance

Definition at line 79 of file qofinstance.c.

80 {
81  if (!inst)
82  return NULL;
83  return &inst->entity.guid;
84 }
KvpFrame* qof_instance_get_slots ( QofInstance )

Return the pointer to the kvp_data

Definition at line 95 of file qofinstance.c.

96 {
97  if (!inst)
98  return NULL;
99  return inst->kvp_data;
100 }
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.

104 {
105  if (!inst)
106  {
107  QofTime *time;
108 
109  time = qof_time_get_current ();
110  return time;
111  }
112  return inst->update_time;
113 }
void qof_instance_init ( QofInstance ,
QofIdType  ,
QofBook  
)

Initialise the memory associated with an instance

Definition at line 53 of file qofinstance.c.

54 {
55  QofCollection *col;
56 
57  inst->book = book;
58  inst->kvp_data = kvp_frame_new ();
59  inst->update_time = qof_time_get_current ();
60  inst->editlevel = 0;
61  inst->do_free = FALSE;
62  inst->dirty = FALSE;
63 
64  col = qof_book_get_collection (book, type);
65  qof_entity_init (&inst->entity, type, col);
66 }
gboolean qof_instance_is_dirty ( QofInstance )

Return value of is_dirty flag

Definition at line 128 of file qofinstance.c.

129 {
130  QofCollection *coll;
131 
132  if (!inst)
133  {
134  return FALSE;
135  }
136  coll = inst->entity.collection;
137  if (qof_collection_is_dirty (coll))
138  {
139  return inst->dirty;
140  }
141  inst->dirty = FALSE;
142  return FALSE;
143 }
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.

235 {
236  QofCollection *col;
237  KvpFrame *fr;
238  GUID *twin_guid;
239  QofInstance *twin;
240 
241  if (!src || !target_book)
242  return NULL;
243  ENTER (" ");
244 
245  fr = qof_kvp_bag_find_by_guid (src->kvp_data, "gemini",
246  "book_guid", &target_book->inst.entity.guid);
247 
248  twin_guid = kvp_frame_get_guid (fr, "inst_guid");
249 
250  col = qof_book_get_collection (target_book, src->entity.e_type);
251  twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);
252 
253  LEAVE (" found twin=%p", twin);
254  return twin;
255 }
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.

70 {
71  kvp_frame_delete (inst->kvp_data);
72  inst->editlevel = 0;
73  inst->do_free = FALSE;
74  inst->dirty = FALSE;
75  qof_entity_release (&inst->entity);
76 }
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.

147 {
148  QofCollection *coll;
149 
150  inst->dirty = TRUE;
151  coll = inst->entity.collection;
152  qof_collection_mark_dirty (coll);
153 }
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.

117 {
118  if (!left && !right)
119  return 0;
120  if (!left)
121  return -1;
122  if (!right)
123  return +1;
124  return qof_time_cmp (left->update_time, right->update_time);
125 }