GnuCash  4.901
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_empty (const QofBook *book)
 Check if the book has had anything loaded into it. More...
 
gboolean qof_book_use_trading_accounts (const QofBook *book)
 Returns flag indicating whether this book uses trading accounts.
 
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...
 
void qof_book_set_default_invoice_report (QofBook *book, const gchar *guid, const gchar *name)
 Save the Invoice Report name / guid to be used as the default for printing Invoices.
 
gchar * qof_book_get_default_invoice_report_guid (const QofBook *book)
 Get the guid of the Invoice Report to be used as the default for printing Invoices.
 
gchar * qof_book_get_default_invoice_report_name (const QofBook *book)
 Get the name of the Invoice Report to be used as the default for printing Invoices.
 
gdouble qof_book_get_default_invoice_report_timeout (const QofBook *book)
 Get the length of time available to change the used Invoice Report when printing Invoices.
 
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)
 
const GncGUIDqof_book_get_guid_option (QofBook *book, GSList *path)
 
void qof_book_option_frame_delete (QofBook *book, const char *opt_name)
 
GHashTable * qof_book_get_features (QofBook *book)
 Access functions for reading and setting the used-features on this book.
 
void qof_book_unset_feature (QofBook *book, const gchar *key)
 
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:212
QofCollection * qof_book_get_collection(const QofBook *, QofIdType)
Return The table of entities of the given type.
Definition: qofbook.cpp:527

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 186 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 238 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 342 of file qofbook.cpp.

343 {
344  GHashTable* cols;
345 
346  if (!book) return;
347  ENTER ("book=%p", book);
348 
349  book->shutting_down = TRUE;
350  qof_event_force (&book->inst, QOF_EVENT_DESTROY, NULL);
351 
352  /* Call the list of finalizers, let them do their thing.
353  * Do this before tearing into the rest of the book.
354  */
355  g_hash_table_foreach (book->data_table_finalizers, book_final, book);
356 
357  qof_object_book_end (book);
358 
359  g_hash_table_destroy (book->data_table_finalizers);
360  book->data_table_finalizers = NULL;
361  g_hash_table_destroy (book->data_tables);
362  book->data_tables = NULL;
363 
364  /* qof_instance_release (&book->inst); */
365 
366  /* Note: we need to save this hashtable until after we remove ourself
367  * from it, otherwise we'll crash in our dispose() function when we
368  * DO remove ourself from the collection but the collection had already
369  * been destroyed.
370  */
371  cols = book->hash_of_collections;
372  g_object_unref (book);
373  g_hash_table_destroy (cols);
374  /*book->hash_of_collections = NULL;*/
375 
376  LEAVE ("book=%p", book);
377 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282

◆ qof_book_empty()

gboolean qof_book_empty ( const QofBook *  book)

Check if the book has had anything loaded into it.

Definition at line 517 of file qofbook.cpp.

518 {
519  if (!book) return TRUE;
520  auto root_acct_col = qof_book_get_collection (book, GNC_ID_ROOT_ACCOUNT);
521  return qof_collection_get_data(root_acct_col) == nullptr;
522 }
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:527
gpointer qof_collection_get_data(const QofCollection *col)
Store and retrieve arbitrary object-defined data.
Definition: qofid.cpp:288

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

990 {
991  gint num_days;
992  GDate* result = NULL;
993 
994  g_assert(book);
995  num_days = qof_book_get_num_days_autoreadonly(book);
996  if (num_days > 0)
997  {
998  result = gnc_g_date_new_today();
999  g_date_subtract_days(result, num_days);
1000  }
1001  return result;
1002 }
gint qof_book_get_num_days_autoreadonly(const QofBook *book)
Returns the number of days for auto-read-only transactions.
Definition: qofbook.cpp:969
GDate * gnc_g_date_new_today()
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1226

◆ 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 guaranteed to return a non-NULL value. (Unless the system malloc failed (out of memory) in which case what happens??).

Definition at line 527 of file qofbook.cpp.

528 {
529  QofCollection *col;
530 
531  if (!book || !entity_type) return NULL;
532 
533  col = static_cast<QofCollection*>(g_hash_table_lookup (book->hash_of_collections, entity_type));
534  if (!col)
535  {
536  col = qof_collection_new (entity_type);
537  g_hash_table_insert(
538  book->hash_of_collections,
539  (gpointer)qof_string_cache_insert(entity_type), col);
540  }
541  return col;
542 }
const char * qof_string_cache_insert(const char *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:48

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

587 {
588  KvpFrame *kvp;
589  KvpValue *value;
590 
591  if (!book)
592  {
593  PWARN ("No book!!!");
594  return -1;
595  }
596 
597  if (!counter_name || *counter_name == '\0')
598  {
599  PWARN ("Invalid counter name.");
600  return -1;
601  }
602 
603  /* Use the KVP in the book */
604  kvp = qof_instance_get_slots (QOF_INSTANCE (book));
605 
606  if (!kvp)
607  {
608  PWARN ("Book has no KVP_Frame");
609  return -1;
610  }
611 
612  value = kvp->get_slot({"counters", counter_name});
613  if (value)
614  {
615  /* found it */
616  return value->get<int64_t>();
617  }
618  else
619  {
620  /* New counter */
621  return 0;
622  }
623 }
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250

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

688 {
689  KvpFrame *kvp;
690  const char *user_format = NULL;
691  gchar *norm_format = NULL;
692  KvpValue *value;
693  gchar *error = NULL;
694 
695  if (!book)
696  {
697  PWARN ("No book!!!");
698  return NULL;
699  }
700 
701  if (!counter_name || *counter_name == '\0')
702  {
703  PWARN ("Invalid counter name.");
704  return NULL;
705  }
706 
707  /* Get the KVP from the current book */
708  kvp = qof_instance_get_slots (QOF_INSTANCE (book));
709 
710  if (!kvp)
711  {
712  PWARN ("Book has no KVP_Frame");
713  return NULL;
714  }
715 
716  /* Get the format string */
717  value = kvp->get_slot({"counter_formats", counter_name});
718  if (value)
719  {
720  user_format = value->get<const char*>();
721  norm_format = qof_book_normalize_counter_format(user_format, &error);
722  if (!norm_format)
723  {
724  PWARN("Invalid counter format string. Format string: '%s' Counter: '%s' Error: '%s')", user_format, counter_name, error);
725  /* Invalid format string */
726  user_format = NULL;
727  g_free(error);
728  }
729  }
730 
731  /* If no (valid) format string was found, use the default format
732  * string */
733  if (!norm_format)
734  {
735  /* Use the default format */
736  norm_format = g_strdup ("%.6" PRIi64);
737  }
738  return norm_format;
739 }
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250
gchar * qof_book_normalize_counter_format(const gchar *p, gchar **err_msg)
Validate a counter format string.
Definition: qofbook.cpp:742

◆ 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_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 969 of file qofbook.cpp.

970 {
971  g_assert(book);
972 
973  if (!book->cached_num_days_autoreadonly_isvalid)
974  {
975  double tmp;
976 
977  // No cached value? Then do the expensive KVP lookup
978  qof_instance_get (QOF_INSTANCE (book),
979  PARAM_NAME_NUM_AUTOREAD_ONLY, &tmp,
980  NULL);
981 
982  const_cast<QofBook*>(book)->cached_num_days_autoreadonly = tmp;
983  const_cast<QofBook*>(book)->cached_num_days_autoreadonly_isvalid = TRUE;
984  }
985  // Value is cached now. Use the cheap variable returning.
986  return (gint) book->cached_num_days_autoreadonly;
987 }
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 1337 of file qofbook.cpp.

1338 {
1339  KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
1340  return root->get_slot(gslist_to_option_path(path));
1341 }

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

428 {
429  return book->dirty_time;
430 }

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

627 {
628  KvpFrame *kvp;
629  KvpValue *value;
630  gint64 counter;
631  gchar* format;
632  gchar* result;
633 
634  if (!book)
635  {
636  PWARN ("No book!!!");
637  return NULL;
638  }
639 
640  if (!counter_name || *counter_name == '\0')
641  {
642  PWARN ("Invalid counter name.");
643  return NULL;
644  }
645 
646  /* Get the current counter value from the KVP in the book. */
647  counter = qof_book_get_counter(book, counter_name);
648 
649  /* Check if an error occurred */
650  if (counter < 0)
651  return NULL;
652 
653  /* Increment the counter */
654  counter++;
655 
656  /* Get the KVP from the current book */
657  kvp = qof_instance_get_slots (QOF_INSTANCE (book));
658 
659  if (!kvp)
660  {
661  PWARN ("Book has no KVP_Frame");
662  return NULL;
663  }
664 
665  /* Save off the new counter */
666  qof_book_begin_edit(book);
667  value = new KvpValue(counter);
668  delete kvp->set_path({"counters", counter_name}, value);
669  qof_instance_set_dirty (QOF_INSTANCE (book));
670  qof_book_commit_edit(book);
671 
672  format = qof_book_get_counter_format(book, counter_name);
673 
674  if (!format)
675  {
676  PWARN("Cannot get format for counter");
677  return NULL;
678  }
679 
680  /* Generate a string version of the counter */
681  result = g_strdup_printf(format, counter);
682  g_free (format);
683  return result;
684 }
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:687
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250
gint64 qof_book_get_counter(QofBook *book, const char *counter_name)
This will get the named counter for this book.
Definition: qofbook.cpp:586

◆ qof_book_is_readonly()

gboolean qof_book_is_readonly ( const QofBook *  book)

Return whether the book is read only.

Definition at line 503 of file qofbook.cpp.

504 {
505  g_return_val_if_fail( book != NULL, TRUE );
506  return book->read_only;
507 }

◆ 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 cannot be marked as open.

Definition at line 576 of file qofbook.cpp.

577 {
578  if (!book)
579  {
580  return;
581  }
582  book->book_open = 'n';
583 }

◆ qof_book_mark_readonly()

void qof_book_mark_readonly ( QofBook *  book)

Mark the book as read only.

Definition at line 510 of file qofbook.cpp.

511 {
512  g_return_if_fail( book != NULL );
513  book->read_only = TRUE;
514 }

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

405 {
406  if (!book) return;
407  if (!book->session_dirty)
408  {
409  /* Set the session dirty upfront, because the callback will check. */
410  book->session_dirty = TRUE;
411  book->dirty_time = gnc_time (NULL);
412  if (book->dirty_cb)
413  book->dirty_cb(book, TRUE, book->dirty_data);
414  }
415 }
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:270

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

391 {
392  if (!book) return;
393 
394  book->dirty_time = 0;
395  if (book->session_dirty)
396  {
397  /* Set the session clean upfront, because the callback will check. */
398  book->session_dirty = FALSE;
399  if (book->dirty_cb)
400  book->dirty_cb(book, FALSE, book->dirty_data);
401  }
402 }

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

309 {
310  QofBook *book;
311 
312  ENTER (" ");
313  book = static_cast<QofBook*>(g_object_new(QOF_TYPE_BOOK, NULL));
314  qof_object_book_begin (book);
315 
316  qof_event_gen (&book->inst, QOF_EVENT_CREATE, NULL);
317  LEAVE ("book=%p", book);
318  return book;
319 }
void qof_object_book_begin(QofBook *book)
To be called from within the book.
Definition: qofobject.cpp:80
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:231

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

743 {
744  const gchar *valid_formats [] = {
745  G_GINT64_FORMAT,
746  "lli",
747  "I64i",
748  PRIi64,
749  "li",
750  NULL,
751  };
752  int i = 0;
753  gchar *normalized_spec = NULL;
754 
755  while (valid_formats[i])
756  {
757 
758  if (err_msg && *err_msg)
759  {
760  g_free (*err_msg);
761  *err_msg = NULL;
762  }
763 
764  normalized_spec = qof_book_normalize_counter_format_internal(p, valid_formats[i], err_msg);
765  if (normalized_spec)
766  return normalized_spec; /* Found a valid format specifier, return */
767  i++;
768  }
769 
770  return NULL;
771 }
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:774

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

1345 {
1346  KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
1347  if (path != nullptr)
1348  {
1349  Path path_v {str_KVP_OPTION_PATH};
1350  Path tmp_path;
1351  for (auto item = path; item != nullptr; item = g_slist_next(item))
1352  tmp_path.push_back(static_cast<const char*>(item->data));
1353  delete root->set_path(gslist_to_option_path(path), nullptr);
1354  }
1355  else
1356  delete root->set_path({str_KVP_OPTION_PATH}, nullptr);
1357 }

◆ qof_book_register()

gboolean qof_book_register ( void  )

Register the book object with the QOF object system.

Definition at line 1360 of file qofbook.cpp.

1361 {
1362  static QofParam params[] =
1363  {
1364  { QOF_PARAM_GUID, QOF_TYPE_GUID, (QofAccessFunc)qof_entity_get_guid, NULL },
1365  { QOF_PARAM_KVP, QOF_TYPE_KVP, (QofAccessFunc)qof_instance_get_slots, NULL },
1366  { NULL },
1367  };
1368 
1369  qof_class_register (QOF_ID_BOOK, NULL, params);
1370 
1371  return TRUE;
1372 }
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:86
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 1285 of file qofbook.cpp.

1287 {
1288  /* Wrap this in begin/commit so that it commits only once instead of doing
1289  * so for every option. Qof_book_set_option will take care of dirtying the
1290  * book.
1291  */
1292  qof_book_begin_edit (book);
1293  save_cb (odb, book, clear);
1294  qof_book_commit_edit (book);
1295 }

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

383 {
384  if (!book) return FALSE;
385  return !qof_book_empty(book) && book->session_dirty;
386 
387 }
gboolean qof_book_empty(const QofBook *book)
Check if the book has had anything loaded into it.
Definition: qofbook.cpp:517

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

1325 {
1326  KvpFrame *root = qof_instance_get_slots (QOF_INSTANCE (book));
1327  qof_book_begin_edit (book);
1328  delete root->set_path(gslist_to_option_path(path), value);
1329  qof_instance_set_dirty (QOF_INSTANCE (book));
1330  qof_book_commit_edit (book);
1331 
1332  // Also, mark any cached value as invalid
1333  book->cached_num_field_source_isvalid = FALSE;
1334 }

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

964 {
965  g_assert(book);
966  return (qof_book_get_num_days_autoreadonly(book) != 0);
967 }
gint qof_book_get_num_days_autoreadonly(const QofBook *book)
Returns the number of days for auto-read-only transactions.
Definition: qofbook.cpp:969