QOF: Book: The QOF Data Set.

QOF 0.7.5

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Files | Macros | Typedefs | Functions
Book: The QOF Data Set.
Query Object Framework

## Files
file | qofbook.h
| Encapsulate all the information about a dataset.

## Macros
#define | QOF_BOOK_LOOKUP_ENTITY(book, guid, e_type, c_type)
| Encapsulates all the information about a dataset manipulated by QOF. This is the top-most structure used for anchoring data. More...
#define | qof_book_get_slots(book) qof_instance_get_slots(QOF_INSTANCE(book))

## Typedefs
typedef struct _QofBook | QofBook
| QofBook reference.
typedef GList | QofBookList
typedef void(* | QofBookFinalCB) (QofBook *, gpointer key, gpointer user_data)
typedef void(* | QofCollectionForeachCB) (QofCollection *, gpointer user_data)

## Functions
gboolean | qof_book_register (void)
QofBook * | qof_book_new (void)
void | qof_book_destroy (QofBook *book)
void | qof_book_mark_closed (QofBook *book)
QofCollection * | qof_book_get_collection (QofBook *, QofIdType)
void | qof_book_foreach_collection (QofBook *, QofCollectionForeachCB, gpointer)
void | qof_book_set_data (QofBook *book, const gchar *key, gpointer data)
void | qof_book_set_data_fin (QofBook *book, const gchar *key, gpointer data, QofBookFinalCB)
gpointer | qof_book_get_data (QofBook *book, const gchar *key)
gboolean | qof_book_shutting_down (QofBook *book)
gboolean | qof_book_not_saved (QofBook *book)
void | qof_book_mark_saved (QofBook *book)
void | qof_book_kvp_changed (QofBook *book)
gboolean | qof_book_equal (QofBook *book_1, QofBook *book_2)
gint64 | qof_book_get_counter (QofBook *book, const gchar *counter_name)

## Detailed Description

A QOF Book is a dataset. It provides a single handle through which all the various collections of entities can be found. In particular, given only the type of the entity, the collection can be found.

Books also provide the 'natural' place to working with a storage backend, as a book can encapsulate everything held in storage.

## Macro Definition Documentation

#define qof_book_get_slots | ( |  | book | ) | qof_instance_get_slots(QOF_INSTANCE(book))

Return The kvp data for the book. Note that the book KVP data is persistent, and is stored/retrieved from the file/database. Thus, the book KVP is the correct place to store data that needs to be persistent accross sessions (or shared between multiple users). To store application runtime data, use qof_book_set_data() instead.

Definition at line 113 of file qofbook.h.

#define QOF_BOOK_LOOKUP_ENTITY | ( |  | book,
|  |  | guid,
|  |  | e_type,
|  |  | c_type
| ) |  |

Value:
({ \
QofEntity *val = NULL; \
if (guid && book) { \
QofCollection *col; \
col = qof_book_get_collection (book, e_type); \
val = qof_collection_lookup_entity (col, guid); \
} \
(c_type *) val; \
})
qof_book_get_collection
QofCollection * qof_book_get_collection(QofBook *, QofIdType)
Definition: qofbook.c:220
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
QofEntity
struct QofEntity_s QofEntity
Definition: qofid.h:129

Encapsulates all the information about a dataset manipulated by QOF. This is the top-most structure used for anchoring data.

Lookup an entity by guid, returning pointer to the entity

Definition at line 50 of file qofbook.h.

## Typedef Documentation

typedef GList QofBookList

GList of QofBook

Definition at line 64 of file qofbook.h.

typedef void(* QofCollectionForeachCB) (QofCollection *, gpointer user_data)

Invoke the indicated callback on each collection in the book.

Definition at line 102 of file qofbook.h.

## Function Documentation

void qof_book_destroy | ( | QofBook * | book | ) |

End any editing sessions associated with book, and free all memory associated with it.

Definition at line 99 of file qofbook.c.

100 {
101 if (!book)
102 return;
103 ENTER ("book=%p", book);
104 book->shutting_down = TRUE;
105 qof_event_force (&book->inst.entity, QOF_EVENT_DESTROY, NULL);
106 /* Call the list of finalizers, let them do their thing.
107 * Do this before tearing into the rest of the book.
108 */
109 g_hash_table_foreach (book->data_table_finalizers, book_final, book);
110 qof_object_book_end (book);
111 g_hash_table_destroy (book->data_table_finalizers);
112 book->data_table_finalizers = NULL;
113 g_hash_table_destroy (book->data_tables);
114 book->data_tables = NULL;
115 qof_instance_release (&book->inst);
116 g_hash_table_destroy (book->hash_of_collections);
117 book->hash_of_collections = NULL;
118 g_free (book);
119 LEAVE ("book=%p", book);
120 }
_QofBook::inst
QofInstance inst
Definition: qofbook-p.h:51
_QofBook::hash_of_collections
GHashTable * hash_of_collections
Definition: qofbook-p.h:57
QOF_EVENT_DESTROY
#define QOF_EVENT_DESTROY
Definition: qofevent.h:81
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
_QofBook::data_table_finalizers
GHashTable * data_table_finalizers
Definition: qofbook-p.h:64
QofInstance_s::entity
QofEntity entity
Definition: qofinstance-p.h:38
qof_instance_release
void qof_instance_release(QofInstance *inst)
Definition: qofinstance.c:69
_QofBook::data_tables
GHashTable * data_tables
Definition: qofbook-p.h:61
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217
_QofBook::shutting_down
gboolean shutting_down
Definition: qofbook-p.h:77

gboolean qof_book_equal | ( | QofBook * | book_1,
|  | QofBook * | book_2
| ) |  |

The qof_book_equal() method returns TRUE if books are equal. XXX this routine is broken, and does not currently compare data.

Definition at line 125 of file qofbook.c.

126 {
127 if (book_1 == book_2)
128 return TRUE;
129 if (!book_1 || !book_2)
130 return FALSE;
131 return TRUE;
132 }

QofCollection* qof_book_get_collection | ( | QofBook * | ,
|  | QofIdType |
| ) |  |

Return The table of entities of the given type.

When an object's constructor calls qof_instance_init(), a reference to the object is stored in the book. The book stores all the references to initialized instances, sorted by type. This function returns a collection of the references for the specified type.

If the collection doesn't yet exist for the indicated type, it is created. Thus, this routine is gaurenteed to return a non-NULL value. (Unless the system malloc failed (out of memory) in which case what happens??).

Definition at line 220 of file qofbook.c.

221 {
222 QofCollection *col;
223
224 if (!book || !entity_type)
225 return NULL;
226 col = g_hash_table_lookup (book->hash_of_collections, entity_type);
227 if (!col)
228 {
229 col = qof_collection_new (entity_type);
230 g_hash_table_insert (book->hash_of_collections,
231 qof_util_string_cache_insert ((gpointer) entity_type), col);
232 }
233 return col;
234 }
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138
qof_util_string_cache_insert
gpointer qof_util_string_cache_insert(gconstpointer key)
Definition: qofutil.c:439
qof_collection_new
QofCollection * qof_collection_new(QofIdType type)
Definition: qofid.c:150

gint64 qof_book_get_counter | ( | QofBook * | book,
|  | const gchar * | counter_name
| ) |  |

This will 'get and increment' the named counter for this book. The return value is -1 on error or the incremented counter.

Definition at line 325 of file qofbook.c.

326 {
327 QofBackend *be;
328 KvpFrame *kvp;
329 KvpValue *value;
330 gint64 counter;
331
332 if (!book)
333 {
334 PWARN ("No book!!!");
335 return -1;
336 }
337 if (!counter_name || *counter_name == '\0')
338 {
339 PWARN ("Invalid counter name.");
340 return -1;
341 }
342 /* If we've got a backend with a counter method, call it */
343 be = book->backend;
344 if (be && be->counter)
345 return ((be->counter) (be, counter_name));
346 /* If not, then use the KVP in the book */
347 kvp = qof_book_get_slots (book);
348 if (!kvp)
349 {
350 PWARN ("Book has no KVP_Frame");
351 return -1;
352 }
353 value = kvp_frame_get_slot_path (kvp, "counters", counter_name, NULL);
354 if (value)
355 {
356 /* found it */
357 counter = kvp_value_get_gint64 (value);
358 }
359 else
360 {
361 /* New counter */
362 counter = 0;
363 }
364 /* Counter is now valid; increment it */
365 counter++;
366 /* Save off the new counter */
367 value = kvp_value_new_gint64 (counter);
368 kvp_frame_set_slot_path (kvp, value, "counters", counter_name, NULL);
369 kvp_value_delete (value);
370 /* and return the value */
371 return counter;
372 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
kvp_frame_set_slot_path
void kvp_frame_set_slot_path(KvpFrame *frame, const KvpValue *new_value, const gchar *first_key,...)
Definition: kvpframe.c:726
kvp_value_get_gint64
gint64 kvp_value_get_gint64(const KvpValue *value)
Definition: kvpframe.c:1402
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
_QofBook::backend
QofBackend * backend
Definition: qofbook-p.h:87
kvp_frame_get_slot_path
KvpValue * kvp_frame_get_slot_path(KvpFrame *frame, const gchar *first_key,...)
Definition: kvpframe.c:1060
PWARN
#define PWARN(format, args...)
Definition: qoflog.h:191
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361
qof_book_get_slots
#define qof_book_get_slots(book)
Definition: qofbook.h:113
QofBackend_s
Definition: qofbackend-p.h:283

gpointer qof_book_get_data | ( | QofBook * | book,
|  | const gchar * | key
| ) |  |

Retrieves arbitrary pointers to structs stored by qof_book_set_data.

Definition at line 212 of file qofbook.c.

213 {
214 if (!book || !key)
215 return NULL;
216 return g_hash_table_lookup (book->data_tables, (gpointer) key);
217 }
_QofBook::data_tables
GHashTable * data_tables
Definition: qofbook-p.h:61

void qof_book_kvp_changed | ( | QofBook * | book | ) |

Call this function when you change the book kvp, to make sure the book is marked 'dirty'.

Definition at line 180 of file qofbook.c.

181 {
182 if (!book)
183 return;
184 book->inst.dirty = TRUE;
185 }
_QofBook::inst
QofInstance inst
Definition: qofbook-p.h:51

void qof_book_mark_closed | ( | QofBook * | book | ) |

Close a book to editing.

It is up to the application to check this flag, and once marked closed, books cannnot be marked as open.

Definition at line 265 of file qofbook.c.

266 {
267 if (!book)
268 {
269 return;
270 }
271 book->book_open = 'n';
272 }
_QofBook::book_open
gchar book_open
Definition: qofbook-p.h:70

void qof_book_mark_saved | ( | QofBook * | book | ) |

The qof_book_mark_saved() routine marks the book as having been saved (to a file, to a database). Used by backends to mark the notsaved flag as FALSE just after loading. Can also be used by the frontend when the used has said to abandon any changes.

Definition at line 144 of file qofbook.c.

145 {
146 if (!book)
147 return;
148
149 book->inst.dirty = FALSE;
150 qof_object_mark_clean (book);
151 }
_QofBook::inst
QofInstance inst
Definition: qofbook-p.h:51

QofBook* qof_book_new | ( | void |  | ) |

Allocate, initialise and return a new QofBook. Books contain references to all of the top-level object containers.

Definition at line 75 of file qofbook.c.

76 {
77 QofBook *book;
78
79 ENTER (" ");
80 book = g_new0 (QofBook, 1);
81 qof_book_init (book);
82 qof_object_book_begin (book);
83 qof_event_gen (&book->inst.entity, QOF_EVENT_CREATE, NULL);
84 LEAVE ("book=%p", book);
85 return book;
86 }
_QofBook::inst
QofInstance inst
Definition: qofbook-p.h:51
qof_object_book_begin
void qof_object_book_begin(QofBook *book)
Definition: qofobject.c:60
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
qof_event_gen
void qof_event_gen(QofEntity *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.c:292
QOF_EVENT_CREATE
#define QOF_EVENT_CREATE
Definition: qofevent.h:71
QofInstance_s::entity
QofEntity entity
Definition: qofinstance-p.h:38
_QofBook
Definition: qofbook-p.h:48
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

gboolean qof_book_not_saved | ( | QofBook * | book | ) |

qof_book_not_saved() will return TRUE if any data in the book hasn't been saved to long-term storage. (Actually, that's not quite true. The book doesn't know anything about saving. Its just that whenever data is modified, the 'dirty' flag is set. This routine returns the value of the 'dirty' flag. Its up to the backend to periodically reset this flag, when it actually does save the data.)

Definition at line 135 of file qofbook.c.

136 {
137 if (!book)
138 return FALSE;
139
140 return (book->inst.dirty || qof_object_is_dirty (book));
141 }
_QofBook::inst
QofInstance inst
Definition: qofbook-p.h:51

gboolean qof_book_register | ( | void |  | ) |

Register the book object with the QOF object system.

Register books with the framework

Definition at line 376 of file qofbook.c.

377 {
378 static QofParam params[] = {
379 {QOF_PARAM_GUID, QOF_TYPE_GUID,
380 (QofAccessFunc) qof_entity_get_guid,
381 NULL, NULL},
382 {QOF_PARAM_KVP, QOF_TYPE_KVP,
383 (QofAccessFunc) qof_instance_get_slots,
384 NULL, NULL},
385 {NULL, NULL, NULL, NULL, NULL},
386 };
387
388 qof_class_register (QOF_ID_BOOK, NULL, params);
389
390 return TRUE;
391 }
_QofParam
Definition: qofclass.h:195
qof_class_register
void qof_class_register(QofIdTypeConst obj_name, QofSortFunc default_sort_function, const QofParam *params)
registers a new object class with the Qof subsystem.
Definition: qofclass.c:93
qof_instance_get_slots
KvpFrame * qof_instance_get_slots(QofInstance *inst)
Definition: qofinstance.c:95
QofAccessFunc
gpointer(* QofAccessFunc)(gpointer object, const QofParam *param)
Definition: qofclass.h:169
QOF_PARAM_KVP
#define QOF_PARAM_KVP
Definition: qofquery.h:108
qof_entity_get_guid
const GUID * qof_entity_get_guid(QofEntity *ent)
Definition: qofid.c:105

void qof_book_set_data | ( | QofBook * | book,
|  | const gchar * | key,
|  | gpointer | data
| ) |  |

The qof_book_set_data() allows arbitrary pointers to structs to be stored in QofBook. This is the "preferred" method for extending QofBook to hold new data types. This is also the ideal location to store other arbitrary runtime data that the application may need.

The book data differs from the book KVP in that the contents of the book KVP are persistent (are saved and restored to file or database), whereas the data pointers exist only at runtime.

Definition at line 191 of file qofbook.c.

192 {
193 if (!book || !key)
194 return;
195 g_hash_table_insert (book->data_tables, (gpointer) key, data);
196 }
_QofBook::data_tables
GHashTable * data_tables
Definition: qofbook-p.h:61

void qof_book_set_data_fin | ( | QofBook * | book,
|  | const gchar * | key,
|  | gpointer | data,
|  | QofBookFinalCB |
| ) |  |

Same as qof_book_set_data(), except that the callback will be called when the book is destroyed. The argument to the callback will be the book followed by the data pointer.

Definition at line 199 of file qofbook.c.

201 {
202 if (!book || !key)
203 return;
204 g_hash_table_insert (book->data_tables, (gpointer) key, data);
205
206 if (!cb)
207 return;
208 g_hash_table_insert (book->data_table_finalizers, (gpointer) key, cb);
209 }
_QofBook::data_table_finalizers
GHashTable * data_table_finalizers
Definition: qofbook-p.h:64
_QofBook::data_tables
GHashTable * data_tables
Definition: qofbook-p.h:61

gboolean qof_book_shutting_down | ( | QofBook * | book | ) |

Is the book shutting down?

Definition at line 162 of file qofbook.c.

163 {
164 if (!book)
165 return FALSE;
166 return book->shutting_down;
167 }
_QofBook::shutting_down
gboolean shutting_down
Definition: qofbook-p.h:77