QOF: Instance

QOF 0.7.5

Files | Macros | Typedefs | Functions
Instance
Query Object Framework » Class: Getting and setting entity values.

## 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)
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. More...
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

## ◆ qof_instance_gemini()

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::inst
QofInstance inst
Definition: qofbook-p.h:51
QofInstance_s::kvp_data
KvpFrame * kvp_data
Definition: qofinstance-p.h:47
qof_time_get_current
QofTime * qof_time_get_current(void)
Get the current QofTime.
Definition: qoftime.c:362
qof_kvp_bag_add
KvpFrame * qof_kvp_bag_add(KvpFrame *kvp_root, const gchar *path, QofTime *qt, const gchar *first_name,...)
Definition: kvputil.c:67
QofInstance_s::entity
QofEntity entity
Definition: qofinstance-p.h:38
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120
QofInstance_s::book
QofBook * book
Definition: qofinstance-p.h:41

## ◆ qof_instance_get_book()

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 }

## ◆ qof_instance_get_guid()

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 }

## ◆ qof_instance_get_slots()

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 }

## ◆ qof_instance_get_update_time()

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 }
qof_time_get_current
QofTime * qof_time_get_current(void)
Get the current QofTime.
Definition: qoftime.c:362
QofInstance_s::update_time
QofTime * update_time
Definition: qofinstance-p.h:61
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_instance_init()

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 }
qof_book_get_collection
QofCollection * qof_book_get_collection(QofBook *book, QofIdType entity_type)
Definition: qofbook.c:220
qof_time_get_current
QofTime * qof_time_get_current(void)
Get the current QofTime.
Definition: qoftime.c:362
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138
kvp_frame_new
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:100
qof_entity_init
void qof_entity_init(QofEntity *ent, QofIdType type, QofCollection *tab)
Definition: qofid.c:49

## ◆ qof_instance_is_dirty()

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 }
qof_collection_is_dirty
gboolean qof_collection_is_dirty(QofCollection *col)
Definition: qofid.c:362
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138

## ◆ qof_instance_lookup_twin()

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 }
QofInstance_s
Definition: qofinstance-p.h:35
qof_book_get_collection
QofCollection * qof_book_get_collection(QofBook *book, QofIdType entity_type)
Definition: qofbook.c:220
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
QofInstance_s::kvp_data
KvpFrame * kvp_data
Definition: qofinstance-p.h:47
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138
qof_collection_lookup_entity
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
Definition: qofid.c:321
QofInstance_s::entity
QofEntity entity
Definition: qofinstance-p.h:38
_GUID
Definition: guid.h:53
qof_kvp_bag_find_by_guid
KvpFrame * qof_kvp_bag_find_by_guid(KvpFrame *root, const gchar *path, const gchar *guid_name, GUID *desired_guid)
Definition: kvputil.c:89
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qof_instance_release()

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 }
QofInstance_s::kvp_data
KvpFrame * kvp_data
Definition: qofinstance-p.h:47
kvp_frame_delete
void kvp_frame_delete(KvpFrame *frame)
Definition: kvpframe.c:118
qof_entity_release
void qof_entity_release(QofEntity *ent)
Definition: qofid.c:79
QofInstance_s::entity
QofEntity entity
Definition: qofinstance-p.h:38

## ◆ qof_instance_set_dirty()

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 }
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138
QofInstance_s::entity
QofEntity entity
Definition: qofinstance-p.h:38

## ◆ qof_instance_version_cmp()

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 }
qof_time_cmp
gint qof_time_cmp(const QofTime *ta, const QofTime *tb)
Definition: qoftime.c:165
QofInstance_s::update_time
QofTime * update_time
Definition: qofinstance-p.h:61