GnuCash  2.7.0
Files | Data Structures | Macros | Typedefs | Functions

A QOF Book is a dataset. More...

Files

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

Data Structures

struct  QofBook
 QofBook reference. More...
 
struct  QofBookClass
 

Macros

#define __KVP_VALUE
 
#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. More...
 
#define qof_book_get_guid(X)   qof_entity_get_guid (QOF_INSTANCE(X))
 deprecated
 

Typedefs

typedef void(* QofBookDirtyCB) (QofBook *, gboolean dirty, gpointer user_data)
 
typedef void(* GNCOptionSave) (GNCOptionDB *, QofBook *, gboolean)
 
typedef void(* GNCOptionLoad) (GNCOptionDB *, QofBook *)
 
typedef GList QofBookList
 GList of QofBook.
 
typedef void(* QofBookFinalCB) (QofBook *, gpointer key, gpointer user_data)
 
typedef void(* QofCollectionForeachCB) (QofCollection *, gpointer user_data)
 Invoke the indicated callback on each collection in the book. More...
 

Functions

GType qof_book_get_type (void)
 
gboolean qof_book_register (void)
 Register the book object with the QOF object system. More...
 
QofBook * qof_book_new (void)
 Allocate, initialise and return a new QofBook. More...
 
void qof_book_destroy (QofBook *book)
 End any editing sessions associated with book, and free all memory associated with it. More...
 
void qof_book_mark_closed (QofBook *book)
 Close a book to editing. More...
 
QofCollection * qof_book_get_collection (const QofBook *, QofIdType)
 Return The table of entities of the given type. More...
 
void qof_book_foreach_collection (const QofBook *, QofCollectionForeachCB, gpointer)
 
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. More...
 
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. More...
 
gpointer qof_book_get_data (const QofBook *book, const gchar *key)
 Retrieves arbitrary pointers to structs stored by qof_book_set_data. More...
 
gboolean qof_book_is_readonly (const QofBook *book)
 Return whether the book is read only. More...
 
void qof_book_mark_readonly (QofBook *book)
 Mark the book as read only. More...
 
gboolean qof_book_use_trading_accounts (const QofBook *book)
 Returns flag indicating whether this book uses trading accounts.
 
const gchar * qof_book_get_book_currency_name (QofBook *book)
 Returns pointer to book-currency name for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid default gain/loss policy, both of which are required, for the 'book-currency' currency accounting method to apply. More...
 
const gchar * qof_book_get_default_gains_policy (QofBook *book)
 Returns pointer to default gain/loss policy for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid book-currency, both of which are required, for the 'book-currency' currency accounting method to apply. More...
 
const GncGUIDqof_book_get_default_gain_loss_acct_guid (QofBook *book)
 Returns pointer to default gain/loss account GUID for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid book-currency, both of which are required, for the 'book-currency' currency accounting method to apply. More...
 
gboolean qof_book_uses_autoreadonly (const QofBook *book)
 Returns TRUE if the auto-read-only feature should be used, otherwise FALSE. More...
 
gint qof_book_get_num_days_autoreadonly (const QofBook *book)
 Returns the number of days for auto-read-only transactions. More...
 
GDate * qof_book_get_autoreadonly_gdate (const QofBook *book)
 Returns the GDate that is the threshold for auto-read-only. More...
 
gboolean qof_book_use_split_action_for_num_field (const QofBook *book)
 Returns TRUE if this book uses split action field as the 'Num' field, FALSE if it uses transaction number field.
 
gboolean qof_book_shutting_down (const QofBook *book)
 Is the book shutting down?
 
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. More...
 
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). More...
 
void qof_book_mark_session_dirty (QofBook *book)
 The qof_book_mark_dirty() routine marks the book as having been modified. More...
 
time64 qof_book_get_session_dirty_time (const QofBook *book)
 Retrieve the earliest modification time on the book. More...
 
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.
 
gint64 qof_book_get_counter (QofBook *book, const char *counter_name)
 This will get the named counter for this book. More...
 
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. More...
 
gchar * qof_book_normalize_counter_format (const gchar *format, gchar **err_msg)
 Validate a counter format string. More...
 
char * qof_book_get_counter_format (const QofBook *book, const char *counter_name)
 Get the format string to use for the named counter. More...
 
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)
 
GHashTable * qof_book_get_features (QofBook *book)
 Access functions for reading and setting the used-features on this book.
 
void qof_book_set_feature (QofBook *book, const gchar *key, const gchar *descr)
 
void qof_book_begin_edit (QofBook *book)
 
void qof_book_commit_edit (QofBook *book)
 
void qof_book_save_options (QofBook *book, GNCOptionSave save_cb, GNCOptionDB *odb, gboolean clear)
 Save a GNCOptionsDB back to the book's KVP. More...
 
void qof_book_set_option (QofBook *book, KvpValue *value, GSList *path)
 Save a single option value. More...
 
KvpValue * qof_book_get_option (QofBook *book, GSList *path)
 Read a single option value. More...
 
void qof_book_options_delete (QofBook *book, GSList *path)
 Delete the options. More...
 

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.

Macro Definition Documentation

◆ QOF_BOOK_RETURN_ENTITY

#define QOF_BOOK_RETURN_ENTITY (   book,
  guid,
  e_type,
  c_type 
)
Value:
{ \
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; \
}
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:214
QofCollection * qof_book_get_collection(const QofBook *, QofIdType)
Return The table of entities of the given type.
Definition: qofbook.cpp:599

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.

Definition at line 168 of file qofbook.h.

Typedef Documentation

◆ QofCollectionForeachCB

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

Invoke the indicated callback on each collection in the book.

Definition at line 220 of file qofbook.h.

Function Documentation

◆ qof_book_destroy()

void qof_book_destroy ( QofBook *  book)

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

Definition at line 424 of file qofbook.cpp.

425 {
426  GHashTable* cols;
427 
428  if (!book) return;
429  ENTER ("book=%p", book);
430 
431  book->shutting_down = TRUE;
432  qof_event_force (&book->inst, QOF_EVENT_DESTROY, NULL);
433 
434  /* Call the list of finalizers, let them do their thing.
435  * Do this before tearing into the rest of the book.
436  */
437  g_hash_table_foreach (book->data_table_finalizers, book_final, book);
438 
439  qof_object_book_end (book);
440 
441  g_hash_table_destroy (book->data_table_finalizers);
442  book->data_table_finalizers = NULL;
443  g_hash_table_destroy (book->data_tables);
444  book->data_tables = NULL;
445 
446  /* qof_instance_release (&book->inst); */
447 
448  /* Note: we need to save this hashtable until after we remove ourself
449  * from it, otherwise we'll crash in our dispose() function when we
450  * DO remove ourself from the collection but the collection had already
451  * been destroyed.
452  */
453  cols = book->hash_of_collections;
454  g_object_unref (book);
455  g_hash_table_destroy (cols);
456  /*book->hash_of_collections = NULL;*/
457 
458  LEAVE ("book=%p", book);
459 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271

◆ qof_book_get_autoreadonly_gdate()

GDate* qof_book_get_autoreadonly_gdate ( const QofBook *  book)

Returns the GDate that is the threshold for auto-read-only.

Any txn with posted-date lesser than this date should be considered read-only.

If the auto-read-only feature is not used (qof_book_uses_autoreadonly() returns FALSE), NULL is returned here.

The returned object was allocated newly; the caller must g_date_free() the object afterwards.

Definition at line 1070 of file qofbook.cpp.

1071 {
1072  gint num_days;
1073  GDate* result = NULL;
1074 
1075  g_assert(book);
1076  num_days = qof_book_get_num_days_autoreadonly(book);
1077  if (num_days > 0)
1078  {
1079  result = gnc_g_date_new_today();
1080  g_date_subtract_days(result, num_days);
1081  }
1082  return result;
1083 }
gint qof_book_get_num_days_autoreadonly(const QofBook *book)
Returns the number of days for auto-read-only transactions.
Definition: qofbook.cpp:1060
GDate * gnc_g_date_new_today()
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1344

◆ qof_book_get_book_currency_name()

const gchar* qof_book_get_book_currency_name ( QofBook *  book)

Returns pointer to book-currency name for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid default gain/loss policy, both of which are required, for the 'book-currency' currency accounting method to apply.

Use instead 'gnc_book_get_book_currency_name' which does these validations.

Definition at line 986 of file qofbook.cpp.

987 {
988  const gchar *opt = NULL;
989  qof_instance_get (QOF_INSTANCE (book),
990  "book-currency", &opt,
991  NULL);
992  return opt;
993 }
void qof_instance_get(const QofInstance *inst, const gchar *first_prop,...)
Wrapper for g_object_get.

◆ qof_book_get_collection()

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 599 of file qofbook.cpp.

600 {
601  QofCollection *col;
602 
603  if (!book || !entity_type) return NULL;
604 
605  col = static_cast<QofCollection*>(g_hash_table_lookup (book->hash_of_collections, entity_type));
606  if (!col)
607  {
608  col = qof_collection_new (entity_type);
609  g_hash_table_insert(
610  book->hash_of_collections,
611  qof_string_cache_insert((gpointer) entity_type), col);
612  }
613  return col;
614 }
gpointer qof_string_cache_insert(gconstpointer key)
You can use this function with g_hash_table_insert(), for the key (or value), as long as you use the ...
QofCollection * qof_collection_new(QofIdType type)
create a new collection of entities of type
Definition: qofid.cpp:50

◆ qof_book_get_counter()

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 658 of file qofbook.cpp.

659 {
660  KvpFrame *kvp;
661  KvpValue *value;
662 
663  if (!book)
664  {
665  PWARN ("No book!!!");
666  return -1;
667  }
668 
669  if (!counter_name || *counter_name == '\0')
670  {
671  PWARN ("Invalid counter name.");
672  return -1;
673  }
674 
675  /* Use the KVP in the book */
676  kvp = qof_instance_get_slots (QOF_INSTANCE (book));
677 
678  if (!kvp)
679  {
680  PWARN ("Book has no KVP_Frame");
681  return -1;
682  }
683 
684  value = kvp->get_slot({"counters", counter_name});
685  if (value)
686  {
687  /* found it */
688  return value->get<int64_t>();
689  }
690  else
691  {
692  /* New counter */
693  return 0;
694  }
695 }
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243

◆ qof_book_get_counter_format()

char* 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 returned string should be freed by the caller.

Definition at line 759 of file qofbook.cpp.

760 {
761  KvpFrame *kvp;
762  const char *user_format = NULL;
763  gchar *norm_format = NULL;
764  KvpValue *value;
765  gchar *error = NULL;
766 
767  if (!book)
768  {
769  PWARN ("No book!!!");
770  return NULL;
771  }
772 
773  if (!counter_name || *counter_name == '\0')
774  {
775  PWARN ("Invalid counter name.");
776  return NULL;
777  }
778 
779  /* Get the KVP from the current book */
780  kvp = qof_instance_get_slots (QOF_INSTANCE (book));
781 
782  if (!kvp)
783  {
784  PWARN ("Book has no KVP_Frame");
785  return NULL;
786  }
787 
788  /* Get the format string */
789  value = kvp->get_slot({"counter_formats", counter_name});
790  if (value)
791  {
792  user_format = value->get<const char*>();
793  norm_format = qof_book_normalize_counter_format(user_format, &error);
794  if (!norm_format)
795  {
796  PWARN("Invalid counter format string. Format string: '%s' Counter: '%s' Error: '%s')", user_format, counter_name, error);
797  /* Invalid format string */
798  user_format = NULL;
799  g_free(error);
800  }
801  }
802 
803  /* If no (valid) format string was found, use the default format
804  * string */
805  if (!norm_format)
806  {
807  /* Use the default format */
808  norm_format = g_strdup ("%.6" PRIi64);
809  }
810  return norm_format;
811 }
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243
gchar * qof_book_normalize_counter_format(const gchar *p, gchar **err_msg)
Validate a counter format string.
Definition: qofbook.cpp:814

◆ qof_book_get_data()

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

Retrieves arbitrary pointers to structs stored by qof_book_set_data.

◆ qof_book_get_default_gain_loss_acct_guid()

const GncGUID* qof_book_get_default_gain_loss_acct_guid ( QofBook *  book)

Returns pointer to default gain/loss account GUID for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid book-currency, both of which are required, for the 'book-currency' currency accounting method to apply.

Use instead 'gnc_book_get_default_gain_loss_acct' which does these validations.

Definition at line 1016 of file qofbook.cpp.

1017 {
1018  GncGUID *guid = NULL;
1019  qof_instance_get (QOF_INSTANCE (book),
1020  "default-gain-loss-account-guid", &guid,
1021  NULL);
1022  return guid;
1023 
1024 }
void qof_instance_get(const QofInstance *inst, const gchar *first_prop,...)
Wrapper for g_object_get.
The type used to store guids in C.
Definition: guid.h:75

◆ qof_book_get_default_gains_policy()

const gchar* qof_book_get_default_gains_policy ( QofBook *  book)

Returns pointer to default gain/loss policy for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid book-currency, both of which are required, for the 'book-currency' currency accounting method to apply.

Use instead 'gnc_book_get_default_gains_policy' which does these validations.

Definition at line 1001 of file qofbook.cpp.

1002 {
1003  const gchar *opt = NULL;
1004  qof_instance_get (QOF_INSTANCE (book),
1005  "default-gains-policy", &opt,
1006  NULL);
1007  return opt;
1008 }
void qof_instance_get(const QofInstance *inst, const gchar *first_prop,...)
Wrapper for g_object_get.

◆ qof_book_get_num_days_autoreadonly()

gint qof_book_get_num_days_autoreadonly ( const QofBook *  book)

Returns the number of days for auto-read-only transactions.

If zero, the auto-read-only feature should be disabled (and qof_book_uses_autoreadonly() returns FALSE).

Definition at line 1060 of file qofbook.cpp.

1061 {
1062  g_assert(book);
1063  double tmp;
1064  qof_instance_get (QOF_INSTANCE (book),
1065  "autoreadonly-days", &tmp,
1066  NULL);
1067  return (gint) tmp;
1068 }
void qof_instance_get(const QofInstance *inst, const gchar *first_prop,...)
Wrapper for g_object_get.

◆ qof_book_get_option()

KvpValue* qof_book_get_option ( QofBook *  book,
GSList *  path 
)

Read a single option value.

Used from Scheme, the KvpValue<–>SCM translation is handled by the functions in kvp-scm.c and automated by SWIG. The starting element is set as KVP_OPTION_PATH in qofbookslots.h.

Parameters
bookThe book.
pathA GSList of keys which form a path under KVP_OPTION_PATH.

Definition at line 1205 of file qofbook.cpp.

1206 {
1207  KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
1208  Path path_v {KVP_OPTION_PATH};
1209  for (auto item = path; item != nullptr; item = g_slist_next(item))
1210  path_v.push_back(static_cast<const char*>(item->data));
1211  return root->get_slot(path_v);
1212 }

◆ qof_book_get_session_dirty_time()

time64 qof_book_get_session_dirty_time ( const QofBook *  book)

Retrieve the earliest modification time on the book.

Definition at line 509 of file qofbook.cpp.

510 {
511  return book->dirty_time;
512 }

◆ qof_book_increment_and_format_counter()

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 698 of file qofbook.cpp.

699 {
700  KvpFrame *kvp;
701  KvpValue *value;
702  gint64 counter;
703  gchar* format;
704  gchar* result;
705 
706  if (!book)
707  {
708  PWARN ("No book!!!");
709  return NULL;
710  }
711 
712  if (!counter_name || *counter_name == '\0')
713  {
714  PWARN ("Invalid counter name.");
715  return NULL;
716  }
717 
718  /* Get the current counter value from the KVP in the book. */
719  counter = qof_book_get_counter(book, counter_name);
720 
721  /* Check if an error occurred */
722  if (counter < 0)
723  return NULL;
724 
725  /* Increment the counter */
726  counter++;
727 
728  /* Get the KVP from the current book */
729  kvp = qof_instance_get_slots (QOF_INSTANCE (book));
730 
731  if (!kvp)
732  {
733  PWARN ("Book has no KVP_Frame");
734  return NULL;
735  }
736 
737  /* Save off the new counter */
738  qof_book_begin_edit(book);
739  value = new KvpValue(counter);
740  delete kvp->set_path({"counters", counter_name}, value);
741  qof_instance_set_dirty (QOF_INSTANCE (book));
742  qof_book_commit_edit(book);
743 
744  format = qof_book_get_counter_format(book, counter_name);
745 
746  if (!format)
747  {
748  PWARN("Cannot get format for counter");
749  return NULL;
750  }
751 
752  /* Generate a string version of the counter */
753  result = g_strdup_printf(format, counter);
754  g_free (format);
755  return result;
756 }
char * qof_book_get_counter_format(const QofBook *book, const char *counter_name)
Get the format string to use for the named counter.
Definition: qofbook.cpp:759
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243
gint64 qof_book_get_counter(QofBook *book, const char *counter_name)
This will get the named counter for this book.
Definition: qofbook.cpp:658

◆ qof_book_is_readonly()

gboolean qof_book_is_readonly ( const QofBook *  book)

Return whether the book is read only.

Definition at line 584 of file qofbook.cpp.

585 {
586  g_return_val_if_fail( book != NULL, TRUE );
587  return book->read_only;
588 }

◆ qof_book_mark_closed()

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 648 of file qofbook.cpp.

649 {
650  if (!book)
651  {
652  return;
653  }
654  book->book_open = 'n';
655 }

◆ qof_book_mark_readonly()

void qof_book_mark_readonly ( QofBook *  book)

Mark the book as read only.

Definition at line 591 of file qofbook.cpp.

592 {
593  g_return_if_fail( book != NULL );
594  book->read_only = TRUE;
595 }

◆ qof_book_mark_session_dirty()

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 486 of file qofbook.cpp.

487 {
488  if (!book) return;
489  if (!book->session_dirty)
490  {
491  /* Set the session dirty upfront, because the callback will check. */
492  book->session_dirty = TRUE;
493  book->dirty_time = gnc_time (NULL);
494  if (book->dirty_cb)
495  book->dirty_cb(book, TRUE, book->dirty_data);
496  }
497 }
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:251

◆ qof_book_mark_session_saved()

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 472 of file qofbook.cpp.

473 {
474  if (!book) return;
475 
476  book->dirty_time = 0;
477  if (book->session_dirty)
478  {
479  /* Set the session clean upfront, because the callback will check. */
480  book->session_dirty = FALSE;
481  if (book->dirty_cb)
482  book->dirty_cb(book, FALSE, book->dirty_data);
483  }
484 }

◆ qof_book_new()

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 390 of file qofbook.cpp.

391 {
392  QofBook *book;
393 
394  ENTER (" ");
395  book = static_cast<QofBook*>(g_object_new(QOF_TYPE_BOOK, NULL));
396  qof_object_book_begin (book);
397 
398  qof_event_gen (&book->inst, QOF_EVENT_CREATE, NULL);
399  LEAVE ("book=%p", book);
400  return book;
401 }
void qof_object_book_begin(QofBook *book)
To be called from within the book.
Definition: qofobject.cpp:95
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:234

◆ qof_book_normalize_counter_format()

gchar* qof_book_normalize_counter_format ( const gchar *  format,
gchar **  err_msg 
)

Validate a counter format string.

If valid, returns a normalized format string, that is whatever long int specifier was used will be replaced with the value of the posix "PRIx64" macro. If not valid returns NULL and optionally set an error message is a non-null err_msg parameter was passed. The caller should free the returned format string and error message with g_free.

Definition at line 814 of file qofbook.cpp.

815 {
816  const gchar *valid_formats [] = {
817  G_GINT64_FORMAT,
818  "lli",
819  "I64i",
820  PRIi64,
821  "li",
822  NULL,
823  };
824  int i = 0;
825  gchar *normalized_spec = NULL;
826 
827  while (valid_formats[i])
828  {
829 
830  if (err_msg && *err_msg)
831  {
832  g_free (*err_msg);
833  *err_msg = NULL;
834  }
835 
836  normalized_spec = qof_book_normalize_counter_format_internal(p, valid_formats[i], err_msg);
837  if (normalized_spec)
838  return normalized_spec; /* Found a valid format specifier, return */
839  i++;
840  }
841 
842  return NULL;
843 }
gchar * qof_book_normalize_counter_format_internal(const gchar *p, const gchar *gint64_format, gchar **err_msg)
Validate a counter format string with a given format specifier.
Definition: qofbook.cpp:846

◆ qof_book_options_delete()

void qof_book_options_delete ( QofBook *  book,
GSList *  path 
)

Delete the options.

Primarily used from Scheme to clear out the options before saving a new set.

Parameters
bookThe book.
listA GList of keys which from a path under KVP_OPTION_PATH. If GList is Null, the whole option is deleted.

Definition at line 1215 of file qofbook.cpp.

1216 {
1217  KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
1218  if (path != nullptr)
1219  {
1220  Path path_v {KVP_OPTION_PATH};
1221  for (auto item = path; item != nullptr; item = g_slist_next(item))
1222  path_v.push_back(static_cast<const char*>(item->data));
1223  delete root->set_path(path_v, nullptr);
1224  }
1225  else
1226  delete root->set_path(KVP_OPTION_PATH, nullptr);
1227 }

◆ qof_book_register()

gboolean qof_book_register ( void  )

Register the book object with the QOF object system.

Definition at line 1230 of file qofbook.cpp.

1231 {
1232  static QofParam params[] =
1233  {
1234  { QOF_PARAM_GUID, QOF_TYPE_GUID, (QofAccessFunc)qof_entity_get_guid, NULL },
1235  { QOF_PARAM_KVP, QOF_TYPE_KVP, (QofAccessFunc)qof_instance_get_slots, NULL },
1236  { NULL },
1237  };
1238 
1239  qof_class_register (QOF_ID_BOOK, NULL, params);
1240 
1241  return TRUE;
1242 }
void qof_class_register(QofIdTypeConst obj_name, QofSortFunc default_sort_function, const QofParam *params)
This function registers a new object class with the Qof subsystem.
Definition: qofclass.cpp:89
gpointer(* QofAccessFunc)(gpointer object, const QofParam *param)
The QofAccessFunc defines an arbitrary function pointer for access functions.
Definition: qofclass.h:177
const GncGUID * qof_entity_get_guid(gconstpointer ent)
#define QOF_PARAM_KVP
"Known" Object Parameters – some objects might support these
Definition: qofquery.h:113

◆ qof_book_save_options()

void qof_book_save_options ( QofBook *  book,
GNCOptionSave  save_cb,
GNCOptionDB *  odb,
gboolean  clear 
)

Save a GNCOptionsDB back to the book's KVP.

Parameters
bookThe book.
save_cbA callback function that does the saving.
odbThe GNCOptionsDB to save from.
clearShould the GNCOptionsDB be emptied after the save?

Definition at line 1170 of file qofbook.cpp.

1172 {
1173  /* Wrap this in begin/commit so that it commits only once instead of doing
1174  * so for every option. Qof_book_set_option will take care of dirtying the
1175  * book.
1176  */
1177  qof_book_begin_edit (book);
1178  save_cb (odb, book, clear);
1179  qof_book_commit_edit (book);
1180 }

◆ qof_book_session_not_saved()

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 464 of file qofbook.cpp.

465 {
466  if (!book) return FALSE;
467  return book->session_dirty;
468 
469 }

◆ qof_book_set_data()

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.

◆ qof_book_set_data_fin()

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.

◆ qof_book_set_option()

void qof_book_set_option ( QofBook *  book,
KvpValue *  value,
GSList *  path 
)

Save a single option value.

Used from Scheme, the KvpValue<–>SCM translation is handled by the functions in kvp-scm.c and automated by SWIG. The starting element is set as KVP_OPTION_PATH in qofbookslots.h.

Parameters
bookThe book.
valueThe KvpValue to store.
pathA GSList of keys which form a path under KVP_OPTION_PATH.

Definition at line 1192 of file qofbook.cpp.

1193 {
1194  KvpFrame *root = qof_instance_get_slots (QOF_INSTANCE (book));
1195  Path path_v {KVP_OPTION_PATH};
1196  for (auto item = path; item != nullptr; item = g_slist_next(item))
1197  path_v.push_back(static_cast<const char*>(item->data));
1198  qof_book_begin_edit (book);
1199  delete root->set_path(path_v, value);
1200  qof_instance_set_dirty (QOF_INSTANCE (book));
1201  qof_book_commit_edit (book);
1202 }

◆ qof_book_uses_autoreadonly()

gboolean qof_book_uses_autoreadonly ( const QofBook *  book)

Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.

This is just a wrapper on qof_book_get_num_days_autoreadonly() == 0.

Definition at line 1054 of file qofbook.cpp.

1055 {
1056  g_assert(book);
1057  return (qof_book_get_num_days_autoreadonly(book) != 0);
1058 }
gint qof_book_get_num_days_autoreadonly(const QofBook *book)
Returns the number of days for auto-read-only transactions.
Definition: qofbook.cpp:1060