QOF  0.8.7
Files | Macros | Typedefs | Functions
Book: The QOF Data Set.

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)
 
QofBookqof_book_new (void)
 
void qof_book_destroy (QofBook *book)
 
void qof_book_mark_closed (QofBook *book)
 
QofCollectionqof_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; \
})
QofCollection * qof_book_get_collection(QofBook *, QofIdType)
Definition: qofbook.c:220
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
Definition: qofid.c:292

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 }
QofInstance inst
Definition: qofbook-p.h:51
GHashTable * hash_of_collections
Definition: qofbook-p.h:57
#define QOF_EVENT_DESTROY
Definition: qofevent.h:81
#define LEAVE(format, args...)
Definition: qoflog.h:227
GHashTable * data_table_finalizers
Definition: qofbook-p.h:64
QofEntity entity
Definition: qofinstance-p.h:39
void qof_instance_release(QofInstance *inst)
Definition: qofinstance.c:69
GHashTable * data_tables
Definition: qofbook-p.h:61
#define ENTER(format, args...)
Definition: qoflog.h:217
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 }
struct QofCollection_s QofCollection
Definition: qofid.h:138
gpointer qof_util_string_cache_insert(gconstpointer key)
Definition: qofutil.c:456
QofCollection * qof_collection_new(QofIdType type)
Definition: qofid.c:121
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 }
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
void kvp_frame_set_slot_path(KvpFrame *frame, const KvpValue *new_value, const gchar *first_key,...)
Definition: kvpframe.c:723
gint64 kvp_value_get_gint64(const KvpValue *value)
Definition: kvpframe.c:1399
struct _KvpValue KvpValue
Definition: kvpframe.h:78
QofBackend * backend
Definition: qofbook-p.h:87
KvpValue * kvp_frame_get_slot_path(KvpFrame *frame, const gchar *first_key,...)
Definition: kvpframe.c:1057
#define PWARN(format, args...)
Definition: qoflog.h:191
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1358
#define qof_book_get_slots(book)
Definition: qofbook.h:113
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 }
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 }
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 }
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 }
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 }
QofInstance inst
Definition: qofbook-p.h:51
void qof_object_book_begin(QofBook *book)
Definition: qofobject.c:60
#define LEAVE(format, args...)
Definition: qoflog.h:227
void qof_event_gen(QofEntity *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.c:235
#define QOF_EVENT_CREATE
Definition: qofevent.h:71
QofEntity entity
Definition: qofinstance-p.h:39
#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 }
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,
381  NULL, NULL},
382  {QOF_PARAM_KVP, QOF_TYPE_KVP,
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 }
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:94
KvpFrame * qof_instance_get_slots(QofInstance *inst)
Definition: qofinstance.c:95
gpointer(* QofAccessFunc)(gpointer object, const QofParam *param)
Definition: qofclass.h:144
#define QOF_PARAM_KVP
Definition: qofquery.h:108
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 }
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 }
GHashTable * data_table_finalizers
Definition: qofbook-p.h:64
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 }
gboolean shutting_down
Definition: qofbook-p.h:77