Book

A QOF Book is a dataset. More...

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

Data Structures
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.
#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.

Functions
GType	qof_book_get_type (void)
gboolean	qof_book_register (void)
	Register the book object with the QOF object system.
QofBook *	qof_book_new (void)
	Allocate, initialise and return a new QofBook.
void	qof_book_destroy (QofBook *book)
	End any editing sessions associated with book, and free all memory associated with it.
void	qof_book_mark_closed (QofBook *book)
	Close a book to editing.
gboolean	qof_book_is_open (const QofBook *book)
void	qof_book_swap_books_readonly (QofBook *book, QofBook *other)
QofCollection *	qof_book_get_collection (const QofBook *, QofIdType)
	Return The table of entities of the given type.
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.
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.
gpointer	qof_book_get_data (const QofBook *book, const gchar *key)
	Retrieves arbitrary pointers to structs stored by qof_book_set_data.
gboolean	qof_book_is_readonly (const QofBook *book)
	Return whether the book is read only.
void	qof_book_mark_readonly (QofBook *book)
	Mark the book as read only.
gboolean	qof_book_empty (const QofBook *book)
	Check if the book has had anything loaded into it.
gboolean	qof_book_use_trading_accounts (const QofBook *book)
	Returns flag indicating whether this book uses trading accounts.
void	qof_book_reset_num_days_autoreadonly_cache (QofBook *book)
gboolean	qof_book_uses_autoreadonly (const QofBook *book)
	Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
gint	qof_book_get_num_days_autoreadonly (const QofBook *book)
	Returns the number of days for auto-read-only transactions.
GDate *	qof_book_get_autoreadonly_gdate (const QofBook *book)
	Returns the GDate that is the threshold for auto-read-only.
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.
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).
void	qof_book_mark_session_dirty (QofBook *book)
	The qof_book_mark_dirty() routine marks the book as having been modified.
time64	qof_book_get_session_dirty_time (const QofBook *book)
	Retrieve the earliest modification time on the book.
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.
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.
gchar *	qof_book_normalize_counter_format (const gchar *format, gchar **err_msg)
	Validate a counter format string.
char *	qof_book_get_counter_format (const QofBook *book, const char *counter_name)
	Get the format string to use for the named counter.
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 GncGUID *	qof_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.
void	qof_book_set_option (QofBook *book, KvpValue *value, GSList *path)
	Save a single option value.
KvpValue *	qof_book_get_option (QofBook *book, GSList *path)
	Read a single option value.
void	qof_book_options_delete (QofBook *book, GSList *path)
	Delete the options.

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

__KVP_VALUE

#define __KVP_VALUE

Definition at line 55 of file qofbook.h.

QOF_BOOK

#define QOF_BOOK

(

o

)

(G_TYPE_CHECK_INSTANCE_CAST ((o), QOF_TYPE_BOOK, QofBook))

Definition at line 69 of file qofbook.h.

{
    QofInstanceClass parent_class;
};
 
GType qof_book_get_type(void);
 
#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;                                    \
}
 
 
 
typedef GList QofBookList;
 
typedef void (*QofBookFinalCB) (QofBook *, gpointer key, gpointer user_data);
 
gboolean qof_book_register (void);
 
QofBook * qof_book_new (void);
 
void qof_book_destroy (QofBook *book);
 
void qof_book_mark_closed (QofBook *book);
 
gboolean qof_book_is_open (const QofBook *book);
 
void qof_book_swap_books_readonly (QofBook *book, QofBook *other);
 
/*@ dependent @*/
QofCollection  * qof_book_get_collection (const QofBook *, QofIdType);
 
typedef void (*QofCollectionForeachCB) (QofCollection *, gpointer user_data);
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_is_readonly(const QofBook *book);
 
void qof_book_mark_readonly(QofBook *book);
 
gboolean qof_book_empty(const QofBook *book);
 
#endif /* SWIG */
 
gboolean qof_book_use_trading_accounts (const QofBook *book);
 
void qof_book_reset_num_days_autoreadonly_cache (QofBook *book);
 
gboolean qof_book_uses_autoreadonly (const QofBook *book);
 
gint qof_book_get_num_days_autoreadonly (const QofBook *book);
 
GDate* qof_book_get_autoreadonly_gdate (const QofBook *book);
 
void qof_book_set_default_invoice_report (QofBook *book, const gchar *guid,
                                          const gchar *name);
 
gchar * qof_book_get_default_invoice_report_guid (const QofBook *book);
 
gchar * qof_book_get_default_invoice_report_name (const QofBook *book);
 
gdouble qof_book_get_default_invoice_report_timeout (const QofBook *book);
 
gboolean qof_book_use_split_action_for_num_field (const QofBook *book);
 
gboolean qof_book_shutting_down (const QofBook *book);
 
gboolean qof_book_session_not_saved (const QofBook *book);
 
/* The following functions are not useful in scripting languages */
#ifndef SWIG
 
void qof_book_mark_session_saved(QofBook *book);
 
void qof_book_mark_session_dirty(QofBook *book);
 
time64 qof_book_get_session_dirty_time(const QofBook *book);
 
void qof_book_set_dirty_cb(QofBook *book, QofBookDirtyCB cb, gpointer user_data);
 
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_normalize_counter_format(const gchar *format, gchar **err_msg);
 
char *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);
const GncGUID* qof_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);
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);
 
/* Access functions for options. */
void qof_book_load_options (QofBook *book, GncOptionLoad load_cb,
                            GncOptionDB *odb);
void qof_book_save_options (QofBook *book, GncOptionSave save_cb,
                            GncOptionDB* odb, gboolean clear);
void qof_book_set_option (QofBook *book, KvpValue *value, GSList *path);
 
KvpValue* qof_book_get_option (QofBook *book, GSList *path);
 
void qof_book_options_delete (QofBook *book, GSList *path);
#define qof_book_get_guid(X) qof_entity_get_guid (QOF_INSTANCE(X))
 
#ifdef __cplusplus
}
#endif
 
#endif /* SWIG */
#endif /* QOF_BOOK_H */

QOF_BOOK_CLASS

#define QOF_BOOK_CLASS

(

k

)

(G_TYPE_CHECK_CLASS_CAST((k), QOF_TYPE_BOOK, QofBookClass))

Definition at line 71 of file qofbook.h.

QOF_BOOK_GET_CLASS

#define QOF_BOOK_GET_CLASS

(

o

)

(G_TYPE_INSTANCE_GET_CLASS ((o), QOF_TYPE_BOOK, QofBookClass))

Definition at line 77 of file qofbook.h.

qof_book_get_guid

#define qof_book_get_guid

(

X

)

qof_entity_get_guid (QOF_INSTANCE(X))

deprecated

Definition at line 362 of file qofbook.h.

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;                                    \
}

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 101 of file qofbook.h.

                                                        {   \
  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;                                    \
}

QOF_IS_BOOK

#define QOF_IS_BOOK

(

o

)

(G_TYPE_CHECK_INSTANCE_TYPE ((o), QOF_TYPE_BOOK))

Definition at line 73 of file qofbook.h.

QOF_IS_BOOK_CLASS

#define QOF_IS_BOOK_CLASS

(

k

)

(G_TYPE_CHECK_CLASS_TYPE ((k), QOF_TYPE_BOOK))

Definition at line 75 of file qofbook.h.

QOF_TYPE_BOOK

#define QOF_TYPE_BOOK   (qof_book_get_type ())

Definition at line 68 of file qofbook.h.

Typedef Documentation

GncOptionLoad

typedef void(* GncOptionLoad) (GncOptionDB *, QofBook *)

Definition at line 83 of file qofbook.h.

GncOptionSave

typedef void(* GncOptionSave) (GncOptionDB *, QofBook *, gboolean)

Definition at line 82 of file qofbook.h.

QofBookDirtyCB

typedef void(* QofBookDirtyCB) (QofBook *, gboolean dirty, gpointer user_data)

Definition at line 80 of file qofbook.h.

QofBookFinalCB

typedef void(* QofBookFinalCB) (QofBook *, gpointer key, gpointer user_data)

Definition at line 116 of file qofbook.h.

QofBookList

typedef GList QofBookList

GList of QofBook.

Definition at line 114 of file qofbook.h.

QofCollectionForeachCB

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

Invoke the indicated callback on each collection in the book.

Definition at line 157 of file qofbook.h.

Function Documentation

qof_book_begin_edit()

void qof_book_begin_edit

(

QofBook *

book

)

Definition at line 1234 of file qofbook.cpp.

{
    qof_begin_edit(&book->inst);
}

qof_book_commit_edit()

void qof_book_commit_edit

(

QofBook *

book

)

Definition at line 1355 of file qofbook.cpp.

{
    if (!qof_commit_edit (QOF_INSTANCE(book))) return;
    qof_commit_edit_part2 (&book->inst, commit_err, noop, noop/*lot_free*/);
}

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

{
    GHashTable* cols;
 
    if (!book || !book->hash_of_collections) return;
    ENTER ("book=%p", book);
 
    book->shutting_down = TRUE;
    qof_event_force (&book->inst, QOF_EVENT_DESTROY, nullptr);
 
    /* 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);
 
    /* Lots hold a variety of pointers that need to still exist while
     * cleaning them up so run its book_end before the rest.
     */
    auto lots{qof_book_get_collection(book, GNC_ID_LOT)};
    qof_collection_foreach(lots, destroy_lot, nullptr);
    qof_object_book_end (book);
 
    g_hash_table_destroy (book->data_table_finalizers);
    book->data_table_finalizers = nullptr;
    g_hash_table_destroy (book->data_tables);
    book->data_tables = nullptr;
 
    /* 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);
 
    LEAVE ("book=%p", book);
}

qof_book_empty()

gboolean qof_book_empty

(

const QofBook *

book

)

Check if the book has had anything loaded into it.

Definition at line 511 of file qofbook.cpp.

{
    if (!book) return TRUE;
    auto root_acct_col = qof_book_get_collection (book, GNC_ID_ROOT_ACCOUNT);
    return qof_collection_get_data(root_acct_col) == nullptr;
}

qof_book_foreach_collection()

void qof_book_foreach_collection	(	const QofBook *	book,
		QofCollectionForeachCB	cb,
		gpointer	user_data
	)

Definition at line 554 of file qofbook.cpp.

{
    struct _iterate iter;
 
    g_return_if_fail (book);
    g_return_if_fail (cb);
 
    iter.fn = cb;
    iter.data = user_data;
 
    g_hash_table_foreach (book->hash_of_collections, foreach_cb, &iter);
}

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

{
    gint num_days;
    GDate* result = nullptr;
 
    g_assert(book);
    num_days = qof_book_get_num_days_autoreadonly(book);
    if (num_days > 0)
    {
        result = gnc_g_date_new_today();
        g_date_subtract_days(result, num_days);
    }
    return result;
}

qof_book_get_collection()

QofCollection * qof_book_get_collection	(	const QofBook *	book,
		QofIdType	entity_type
	)

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

{
    QofCollection *col;
 
    if (!book || !entity_type) return nullptr;
 
    col = static_cast<QofCollection*>(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,
            (gpointer)qof_string_cache_insert(entity_type), col);
    }
    return col;
}

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

{
    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_instance_get_slots (QOF_INSTANCE (book));
 
    if (!kvp)
    {
        PWARN ("Book has no KVP_Frame");
        return -1;
    }
 
    value = kvp->get_slot({"counters", counter_name});
    if (value)
    {
        auto int_value{value->get<int64_t>()};
        /* Might be a double because of
         * https://bugs.gnucash.org/show_bug.cgi?id=798930
         */
        if (!int_value)
            int_value = static_cast<int64_t>(value->get<double>());
        return int_value;
    }
    else
    {
        /* New counter */
        return 0;
    }
}

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

{
    KvpFrame *kvp;
    const char *user_format = nullptr;
    gchar *norm_format = nullptr;
    KvpValue *value;
    gchar *error = nullptr;
 
    if (!book)
    {
        PWARN ("No book!!!");
        return nullptr;
    }
 
    if (!counter_name || *counter_name == '\0')
    {
        PWARN ("Invalid counter name.");
        return nullptr;
    }
 
    /* Get the KVP from the current book */
    kvp = qof_instance_get_slots (QOF_INSTANCE (book));
 
    if (!kvp)
    {
        PWARN ("Book has no KVP_Frame");
        return nullptr;
    }
 
    /* Get the format string */
    value = kvp->get_slot({"counter_formats", counter_name});
    if (value)
    {
        user_format = value->get<const char*>();
        norm_format = qof_book_normalize_counter_format(user_format, &error);
        if (!norm_format)
        {
            PWARN("Invalid counter format string. Format string: '%s' Counter: '%s' Error: '%s')", user_format, counter_name, error);
            /* Invalid format string */
            user_format = nullptr;
            g_free(error);
        }
    }
 
    /* If no (valid) format string was found, use the default format
     * string */
    if (!norm_format)
    {
        /* Use the default format */
        norm_format = g_strdup ("%.6" PRIi64);
    }
    return norm_format;
}

qof_book_get_default_invoice_report_guid()

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.

Definition at line 1090 of file qofbook.cpp.

{
    gchar *report_guid = nullptr;
 
    if (!book)
    {
        PWARN ("No book!!!");
        return report_guid;
    }
 
    KvpValue *value = get_option_default_invoice_report_value (const_cast<QofBook*>(book));
 
    if (value)
    {
        auto str {value->get<const char*>()};
        auto ptr = strchr (str, '/');
        if (ptr)
        {
            if (ptr - str == GUID_ENCODING_LENGTH)
            {
                if (strlen (str) > GUID_ENCODING_LENGTH)
                    report_guid = g_strndup (&str[0], GUID_ENCODING_LENGTH);
            }
        }
    }
    return report_guid;
}

qof_book_get_default_invoice_report_name()

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.

Definition at line 1119 of file qofbook.cpp.

{
    gchar *report_name = nullptr;
 
    if (!book)
    {
        PWARN ("No book!!!");
        return report_name;
    }
 
    KvpValue *value = get_option_default_invoice_report_value (const_cast<QofBook*>(book));
 
    if (value)
    {
        auto str {value->get<const char*>()};
        auto ptr = strchr (str, '/');
        if (ptr)
        {
            if (ptr - str == GUID_ENCODING_LENGTH)
            {
                if (strlen (str) > GUID_ENCODING_LENGTH + 1)
                    report_name = g_strdup (&str[GUID_ENCODING_LENGTH + 1]);
                else
                    report_name = g_strdup ("");
            }
        }
    }
    return report_name;
}

qof_book_get_default_invoice_report_timeout()

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.

Definition at line 1150 of file qofbook.cpp.

{
    double ret = 0;
 
    if (!book)
    {
        PWARN ("No book!!!");
        return ret;
    }
 
    KvpFrame *root = qof_instance_get_slots (QOF_INSTANCE(book));
    KvpValue *value = root->get_slot ({KVP_OPTION_PATH,
                                       OPTION_SECTION_BUSINESS,
                                       OPTION_NAME_DEFAULT_INVOICE_REPORT_TIMEOUT});
 
    if (value)
        ret = {value->get<double>()};
 
    return ret;
}

qof_book_get_features()

GHashTable * qof_book_get_features

(

QofBook *

book

)

Access functions for reading and setting the used-features on this book.

Definition at line 1254 of file qofbook.cpp.

{
    KvpFrame *frame = qof_instance_get_slots (QOF_INSTANCE (book));
    GHashTable *features = g_hash_table_new_full (g_str_hash, g_str_equal,
                                                  nullptr, g_free);
 
    PWARN ("qof_book_get_features is now deprecated.");
 
    auto slot = frame->get_slot({GNC_FEATURES});
    if (slot != nullptr)
    {
        frame = slot->get<KvpFrame*>();
        frame->for_each_slot_temp(&add_feature_to_hash, features);
    }
    return features;
}

qof_book_get_guid_option()

const GncGUID * qof_book_get_guid_option	(	QofBook *	book,
		GSList *	path
	)

Definition at line 1208 of file qofbook.cpp.

{
    g_return_val_if_fail(book != nullptr, nullptr);
    g_return_val_if_fail(path != nullptr, nullptr);
 
    auto table_value = qof_book_get_option(book, path);
    if (!table_value)
        return nullptr;
    return table_value->get<GncGUID*>();
}

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

{
    g_assert(book);
 
    if (!book->cached_num_days_autoreadonly_isvalid)
    {
        double tmp;
 
        // No cached value? Then do the expensive KVP lookup
        qof_instance_get (QOF_INSTANCE (book),
              PARAM_NAME_NUM_AUTOREAD_ONLY, &tmp,
              nullptr);
 
        const_cast<QofBook*>(book)->cached_num_days_autoreadonly = tmp;
        const_cast<QofBook*>(book)->cached_num_days_autoreadonly_isvalid = TRUE;
    }
    // Value is cached now. Use the cheap variable returning.
    return (gint) book->cached_num_days_autoreadonly;
}

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

book	The book.
path	A GSList of keys which form a path under KVP_OPTION_PATH.

Definition at line 1392 of file qofbook.cpp.

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

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

{
    return book->dirty_time;
}

qof_book_get_string_option()

const char * qof_book_get_string_option	(	const QofBook *	book,
		const char *	opt_name
	)

Definition at line 1185 of file qofbook.cpp.

{
    auto slot = qof_instance_get_slots(QOF_INSTANCE (book))->get_slot(opt_name_to_path(opt_name));
    if (slot == nullptr)
        return nullptr;
    return slot->get<const char*>();
}

qof_book_get_type()

GType qof_book_get_type

(

void

)

Definition at line 24 of file gmock-qofbook.cpp.

{
    return qof_mockbook_get_type();
}

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

{
    KvpFrame *kvp;
    KvpValue *value;
    gint64 counter;
    gchar* format;
    gchar* result;
 
    if (!book)
    {
        PWARN ("No book!!!");
        return nullptr;
    }
 
    if (!counter_name || *counter_name == '\0')
    {
        PWARN ("Invalid counter name.");
        return nullptr;
    }
 
    /* Get the current counter value from the KVP in the book. */
    counter = qof_book_get_counter(book, counter_name);
 
    /* Check if an error occurred */
    if (counter < 0)
        return nullptr;
 
    /* Increment the counter */
    counter++;
 
    /* Get the KVP from the current book */
    kvp = qof_instance_get_slots (QOF_INSTANCE (book));
 
    if (!kvp)
    {
        PWARN ("Book has no KVP_Frame");
        return nullptr;
    }
 
    /* Save off the new counter */
    qof_book_begin_edit(book);
    value = new KvpValue(counter);
    delete kvp->set_path({"counters", counter_name}, 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 nullptr;
    }
 
    /* Generate a string version of the counter */
    result = g_strdup_printf(format, counter);
    g_free (format);
    return result;
}

qof_book_is_open()

gboolean qof_book_is_open

(

const QofBook *

book

)

Definition at line 579 of file qofbook.cpp.

{
    g_return_val_if_fail (book, FALSE);
    return book->book_open == 'y';
}

qof_book_is_readonly()

gboolean qof_book_is_readonly

(

const QofBook *

book

)

Return whether the book is read only.

Definition at line 497 of file qofbook.cpp.

{
    g_return_val_if_fail( book != nullptr, TRUE );
    return book->read_only;
}

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

{
    if (!book)
    {
        return;
    }
    book->book_open = 'n';
}

qof_book_mark_readonly()

void qof_book_mark_readonly

(

QofBook *

book

)

Mark the book as read only.

Definition at line 504 of file qofbook.cpp.

{
    g_return_if_fail( book != nullptr );
    book->read_only = TRUE;
}

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

{
    if (!book) return;
    if (!book->session_dirty)
    {
        /* Set the session dirty upfront, because the callback will check. */
        book->session_dirty = TRUE;
        book->dirty_time = gnc_time (nullptr);
        if (book->dirty_cb)
            book->dirty_cb(book, TRUE, book->dirty_data);
    }
}

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

{
    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);
    }
}

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

{
    QofBook *book;
 
    ENTER (" ");
    book = static_cast<QofBook*>(g_object_new(QOF_TYPE_BOOK, nullptr));
    qof_object_book_begin (book);
 
    qof_event_gen (&book->inst, QOF_EVENT_CREATE, nullptr);
    LEAVE ("book=%p", book);
    return book;
}

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

{
    const gchar *valid_formats [] = {
            G_GINT64_FORMAT,
            "lli",
            "I64i",
            PRIi64,
            "li",
            nullptr,
    };
    int i = 0;
    gchar *normalized_spec = nullptr;
 
    while (valid_formats[i])
    {
 
        if (err_msg && *err_msg)
        {
            g_free (*err_msg);
            *err_msg = nullptr;
        }
 
        normalized_spec = qof_book_normalize_counter_format_internal(p, valid_formats[i], err_msg);
        if (normalized_spec)
            return normalized_spec;  /* Found a valid format specifier, return */
        i++;
    }
 
    return nullptr;
}

qof_book_option_frame_delete()

void qof_book_option_frame_delete	(	QofBook *	book,
		const char *	opt_name
	)

Definition at line 1220 of file qofbook.cpp.

{
    if (opt_name && (*opt_name != '\0'))
    {
        qof_book_begin_edit(book);
        auto frame = qof_instance_get_slots(QOF_INSTANCE(book));
        auto opt_path = opt_name_to_path(opt_name);
        delete frame->set_path(opt_path, nullptr);
        qof_instance_set_dirty (QOF_INSTANCE (book));
        qof_book_commit_edit(book);
    }
}

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

book	The book.
list	A GList of keys which from a path under KVP_OPTION_PATH. If GList is Null, the whole option is deleted.

Definition at line 1399 of file qofbook.cpp.

{
    KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
    if (path != nullptr)
    {
        Path path_v {str_KVP_OPTION_PATH};
        Path tmp_path;
        for (auto item = path; item != nullptr; item = g_slist_next(item))
            tmp_path.push_back(static_cast<const char*>(item->data));
        delete root->set_path(gslist_to_option_path(path), nullptr);
    }
    else
        delete root->set_path({str_KVP_OPTION_PATH}, nullptr);
}

qof_book_register()

gboolean qof_book_register

(

void

)

Register the book object with the QOF object system.

Definition at line 1415 of file qofbook.cpp.

{
    static QofParam params[] =
    {
        { QOF_PARAM_GUID, QOF_TYPE_GUID, (QofAccessFunc)qof_entity_get_guid, nullptr },
        { QOF_PARAM_KVP,  QOF_TYPE_KVP,  (QofAccessFunc)qof_instance_get_slots, nullptr },
        { nullptr },
    };
 
    qof_class_register (QOF_ID_BOOK, nullptr, params);
 
    return TRUE;
}

qof_book_reset_num_days_autoreadonly_cache()

void qof_book_reset_num_days_autoreadonly_cache

(

QofBook *

book

)

Definition at line 980 of file qofbook.cpp.

{
    g_return_if_fail (book);
    book->cached_num_days_autoreadonly_isvalid = FALSE;
}

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

book	The book.
save_cb	A callback function that does the saving.
odb	The GncOptionsDB to save from.
clear	Should the GncOptionsDB be emptied after the save?

Definition at line 1340 of file qofbook.cpp.

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

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

{
    if (!book) return FALSE;
    return !qof_book_empty(book) && book->session_dirty;
 
}

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_default_invoice_report()

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.

Definition at line 1044 of file qofbook.cpp.

{
    const gchar *existing_guid_name = nullptr;
    gchar *new_guid_name;
 
    if (!book)
    {
        PWARN ("No book!!!");
        return;
    }
 
    if (!guid)
    {
        PWARN ("No guid!!!");
        return;
    }
 
    if (!name)
    {
        PWARN ("No name!!!");
        return;
    }
 
    KvpValue *value = get_option_default_invoice_report_value (book);
 
    if (value)
        existing_guid_name = {value->get<const char*>()};
 
    new_guid_name = g_strconcat (guid, "/", name, nullptr);
 
    if (g_strcmp0 (existing_guid_name, new_guid_name) != 0)
    {
        auto value = new KvpValue {g_strdup(new_guid_name)};
        KvpFrame *root = qof_instance_get_slots (QOF_INSTANCE(book));
        qof_book_begin_edit (book);
        delete root->set_path ({KVP_OPTION_PATH,
                                OPTION_SECTION_BUSINESS,
                                OPTION_NAME_DEFAULT_INVOICE_REPORT}, value);
        qof_instance_set_dirty (QOF_INSTANCE(book));
        qof_book_commit_edit (book);
    }
    g_free (new_guid_name);
}

qof_book_set_dirty_cb()

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

{
    g_return_if_fail(book);
    if (book->dirty_cb)
        PWARN("Already existing callback %p, will be overwritten by %p\n",
                  book->dirty_cb, cb);
    book->dirty_data = user_data;
    book->dirty_cb = cb;
}

qof_book_set_feature()

void qof_book_set_feature	(	QofBook *	book,
		const gchar *	key,
		const gchar *	descr
	)

Definition at line 1272 of file qofbook.cpp.

{
    KvpFrame *frame = qof_instance_get_slots (QOF_INSTANCE (book));
    KvpValue* feature = nullptr;
    auto feature_slot = frame->get_slot({GNC_FEATURES});
    if (feature_slot)
    {
        auto feature_frame = feature_slot->get<KvpFrame*>();
        feature = feature_frame->get_slot({key});
    }
    if (feature == nullptr || g_strcmp0 (feature->get<const char*>(), descr))
    {
        qof_book_begin_edit (book);
        delete frame->set_path({GNC_FEATURES, key}, new KvpValue(g_strdup (descr)));
        qof_instance_set_dirty (QOF_INSTANCE (book));
        qof_book_commit_edit (book);
    }
}

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

book	The book.
value	The KvpValue to store.
path	A GSList of keys which form a path under KVP_OPTION_PATH.

Definition at line 1379 of file qofbook.cpp.

{
    KvpFrame *root = qof_instance_get_slots (QOF_INSTANCE (book));
    qof_book_begin_edit (book);
    delete root->set_path(gslist_to_option_path(path), value);
    qof_instance_set_dirty (QOF_INSTANCE (book));
    qof_book_commit_edit (book);
 
    // Also, mark any cached value as invalid
    book->cached_num_field_source_isvalid = FALSE;
}

qof_book_set_string_option()

void qof_book_set_string_option	(	QofBook *	book,
		const char *	opt_name,
		const char *	opt_val
	)

Definition at line 1194 of file qofbook.cpp.

{
    qof_book_begin_edit(book);
    auto frame = qof_instance_get_slots(QOF_INSTANCE(book));
    auto opt_path = opt_name_to_path(opt_name);
    if (opt_val && (*opt_val != '\0'))
        delete frame->set_path(opt_path, new KvpValue(g_strdup(opt_val)));
    else
        delete frame->set_path(opt_path, nullptr);
    qof_instance_set_dirty (QOF_INSTANCE (book));
    qof_book_commit_edit(book);
}

qof_book_shutting_down()

gboolean qof_book_shutting_down

(

const QofBook *

book

)

Is the book shutting down?

Definition at line 447 of file qofbook.cpp.

{
    if (!book) return FALSE;
    return book->shutting_down;
}

qof_book_swap_books_readonly()

void qof_book_swap_books_readonly	(	QofBook *	book,
		QofBook *	other
	)

Definition at line 585 of file qofbook.cpp.

{
    g_return_if_fail (book && other);
    std::swap (book->read_only, other->read_only);
}

qof_book_unset_feature()

void qof_book_unset_feature	(	QofBook *	book,
		const gchar *	key
	)

Definition at line 1318 of file qofbook.cpp.

{
    KvpFrame *frame = qof_instance_get_slots (QOF_INSTANCE (book));
    auto feature_slot = frame->get_slot({GNC_FEATURES, key});
    if (!feature_slot)
    {
        PWARN ("no feature %s. bail out.", key);
        return;
    }
    qof_book_begin_edit (book);
    delete frame->set_path({GNC_FEATURES, key}, nullptr);
    qof_instance_set_dirty (QOF_INSTANCE (book));
    qof_book_commit_edit (book);
}

qof_book_use_split_action_for_num_field()

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.

Definition at line 30 of file gmock-qofbook.cpp.

{
    SCOPED_TRACE("");
    auto mockbook = qof_mockbook(book);
    return mockbook ? mockbook->use_split_action_for_num_field() : FALSE;
}

qof_book_use_trading_accounts()

gboolean qof_book_use_trading_accounts

(

const QofBook *

book

)

Returns flag indicating whether this book uses trading accounts.

Definition at line 921 of file qofbook.cpp.

{
    char *opt = nullptr;
    qof_instance_get (QOF_INSTANCE (book), "trading-accts", &opt, nullptr);
    auto retval = (opt && opt[0] == 't' && opt[1] == 0);
    g_free (opt);
    return retval;
}

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

{
    g_assert(book);
    return (qof_book_get_num_days_autoreadonly(book) != 0);
}