Book
[Object: Dynamic Object Class 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))
#define qof_book_get_guid(X)   qof_entity_get_guid (QOF_ENTITY(X))

Typedefs

typedef _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 char *counter_name)


Define Documentation

#define qof_book_get_guid  )     qof_entity_get_guid (QOF_ENTITY(X))
 

deprecated

Definition at line 173 of file qofbook.h.

#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 114 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 52 of file qofbook.h.


Typedef Documentation

typedef GList QofBookList
 

GList of QofBook

Definition at line 66 of file qofbook.h.

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

Invoke the indicated callback on each collection in the book.

Definition at line 104 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 105 of file qofbook.c.

00106 {
00107   if (!book) return;
00108   ENTER ("book=%p", book);
00109 
00110   book->shutting_down = TRUE;
00111   qof_event_force (&book->inst.entity, QOF_EVENT_DESTROY, NULL);
00112 
00113   /* Call the list of finalizers, let them do their thing. 
00114    * Do this before tearing into the rest of the book.
00115    */
00116   g_hash_table_foreach (book->data_table_finalizers, book_final, book);
00117 
00118   qof_object_book_end (book);
00119 
00120   g_hash_table_destroy (book->data_table_finalizers);
00121   book->data_table_finalizers = NULL;
00122   g_hash_table_destroy (book->data_tables);
00123   book->data_tables = NULL;
00124 
00125   qof_instance_release (&book->inst);
00126 
00127   g_hash_table_destroy (book->hash_of_collections);
00128   book->hash_of_collections = NULL;
00129 
00130   g_free (book);
00131   LEAVE ("book=%p", book);
00132 }

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 138 of file qofbook.c.

00139 {
00140   if (book_1 == book_2) return TRUE;
00141   if (!book_1 || !book_2) return FALSE;
00142   return TRUE;
00143 }

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 231 of file qofbook.c.

00232 {
00233   QofCollection *col;
00234 
00235   if (!book || !entity_type) return NULL;
00236 
00237   col = g_hash_table_lookup (book->hash_of_collections, entity_type);
00238   if (!col) {
00239       col = qof_collection_new (entity_type);
00240       g_hash_table_insert(
00241           book->hash_of_collections,
00242           qof_util_string_cache_insert((gpointer) entity_type), col);
00243   }
00244   return col;
00245 }

gint64 qof_book_get_counter QofBook book,
const char *  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 315 of file qofbook.c.

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

gpointer qof_book_get_data QofBook book,
const gchar *  key
 

Retrieves arbitrary pointers to structs stored by qof_book_set_data.

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 193 of file qofbook.c.

00194 {
00195   if (!book) return;
00196   book->inst.dirty = TRUE;
00197 }

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 278 of file qofbook.c.

00279 {
00280         if(!book) { return; }
00281         book->book_open = 'n';
00282 }

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 156 of file qofbook.c.

00157 {
00158   if (!book) return;
00159 
00160   book->inst.dirty = FALSE;
00161   qof_object_mark_clean (book);
00162 }

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 80 of file qofbook.c.

00081 {
00082   QofBook *book;
00083 
00084   ENTER (" ");
00085   book = g_new0(QofBook, 1);
00086   qof_book_init(book);
00087   qof_object_book_begin (book);
00088 
00089   qof_event_gen (&book->inst.entity, QOF_EVENT_CREATE, NULL);
00090   LEAVE ("book=%p", book);
00091   return book;
00092 }

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 148 of file qofbook.c.

00149 {
00150   if (!book) return FALSE;
00151 
00152   return(book->inst.dirty || qof_object_is_dirty (book));
00153 }

gboolean qof_book_register void   ) 
 

Register the book object with the QOF object system.

Definition at line 367 of file qofbook.c.

00368 {
00369   static QofParam params[] = {
00370     { QOF_PARAM_GUID, QOF_TYPE_GUID, (QofAccessFunc)qof_entity_get_guid, NULL },
00371     { QOF_PARAM_KVP,  QOF_TYPE_KVP,  (QofAccessFunc)qof_instance_get_slots, NULL },
00372     { NULL },
00373   };
00374 
00375   qof_class_register (QOF_ID_BOOK, NULL, params);
00376 
00377   return TRUE;
00378 }

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.

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.

gboolean qof_book_shutting_down QofBook book  ) 
 

Is the book shutting down?

Definition at line 175 of file qofbook.c.

00176 {
00177   if (!book) return FALSE;
00178   return book->shutting_down;
00179 }


Generated on Fri May 12 17:57:22 2006 for QOF by  doxygen 1.4.4