qofbook.h

Go to the documentation of this file.

/********************************************************************\
 * qofbook.h -- Encapsulate all the information about a dataset.    *
 * This program is free software; you can redistribute it and/or    *
 * modify it under the terms of the GNU General Public License as   *
 * published by the Free Software Foundation; either version 2 of   *
 * the License, or (at your option) any later version.              *
 *                                                                  *
 * This program is distributed in the hope that it will be useful,  *
 * but WITHOUT ANY WARRANTY; without even the implied warranty of   *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the    *
 * GNU General Public License for more details.                     *
 *                                                                  *
 * You should have received a copy of the GNU General Public License*
 * along with this program; if not, contact:                        *
 *                                                                  *
 * Free Software Foundation           Voice:  +1-617-542-5942       *
 * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
 * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
 *                                                                  *
\********************************************************************/
#ifndef QOF_BOOK_H
#define QOF_BOOK_H

#include <glib.h>
#ifdef __cplusplus
class GncOptionDB;
#else
typedef struct GncOptionDB GncOptionDB;
#endif
/* We only want a few things exported to Guile */
#ifndef SWIG

typedef struct _QofBookClass  QofBookClass;
#ifndef __KVP_VALUE
typedef struct KvpValueImpl KvpValue;
#define __KVP_VALUE
#endif

#include "qofid.h"
#include "qofinstance.h"
#include "qofbackend.h"

#ifdef __cplusplus
extern "C"
{
#endif

/* --- type macros --- */
#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))

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

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

/* Book structure */
struct _QofBook
{
    QofInstance   inst;     /* Unique guid for this book. */

    /* Boolean indicates that the session is dirty -- that is, it has
     * not yet been written out to disk after the last time the
     * backend ran commit_edit(). This is distinct from the inherited
     * QofInstance::dirty, which indicates that some persistent
     * property of the book object itself has been edited and not
     * committed. Some backends write data out as part of
     * commit_edit() and so don't use this flag.
     */
    gboolean session_dirty;

    /* The time when the book was first dirtied.  This is a secondary
     * indicator. It should only be used when session_saved is FALSE. */
    time64 dirty_time;

    /* This callback function is called any time the book dirty flag
     * changes state. Both clean->dirty and dirty->clean transitions
     * trigger a callback. */
    QofBookDirtyCB dirty_cb;

    /* This is the user supplied data that is returned in the dirty
     * callback function.*/
    gpointer dirty_data;

    /* The entity table associates the GUIDs of all the objects
     * belonging to this book, with their pointers to the respective
     * objects.  This allows a lookup of objects based on their guid.
     */
    GHashTable * hash_of_collections;

    /* In order to store arbitrary data, for extensibility, add a table
     * that will be used to hold arbitrary pointers.
     */
    GHashTable *data_tables;

    /* Hash table of destroy callbacks for the data table. */
    GHashTable *data_table_finalizers;

    /* Boolean indicates whether book is safe to write to (true means
     * that it isn't). The usual reason will be a database version
     * mismatch with the running instance of Gnucash.
     */
    gboolean read_only;

    /* state flag: 'y' means 'open for editing',
     * 'n' means 'book is closed'
     * xxxxx shouldn't this be replaced by the instance editlevel ???
     */
    char book_open;

    /* a flag denoting whether the book is closing down, used to
     * help the QOF objects shut down cleanly without maintaining
     * internal consistency.
     * XXX shouldn't this be replaced by instance->do_free ???
     */
    gboolean shutting_down;

    /* version number, used for tracking multiuser updates */
    gint32  version;

    /* To be technically correct, backends belong to sessions and
     * not books.  So the pointer below "really shouldn't be here",
     * except that it provides a nice convenience, avoiding a lookup
     * from the session.  Better solutions welcome ... */
    QofBackend *backend;

    /* A cached value of the OPTION_NAME_NUM_FIELD_SOURCE option value
     * because it is queried quite a lot, so we want to avoid a KVP
     * lookup on each query */
    gboolean cached_num_field_source;
    /* Whether the above cached value is valid. */
    gboolean cached_num_field_source_isvalid;

    /* A cahed value of the "autoreadonly-days" option value because
     * it is queried quite a lot, so we want to avoid a KVP lookup on
     * each query */
    gint cached_num_days_autoreadonly;
    /* Whether the above cached value is valid. */
    gboolean cached_num_days_autoreadonly_isvalid;
};

struct _QofBookClass
{
    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);

/*@ 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);

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 */