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

Data Structures
struct	_QofBook

struct	_QofBookClass

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

#define	QOF_BOOK_RETURN_ENTITY(book, guid, e_type, c_type)
	Encapsulates all the information about a dataset manipulated by QOF. This is the top-most structure used for anchoring data. More...

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

Typedefs
typedef struct _QofBookClass	QofBookClass

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

typedef struct gnc_option_db	GNCOptionDB

typedef void(*	GNCOptionSave )(GNCOptionDB , KvpFrame , gboolean)

typedef void(*	GNCOptionLoad )(GNCOptionDB , KvpFrame )

typedef GList	QofBookList

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

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

Functions
GType	qof_book_get_type (void)

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)

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_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)

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)

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_validate_counter_format (const gchar *format)

const 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)

GHashTable *	qof_book_get_features (QofBook *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_load_options (QofBook book, GNCOptionLoad load_cb, GNCOptionDB odb)

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

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

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

deprecated

Definition at line 351 of file qofbook.h.

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

Typedef Documentation

typedef GList QofBookList

GList of QofBook

Definition at line 177 of file qofbook.h.

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

Invoke the indicated callback on each collection in the book.

Definition at line 216 of file qofbook.h.

Function Documentation

void qof_book_destroy ( QofBook * book )

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

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.

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??).

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.

const 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 string should not be freed.

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

Retrieves arbitrary pointers to structs stored by qof_book_set_data.

GHashTable* qof_book_get_features ( QofBook * book )

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

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).

time64 qof_book_get_session_dirty_time ( const QofBook * book )

Retrieve the earliest modification time on the 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. The return value is NULL on error or the formatted (new) value of the counter. The caller should free the result with g_gree.

gboolean qof_book_is_readonly ( const QofBook * book )

Return whether the book is read only.

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.

void qof_book_mark_readonly ( QofBook * book )

Mark the book as read only.

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.

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.

QofBook* qof_book_new ( void )

Allocate, initialise and return a new QofBook. Books contain references to all of the top-level object containers.

gboolean qof_book_register ( void )

Register the book object with the QOF object system.

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.)

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.

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.

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.

gboolean qof_book_shutting_down ( const QofBook * book )

Is the book shutting down?

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_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. This is just a wrapper on qof_book_get_num_days_autoreadonly() == 0.

gchar* qof_book_validate_counter_format ( const gchar * format )

Validate a counter format string. Returns an error message if the format string was invalid, or NULL if it is ok. The caller should free the error message with g_free.

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation