Book: The QOF Data Set.
[Query Object Framework]

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.


Files

file  qofbook.h
 Encapsulate all the information about a dataset.

Defines

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

Define 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;                                           \
})
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.

00100 {
00101     if (!book)
00102         return;
00103     ENTER ("book=%p", book);
00104     book->shutting_down = TRUE;
00105     qof_event_force (&book->inst.entity, QOF_EVENT_DESTROY, NULL);
00106     /* Call the list of finalizers, let them do their thing. 
00107      * Do this before tearing into the rest of the book.
00108      */
00109     g_hash_table_foreach (book->data_table_finalizers, book_final, book);
00110     qof_object_book_end (book);
00111     g_hash_table_destroy (book->data_table_finalizers);
00112     book->data_table_finalizers = NULL;
00113     g_hash_table_destroy (book->data_tables);
00114     book->data_tables = NULL;
00115     qof_instance_release (&book->inst);
00116     g_hash_table_destroy (book->hash_of_collections);
00117     book->hash_of_collections = NULL;
00118     g_free (book);
00119     LEAVE ("book=%p", book);
00120 }

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.

00126 {
00127     if (book_1 == book_2)
00128         return TRUE;
00129     if (!book_1 || !book_2)
00130         return FALSE;
00131     return TRUE;
00132 }

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.

00221 {
00222     QofCollection *col;
00223 
00224     if (!book || !entity_type)
00225         return NULL;
00226     col = g_hash_table_lookup (book->hash_of_collections, entity_type);
00227     if (!col)
00228     {
00229         col = qof_collection_new (entity_type);
00230         g_hash_table_insert (book->hash_of_collections,
00231             qof_util_string_cache_insert ((gpointer) entity_type), col);
00232     }
00233     return col;
00234 }

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.

00326 {
00327     QofBackend *be;
00328     KvpFrame *kvp;
00329     KvpValue *value;
00330     gint64 counter;
00331 
00332     if (!book)
00333     {
00334         PWARN ("No book!!!");
00335         return -1;
00336     }
00337     if (!counter_name || *counter_name == '\0')
00338     {
00339         PWARN ("Invalid counter name.");
00340         return -1;
00341     }
00342     /* If we've got a backend with a counter method, call it */
00343     be = book->backend;
00344     if (be && be->counter)
00345         return ((be->counter) (be, counter_name));
00346     /* If not, then use the KVP in the book */
00347     kvp = qof_book_get_slots (book);
00348     if (!kvp)
00349     {
00350         PWARN ("Book has no KVP_Frame");
00351         return -1;
00352     }
00353     value = kvp_frame_get_slot_path (kvp, "counters", counter_name, NULL);
00354     if (value)
00355     {
00356         /* found it */
00357         counter = kvp_value_get_gint64 (value);
00358     }
00359     else
00360     {
00361         /* New counter */
00362         counter = 0;
00363     }
00364     /* Counter is now valid; increment it */
00365     counter++;
00366     /* Save off the new counter */
00367     value = kvp_value_new_gint64 (counter);
00368     kvp_frame_set_slot_path (kvp, value, "counters", counter_name, NULL);
00369     kvp_value_delete (value);
00370     /* and return the value */
00371     return counter;
00372 }

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.

00213 {
00214     if (!book || !key)
00215         return NULL;
00216     return g_hash_table_lookup (book->data_tables, (gpointer) key);
00217 }

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.

00181 {
00182     if (!book)
00183         return;
00184     book->inst.dirty = TRUE;
00185 }

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.

00266 {
00267     if (!book)
00268     {
00269         return;
00270     }
00271     book->book_open = 'n';
00272 }

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.

00145 {
00146     if (!book)
00147         return;
00148 
00149     book->inst.dirty = FALSE;
00150     qof_object_mark_clean (book);
00151 }

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.

00076 {
00077     QofBook *book;
00078 
00079     ENTER (" ");
00080     book = g_new0 (QofBook, 1);
00081     qof_book_init (book);
00082     qof_object_book_begin (book);
00083     qof_event_gen (&book->inst.entity, QOF_EVENT_CREATE, NULL);
00084     LEAVE ("book=%p", book);
00085     return book;
00086 }

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.

00136 {
00137     if (!book)
00138         return FALSE;
00139 
00140     return (book->inst.dirty || qof_object_is_dirty (book));
00141 }

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.

00377 {
00378     static QofParam params[] = {
00379         {QOF_PARAM_GUID, QOF_TYPE_GUID,
00380                 (QofAccessFunc) qof_entity_get_guid,
00381             NULL, NULL},
00382         {QOF_PARAM_KVP, QOF_TYPE_KVP,
00383                 (QofAccessFunc) qof_instance_get_slots,
00384             NULL, NULL},
00385         {NULL, NULL, NULL, NULL, NULL},
00386     };
00387 
00388     qof_class_register (QOF_ID_BOOK, NULL, params);
00389 
00390     return TRUE;
00391 }

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.

00192 {
00193     if (!book || !key)
00194         return;
00195     g_hash_table_insert (book->data_tables, (gpointer) key, data);
00196 }

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.

00201 {
00202     if (!book || !key)
00203         return;
00204     g_hash_table_insert (book->data_tables, (gpointer) key, data);
00205 
00206     if (!cb)
00207         return;
00208     g_hash_table_insert (book->data_table_finalizers, (gpointer) key, cb);
00209 }

gboolean qof_book_shutting_down ( QofBook *  book  ) 

Is the book shutting down?

Definition at line 162 of file qofbook.c.

00163 {
00164     if (!book)
00165         return FALSE;
00166     return book->shutting_down;
00167 }

Generated on Thu Jan 31 22:50:27 2008 for QOF by  doxygen 1.5.4