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

typedef struct _QofBookClass  QofBookClass;

#include "qofid.h"
#include "kvp_frame.h"
#include "qofinstance.h"

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

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

  /* The time when the book was first dirtied.  This is a secondary
   * indicator. It should only be used when inst.dirty is TRUE. */
  time_t 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 thier 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;

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

struct _QofBookClass
{
   QofInstanceClass parent_class;
};

GType qof_book_get_type(void);

#define QOF_BOOK_LOOKUP_ENTITY(book,guid,e_type,c_type) ({  \
  QofInstance *val = NULL;                                    \
  if (guid && book) {                                       \
    QofCollection *col;                                     \
    col = qof_book_get_collection (book, e_type);           \
    val = qof_collection_lookup_entity (col, guid);         \
  }                                                         \
  (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);

QofCollection  * qof_book_get_collection (const QofBook *, QofIdType);

typedef void (*QofCollectionForeachCB) (QofCollection *, gpointer user_data);
void qof_book_foreach_collection (const QofBook *, QofCollectionForeachCB, gpointer);

#define qof_book_get_slots(book) qof_instance_get_slots(QOF_INSTANCE(book))

void qof_book_set_data (QofBook *book, const gchar *key, gpointer data);

void qof_book_set_data_fin (QofBook *book, const gchar *key, gpointer data, 
                            QofBookFinalCB);

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

gboolean qof_book_shutting_down (const QofBook *book);

gboolean qof_book_not_saved (const QofBook *book);

void qof_book_mark_saved(QofBook *book);

void qof_book_mark_dirty(QofBook *book);

void qof_book_print_dirty (const QofBook *book);

time_t qof_book_get_dirty_time(const QofBook *book);

void qof_book_set_dirty_cb(QofBook *book, QofBookDirtyCB cb, gpointer user_data);

void qof_book_kvp_changed (QofBook *book);

gboolean qof_book_equal (const QofBook *book_1, const QofBook *book_2);

gint64 qof_book_get_counter (const QofBook *book, const char *counter_name);

#define qof_book_get_guid(X) qof_entity_get_guid (QOF_INSTANCE(X))

#endif /* QOF_BOOK_H */

---