GnuCash: Book

#define qof_book_get_guid ( X ) qof_entity_get_guid (QOF_INSTANCE(X))

deprecated

Definition at line 270 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 191 of file qofbook.h.

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

Value:

({  \
  QofInstance *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 132 of file qofbook.h.

typedef GList QofBookList

GList of QofBook

Definition at line 143 of file qofbook.h.

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

Invoke the indicated callback on each collection in the book.

Definition at line 181 of file qofbook.h.

void qof_book_destroy ( QofBook * book )

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

Definition at line 116 of file qofbook.c.

00117 {
00118   GHashTable* cols;
00119 
00120   if (!book) return;
00121   ENTER ("book=%p", book);
00122 
00123   book->shutting_down = TRUE;
00124   qof_event_force (&book->inst, QOF_EVENT_DESTROY, NULL);
00125 
00126   /* Call the list of finalizers, let them do their thing. 
00127    * Do this before tearing into the rest of the book.
00128    */
00129   g_hash_table_foreach (book->data_table_finalizers, book_final, book);
00130 
00131   qof_object_book_end (book);
00132 
00133   g_hash_table_destroy (book->data_table_finalizers);
00134   book->data_table_finalizers = NULL;
00135   g_hash_table_destroy (book->data_tables);
00136   book->data_tables = NULL;
00137 
00138   /* qof_instance_release (&book->inst); */
00139 
00140   /* Note: we need to save this hashtable until after we remove ourself
00141    * from it, otherwise we'll crash in our dispose() function when we
00142    * DO remove ourself from the collection but the collection had already
00143    * been destroyed.
00144    */
00145   cols = book->hash_of_collections;
00146   g_object_unref (book);
00147   g_hash_table_destroy (cols);
00148   book->hash_of_collections = NULL;
00149 
00150   LEAVE ("book=%p", book);
00151 }

gboolean qof_book_equal	(	const QofBook *	book_1,
		const 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 157 of file qofbook.c.

00158 {
00159   if (book_1 == book_2) return TRUE;
00160   if (!book_1 || !book_2) return FALSE;
00161   return FALSE;
00162 }

QofCollection* qof_book_get_collection	(	const 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 297 of file qofbook.c.

00298 {
00299   QofCollection *col;
00300 
00301   if (!book || !entity_type) return NULL;
00302 
00303   col = g_hash_table_lookup (book->hash_of_collections, entity_type);
00304   if (!col) {
00305       col = qof_collection_new (entity_type);
00306       g_hash_table_insert(
00307           book->hash_of_collections,
00308           qof_util_string_cache_insert((gpointer) entity_type), col);
00309   }
00310   return col;
00311 }

gint64 qof_book_get_counter	(	const 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 369 of file qofbook.c.

00370 {
00371   QofBackend *be;
00372   KvpFrame *kvp;
00373   KvpValue *value;
00374   gint64 counter;
00375 
00376   if (!book) {
00377     PWARN ("No book!!!");
00378     return -1;
00379   }
00380 
00381   if (!counter_name || *counter_name == '\0') {
00382     PWARN ("Invalid counter name.");
00383     return -1;
00384   }
00385 
00386   /* If we've got a backend with a counter method, call it */
00387   be = book->backend;
00388   if (be && be->counter)
00389     return ((be->counter)(be, counter_name));
00390 
00391   /* If not, then use the KVP in the book */
00392   kvp = qof_book_get_slots (book);
00393 
00394   if (!kvp) {
00395     PWARN ("Book has no KVP_Frame");
00396     return -1;
00397   }
00398 
00399   value = kvp_frame_get_slot_path (kvp, "counters", counter_name, NULL);
00400   if (value) {
00401     /* found it */
00402     counter = kvp_value_get_gint64 (value);
00403   } else {
00404     /* New counter */
00405     counter = 0;
00406   }
00407 
00408   /* Counter is now valid; increment it */
00409   counter++;
00410 
00411   /* Save off the new counter */
00412   value = kvp_value_new_gint64 (counter);
00413   kvp_frame_set_slot_path (kvp, value, "counters", counter_name, NULL);
00414   kvp_value_delete (value);
00415 
00416   /* and return the value */
00417   return counter;
00418 }

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

Retrieves arbitrary pointers to structs stored by qof_book_set_data.

time_t qof_book_get_dirty_time ( const QofBook * book )

Retrieve the earliest modification time on the book.

Definition at line 216 of file qofbook.c.

00217 {
00218   return book->dirty_time;
00219 }

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

00261 {
00262   qof_book_mark_dirty(book);
00263 }

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

00345 {
00346         if(!book) { return; }
00347         book->book_open = 'n';
00348 }

void qof_book_mark_dirty ( QofBook * book )

The qof_book_mark_dirty() routine marks the book as having been modified. It can be used by frontend when the used has made a change at the book level.

Definition at line 191 of file qofbook.c.

00192 {
00193   gboolean was_dirty;
00194 
00195   if (!book) return;
00196 
00197   was_dirty = qof_instance_get_dirty_flag(book);
00198   qof_instance_set_dirty_flag(book, TRUE);
00199   if (!was_dirty) {
00200     book->dirty_time = time(NULL);
00201     if (book->dirty_cb)
00202       book->dirty_cb(book, TRUE, book->dirty_data);
00203   }
00204 }

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

00176 {
00177   gboolean was_dirty;
00178 
00179   if (!book) return;
00180 
00181   was_dirty = qof_instance_get_dirty_flag(book);
00182   qof_instance_set_dirty_flag(book, FALSE);
00183   book->dirty_time = 0;
00184   qof_object_mark_clean (book);
00185   if (was_dirty) {
00186     if (book->dirty_cb)
00187       book->dirty_cb(book, FALSE, book->dirty_data);
00188   }
00189 }

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

00083 {
00084   QofBook *book;
00085 
00086   ENTER (" ");
00087   book = g_object_new(QOF_TYPE_BOOK, NULL);
00088   qof_object_book_begin (book);
00089 
00090   qof_event_gen (&book->inst, QOF_EVENT_CREATE, NULL);
00091   LEAVE ("book=%p", book);
00092   return book;
00093 }

gboolean qof_book_not_saved ( const 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 167 of file qofbook.c.

00168 {
00169   if (!book) return FALSE;
00170 
00171   return(qof_instance_get_dirty_flag(book) || qof_object_is_dirty(book));
00172 }

void qof_book_print_dirty ( const QofBook * book )

This debugging function can be used to traverse the book structure and all subsidiary structures, printing out which structures have been marked dirty.

Definition at line 207 of file qofbook.c.

00208 {
00209   if (qof_instance_get_dirty_flag(book))
00210     printf("book is dirty.\n");
00211   qof_book_foreach_collection
00212     (book, (QofCollectionForeachCB)qof_collection_print_dirty, NULL);
00213 }

gboolean qof_book_register ( void )

Register the book object with the QOF object system.

Definition at line 421 of file qofbook.c.

00422 {
00423   static QofParam params[] = {
00424     { QOF_PARAM_GUID, QOF_TYPE_GUID, (QofAccessFunc)qof_entity_get_guid, NULL },
00425     { QOF_PARAM_KVP,  QOF_TYPE_KVP,  (QofAccessFunc)qof_instance_get_slots, NULL },
00426     { NULL },
00427   };
00428 
00429   qof_class_register (QOF_ID_BOOK, NULL, params);
00430 
00431   return TRUE;
00432 }

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.

void qof_book_set_dirty_cb	(	QofBook *	book,
		QofBookDirtyCB	cb,
		gpointer	user_data
	)

Set the function to call when a book transitions from clean to dirty, or vice versa.

Definition at line 222 of file qofbook.c.

00223 {
00224   if (book->dirty_cb)
00225     g_warning("qof_book_set_dirty_cb: Already existing callback %p, will be overwritten by %p\n",
00226               book->dirty_cb, cb);
00227   book->dirty_data = user_data;
00228   book->dirty_cb = cb;
00229 }

gboolean qof_book_shutting_down ( const QofBook * book )

Is the book shutting down?

Definition at line 242 of file qofbook.c.

00243 {
00244   if (!book) return FALSE;
00245   return book->shutting_down;
00246 }


Files
file	qofbook.h
	Encapsulate all the information about a dataset.
Data Structures
struct	_QofBook
struct	_QofBookClass
Defines
#define	QOF_TYPE_BOOK (qof_book_get_type ())
#define	QOF_BOOK(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), QOF_TYPE_BOOK, QofBook))
#define	QOF_BOOK_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), QOF_TYPE_BOOK, QofBookClass))
#define	QOF_IS_BOOK(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), QOF_TYPE_BOOK))
#define	QOF_IS_BOOK_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), QOF_TYPE_BOOK))
#define	QOF_BOOK_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), QOF_TYPE_BOOK, QofBookClass))
#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_INSTANCE(X))
Typedefs
typedef _QofBookClass	QofBookClass
typedef void(*)	QofBookDirtyCB (QofBook *, gboolean dirty, gpointer user_data)
typedef GList	QofBookList
typedef void(*)	QofBookFinalCB (QofBook *, gpointer key, gpointer user_data)
typedef void(*)	QofCollectionForeachCB (QofCollection *, gpointer user_data)
Functions
GType	qof_book_get_type (void)
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 (const QofBook *, QofIdType)
void	qof_book_foreach_collection (const 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 (const QofBook book, const gchar key)
gboolean	qof_book_shutting_down (const QofBook *book)
gboolean	qof_book_not_saved (const QofBook *book)
void	qof_book_mark_saved (QofBook *book)
void	qof_book_mark_dirty (QofBook *book)
void	qof_book_print_dirty (const QofBook *book)
time_t	qof_book_get_dirty_time (const QofBook *book)
void	qof_book_set_dirty_cb (QofBook *book, QofBookDirtyCB cb, gpointer user_data)
void	qof_book_kvp_changed (QofBook *book)
gboolean	qof_book_equal (const QofBook book_1, const QofBook book_2)
gint64	qof_book_get_counter (const QofBook book, const char counter_name)

Book
[Object: Dynamic Object Class Framework]

Detailed Description

Files

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation

Book [Object: Dynamic Object Class Framework]