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) |
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 char *counter_name) |
|
deprecated |
|
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. |
|
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; \ }) Lookup an entity by guid, returning pointer to the entity |
|
GList of QofBook |
|
Invoke the indicated callback on each collection in the 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 }
|
|
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 }
|
|
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 }
|
|
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 }
|
|
Retrieves arbitrary pointers to structs stored by qof_book_set_data. |
|
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.
|
|
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 }
|
|
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 }
|
|
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 }
|
|
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 }
|
|
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 }
|
|
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. |
|
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. |
|
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 }
|