|
GnuCash 2.3.0
|
|
GnuCash 2.3.0
|
Data Structures | |
| struct | _QofBook |
| struct | _QofBookClass |
Files | |
| file | qofbook.h |
Encapsulate all the information about a dataset. | |
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_RETURN_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_guid(X) qof_entity_get_guid (QOF_INSTANCE(X)) |
Typedefs | |
| typedef struct _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) |
| KvpFrame * | qof_book_get_slots (const QofBook *book) |
| 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_is_readonly (const QofBook *book) |
| void | qof_book_mark_readonly (QofBook *book) |
| gboolean | qof_book_use_trading_accounts (const QofBook *book) |
| gboolean | qof_book_shutting_down (const QofBook *book) |
| gboolean | qof_book_session_not_saved (const QofBook *book) |
| void | qof_book_mark_session_saved (QofBook *book) |
| void | qof_book_mark_session_dirty (QofBook *book) |
| time_t | qof_book_get_session_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) |
| gint64 | qof_book_get_counter (QofBook *book, const char *counter_name) |
| gchar * | qof_book_increment_and_format_counter (QofBook *book, const char *counter_name) |
| gchar * | qof_book_validate_counter_format (const gchar *format) |
| gchar * | qof_book_get_counter_format (const QofBook *book, const char *counter_name) |
| const char * | qof_book_get_string_option (const QofBook *book, const char *opt_name) |
| void | qof_book_set_string_option (QofBook *book, const char *opt_name, const char *opt_val) |
| void | qof_book_begin_edit (QofBook *book) |
| void | qof_book_commit_edit (QofBook *book) |
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.
| #define qof_book_get_guid | ( | X | ) | qof_entity_get_guid (QOF_INSTANCE(X)) |
| #define QOF_BOOK_RETURN_ENTITY | ( | book, | |
| guid, | |||
| e_type, | |||
| c_type | |||
| ) |
{ \
QofInstance *val = NULL; \
if ((guid != NULL) && (book != NULL)) { \
const QofCollection *col; \
col = qof_book_get_collection (book, e_type); \
val = qof_collection_lookup_entity (col, guid); \
} \
return (c_type *) val; \
}
Encapsulates all the information about a dataset manipulated by QOF. This is the top-most structure used for anchoring data.
This macro looks up an entity by GncGUID and returns a pointer to the entity by ending with a "return" statement. Hence, this macro can only be used as the last statement in the definition of a function, but not somewhere inline in the code.
| typedef GList QofBookList |
| typedef void(* QofCollectionForeachCB)(QofCollection *, gpointer user_data) |
| void qof_book_destroy | ( | QofBook * | book | ) |
End any editing sessions associated with book, and free all memory associated with it.
Definition at line 119 of file qofbook.c.
{
GHashTable* cols;
if (!book) return;
ENTER ("book=%p", book);
book->shutting_down = TRUE;
qof_event_force (&book->inst, QOF_EVENT_DESTROY, NULL);
/* Call the list of finalizers, let them do their thing.
* Do this before tearing into the rest of the book.
*/
g_hash_table_foreach (book->data_table_finalizers, book_final, book);
qof_object_book_end (book);
g_hash_table_destroy (book->data_table_finalizers);
book->data_table_finalizers = NULL;
g_hash_table_destroy (book->data_tables);
book->data_tables = NULL;
/* qof_instance_release (&book->inst); */
/* Note: we need to save this hashtable until after we remove ourself
* from it, otherwise we'll crash in our dispose() function when we
* DO remove ourself from the collection but the collection had already
* been destroyed.
*/
cols = book->hash_of_collections;
g_object_unref (book);
g_hash_table_destroy (cols);
/*book->hash_of_collections = NULL;*/
LEAVE ("book=%p", book);
}
| 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 296 of file qofbook.c.
{
QofCollection *col;
if (!book || !entity_type) return NULL;
col = g_hash_table_lookup (book->hash_of_collections, entity_type);
if (!col)
{
col = qof_collection_new (entity_type);
g_hash_table_insert(
book->hash_of_collections,
qof_util_string_cache_insert((gpointer) entity_type), col);
}
return col;
}
| gint64 qof_book_get_counter | ( | QofBook * | book, |
| const char * | counter_name | ||
| ) |
This will get the named counter for this book. The return value is -1 on error or the current value of the counter.
Definition at line 355 of file qofbook.c.
{
KvpFrame *kvp;
KvpValue *value;
if (!book)
{
PWARN ("No book!!!");
return -1;
}
if (!counter_name || *counter_name == '\0')
{
PWARN ("Invalid counter name.");
return -1;
}
/* Use the KVP in the book */
kvp = qof_book_get_slots (book);
if (!kvp)
{
PWARN ("Book has no KVP_Frame");
return -1;
}
value = kvp_frame_get_slot_path (kvp, "counters", counter_name, NULL);
if (value)
{
/* found it */
return kvp_value_get_gint64 (value);
}
else
{
/* New counter */
return 0;
}
}
| gchar* qof_book_get_counter_format | ( | const QofBook * | book, |
| const char * | counter_name | ||
| ) |
Get the format string to use for the named counter. The return value is NULL on error or the format string of the counter. The string should not be freed.
Definition at line 455 of file qofbook.c.
{
KvpFrame *kvp;
gchar *format;
KvpValue *value;
gchar *error;
if (!book)
{
PWARN ("No book!!!");
return NULL;
}
if (!counter_name || *counter_name == '\0')
{
PWARN ("Invalid counter name.");
return NULL;
}
/* Get the KVP from the current book */
kvp = qof_book_get_slots (book);
if (!kvp)
{
PWARN ("Book has no KVP_Frame");
return NULL;
}
format = NULL;
/* Get the format string */
value = kvp_frame_get_slot_path (kvp, "counter_formats", counter_name, NULL);
if (value)
{
format = kvp_value_get_string (value);
error = qof_book_validate_counter_format(format);
if (error != NULL)
{
PWARN("Invalid counter format string. Format string: '%s' Counter: '%s' Error: '%s')", format, counter_name, error);
/* Invalid format string */
format = NULL;
g_free(error);
}
}
/* If no (valid) format string was found, use the default format
* string */
if (!format)
{
/* Use the default format */
format = "%.6" G_GINT64_FORMAT;
}
return format;
}
| 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_session_dirty_time | ( | const QofBook * | 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 247 of file qofbook.c.
{
return qof_instance_get_slots(QOF_INSTANCE(book));
}
| gchar* qof_book_increment_and_format_counter | ( | QofBook * | book, |
| const char * | counter_name | ||
| ) |
This will increment the named counter for this book and format it. The return value is NULL on error or the formatted (new) value of the counter. The caller should free the result with g_gree.
Definition at line 395 of file qofbook.c.
{
QofBackend *be;
KvpFrame *kvp;
KvpValue *value;
gint64 counter;
gchar* format;
if (!book)
{
PWARN ("No book!!!");
return NULL;
}
if (!counter_name || *counter_name == '\0')
{
PWARN ("Invalid counter name.");
return NULL;
}
/* Get the current counter value from the KVP in the book. */
counter = qof_book_get_counter(book, counter_name);
/* Check if an error occured */
if (counter < 0)
return NULL;
/* Increment the counter */
counter++;
/* Get the KVP from the current book */
kvp = qof_book_get_slots (book);
if (!kvp)
{
PWARN ("Book has no KVP_Frame");
return NULL;
}
/* Save off the new counter */
qof_book_begin_edit(book);
value = kvp_value_new_gint64 (counter);
kvp_frame_set_slot_path (kvp, value, "counters", counter_name, NULL);
kvp_value_delete (value);
qof_instance_set_dirty (QOF_INSTANCE (book));
qof_book_commit_edit(book);
format = qof_book_get_counter_format(book, counter_name);
if (!format)
{
PWARN("Cannot get format for counter");
return NULL;
}
/* Generate a string version of the counter */
return g_strdup_printf(format, counter);
}
| gboolean qof_book_is_readonly | ( | const QofBook * | book | ) |
| 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 238 of file qofbook.c.
{
qof_book_begin_edit(book);
qof_instance_set_dirty (QOF_INSTANCE (book));
qof_book_commit_edit(book);
}
| void qof_book_mark_closed | ( | QofBook * | book | ) |
| void qof_book_mark_readonly | ( | QofBook * | book | ) |
| void qof_book_mark_session_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 180 of file qofbook.c.
{
if (!book) return;
if (!book->session_dirty)
{
/* Set the session dirty upfront, because the callback will check. */
book->session_dirty = TRUE;
book->dirty_time = time(NULL);
if (book->dirty_cb)
book->dirty_cb(book, TRUE, book->dirty_data);
}
}
| void qof_book_mark_session_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 166 of file qofbook.c.
{
if (!book) return;
book->dirty_time = 0;
if (book->session_dirty)
{
/* Set the session clean upfront, because the callback will check. */
book->session_dirty = FALSE;
if (book->dirty_cb)
book->dirty_cb(book, FALSE, book->dirty_data);
}
}
| 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 85 of file qofbook.c.
{
QofBook *book;
ENTER (" ");
book = g_object_new(QOF_TYPE_BOOK, NULL);
qof_object_book_begin (book);
qof_event_gen (&book->inst, QOF_EVENT_CREATE, NULL);
LEAVE ("book=%p", book);
return book;
}
| gboolean qof_book_register | ( | void | ) |
Register the book object with the QOF object system.
Definition at line 681 of file qofbook.c.
{
static QofParam params[] =
{
{ QOF_PARAM_GUID, QOF_TYPE_GUID, (QofAccessFunc)qof_entity_get_guid, NULL },
{ QOF_PARAM_KVP, QOF_TYPE_KVP, (QofAccessFunc)qof_instance_get_slots, NULL },
{ NULL },
};
qof_class_register (QOF_ID_BOOK, NULL, params);
return TRUE;
}
| gboolean qof_book_session_not_saved | ( | const QofBook * | book | ) |
qof_book_not_saved() returns the value of the session_dirty flag, set when changes to any object in the book are committed (qof_backend->commit_edit has been called) and the backend hasn't yet written out the changes. (Note that SQL backends write commits out immediately; file backends don't, and use the flag to control an autosave timer.)
Definition at line 158 of file qofbook.c.
{
if (!book) return FALSE;
return book->session_dirty;
}
| 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 200 of file qofbook.c.
{
if (book->dirty_cb)
g_warning("qof_book_set_dirty_cb: Already existing callback %p, will be overwritten by %p\n",
book->dirty_cb, cb);
book->dirty_data = user_data;
book->dirty_cb = cb;
}
| gboolean qof_book_shutting_down | ( | const QofBook * | book | ) |
| gboolean qof_book_use_trading_accounts | ( | const QofBook * | book | ) |
Returns flag indicating whether this book uses trading accounts
Definition at line 624 of file qofbook.c.
{
const char *opt;
kvp_value *kvp_val;
kvp_val = kvp_frame_get_slot_path (qof_book_get_slots (book),
KVP_OPTION_PATH,
OPTION_SECTION_ACCOUNTS,
OPTION_NAME_TRADING_ACCOUNTS,
NULL);
if (kvp_val == NULL)
return FALSE;
opt = kvp_value_get_string (kvp_val);
if (opt && opt[0] == 't' && opt[1] == 0)
return TRUE;
return FALSE;
}
| gchar* qof_book_validate_counter_format | ( | const gchar * | format | ) |
Validate a counter format string. Returns an error message if the format string was invalid, or NULL if it is ok. The caller should free the error message with g_free.
Definition at line 511 of file qofbook.c.
{
return qof_book_validate_counter_format_internal(p, G_GINT64_FORMAT);
}
1.7.4