GnuCash  4.8a-80-g9825132ea+
qofbook.h
Go to the documentation of this file.
1 /********************************************************************\
2  * qofbook.h -- Encapsulate all the information about a dataset. *
3  * This program is free software; you can redistribute it and/or *
4  * modify it under the terms of the GNU General Public License as *
5  * published by the Free Software Foundation; either version 2 of *
6  * the License, or (at your option) any later version. *
7  * *
8  * This program is distributed in the hope that it will be useful, *
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
11  * GNU General Public License for more details. *
12  * *
13  * You should have received a copy of the GNU General Public License*
14  * along with this program; if not, contact: *
15  * *
16  * Free Software Foundation Voice: +1-617-542-5942 *
17  * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
18  * Boston, MA 02110-1301, USA gnu@gnu.org *
19  * *
20 \********************************************************************/
40 #ifndef QOF_BOOK_H
41 #define QOF_BOOK_H
42 
43 #ifdef __cplusplus
44 #include <glib.h> //To preempt it being included extern "C" in a later header.
45 extern "C"
46 {
47 #endif
48 
49 /* We only want a few things exported to Guile */
50 #ifndef SWIG
51 
52 typedef struct _QofBookClass QofBookClass;
53 #ifndef __KVP_VALUE
54 typedef struct KvpValueImpl KvpValue;
55 #define __KVP_VALUE
56 #endif
57 
58 #include "qofid.h"
59 #include "qofinstance.h"
60 #include "qofbackend.h"
61 
62 /* --- type macros --- */
63 #define QOF_TYPE_BOOK (qof_book_get_type ())
64 #define QOF_BOOK(o) \
65  (G_TYPE_CHECK_INSTANCE_CAST ((o), QOF_TYPE_BOOK, QofBook))
66 #define QOF_BOOK_CLASS(k) \
67  (G_TYPE_CHECK_CLASS_CAST((k), QOF_TYPE_BOOK, QofBookClass))
68 #define QOF_IS_BOOK(o) \
69  (G_TYPE_CHECK_INSTANCE_TYPE ((o), QOF_TYPE_BOOK))
70 #define QOF_IS_BOOK_CLASS(k) \
71  (G_TYPE_CHECK_CLASS_TYPE ((k), QOF_TYPE_BOOK))
72 #define QOF_BOOK_GET_CLASS(o) \
73  (G_TYPE_INSTANCE_GET_CLASS ((o), QOF_TYPE_BOOK, QofBookClass))
74 
75 typedef void (*QofBookDirtyCB) (QofBook *, gboolean dirty, gpointer user_data);
76 
77 typedef struct gnc_option_db GNCOptionDB;
78 
79 typedef void (*GNCOptionSave) (GNCOptionDB*, QofBook*, gboolean);
80 typedef void (*GNCOptionLoad) (GNCOptionDB*, QofBook*);
81 
82 /* Book structure */
83 struct _QofBook
84 {
85  QofInstance inst; /* Unique guid for this book. */
86 
87  /* Boolean indicates that the session is dirty -- that is, it has
88  * not yet been written out to disk after the last time the
89  * backend ran commit_edit(). This is distinct from the inherited
90  * QofInstance::dirty, which indicates that some persisitent
91  * property of the book object itself has been edited and not
92  * committed. Some backends write data out as part of
93  * commit_edit() and so don't use this flag.
94  */
95  gboolean session_dirty;
96 
97  /* The time when the book was first dirtied. This is a secondary
98  * indicator. It should only be used when session_saved is FALSE. */
99  time64 dirty_time;
100 
101  /* This callback function is called any time the book dirty flag
102  * changes state. Both clean->dirty and dirty->clean transitions
103  * trigger a callback. */
104  QofBookDirtyCB dirty_cb;
105 
106  /* This is the user supplied data that is returned in the dirty
107  * callback function.*/
108  gpointer dirty_data;
109 
110  /* The entity table associates the GUIDs of all the objects
111  * belonging to this book, with their pointers to the respective
112  * objects. This allows a lookup of objects based on their guid.
113  */
114  GHashTable * hash_of_collections;
115 
116  /* In order to store arbitrary data, for extensibility, add a table
117  * that will be used to hold arbitrary pointers.
118  */
119  GHashTable *data_tables;
120 
121  /* Hash table of destroy callbacks for the data table. */
122  GHashTable *data_table_finalizers;
123 
124  /* Boolean indicates whether book is safe to write to (true means
125  * that it isn't). The usual reason will be a database version
126  * mismatch with the running instance of Gnucash.
127  */
128  gboolean read_only;
129 
130  /* state flag: 'y' means 'open for editing',
131  * 'n' means 'book is closed'
132  * xxxxx shouldn't this be replaced by the instance editlevel ???
133  */
134  char book_open;
135 
136  /* a flag denoting whether the book is closing down, used to
137  * help the QOF objects shut down cleanly without maintaining
138  * internal consistency.
139  * XXX shouldn't this be replaced by instance->do_free ???
140  */
141  gboolean shutting_down;
142 
143  /* version number, used for tracking multiuser updates */
144  gint32 version;
145 
146  /* To be technically correct, backends belong to sessions and
147  * not books. So the pointer below "really shouldn't be here",
148  * except that it provides a nice convenience, avoiding a lookup
149  * from the session. Better solutions welcome ... */
150  QofBackend *backend;
151 
152  /* A cached value of the OPTION_NAME_NUM_FIELD_SOURCE option value
153  * because it is queried quite a lot, so we want to avoid a KVP
154  * lookup on each query */
155  gboolean cached_num_field_source;
156  /* Whether the above cached value is valid. */
157  gboolean cached_num_field_source_isvalid;
158 
159  /* A cahed value of the "autoreadonly-days" option value because
160  * it is queried quite a lot, so we want to avoid a KVP lookup on
161  * each query */
162  gint cached_num_days_autoreadonly;
163  /* Whether the above cached value is valid. */
164  gboolean cached_num_days_autoreadonly_isvalid;
165 };
166 
168 {
169  QofInstanceClass parent_class;
170 };
171 
172 GType qof_book_get_type(void);
173 
183 #define QOF_BOOK_RETURN_ENTITY(book,guid,e_type,c_type) { \
184  QofInstance *val = NULL; \
185  if ((guid != NULL) && (book != NULL)) { \
186  const QofCollection *col; \
187  col = qof_book_get_collection (book, e_type); \
188  val = qof_collection_lookup_entity (col, guid); \
189  } \
190  return (c_type *) val; \
191 }
192 
193 
194 
196 typedef GList QofBookList;
197 
198 typedef void (*QofBookFinalCB) (QofBook *, gpointer key, gpointer user_data);
199 
201 gboolean qof_book_register (void);
202 
205 QofBook * qof_book_new (void);
206 
209 void qof_book_destroy (QofBook *book);
210 
216 void qof_book_mark_closed (QofBook *book);
217 
231 /*@ dependent @*/
232 QofCollection * qof_book_get_collection (const QofBook *, QofIdType);
233 
235 typedef void (*QofCollectionForeachCB) (QofCollection *, gpointer user_data);
236 void qof_book_foreach_collection (const QofBook *, QofCollectionForeachCB, gpointer);
237 
244 void qof_book_set_data (QofBook *book, const gchar *key, gpointer data);
245 
250 void qof_book_set_data_fin (QofBook *book, const gchar *key, gpointer data,
251  QofBookFinalCB);
252 
254 gpointer qof_book_get_data (const QofBook *book, const gchar *key);
255 
257 gboolean qof_book_is_readonly(const QofBook *book);
258 
260 void qof_book_mark_readonly(QofBook *book);
261 
263 gboolean qof_book_empty(const QofBook *book);
264 
265 #endif /* SWIG */
266 
268 gboolean qof_book_use_trading_accounts (const QofBook *book);
269 
275 const gchar * qof_book_get_book_currency_name (QofBook *book);
276 
282 const gchar * qof_book_get_default_gains_policy (QofBook *book);
283 
290 
293 gboolean qof_book_uses_autoreadonly (const QofBook *book);
294 
298 gint qof_book_get_num_days_autoreadonly (const QofBook *book);
299 
308 GDate* qof_book_get_autoreadonly_gdate (const QofBook *book);
309 
312 gboolean qof_book_use_split_action_for_num_field (const QofBook *book);
313 
315 gboolean qof_book_shutting_down (const QofBook *book);
316 
324 gboolean qof_book_session_not_saved (const QofBook *book);
325 
326 /* The following functions are not useful in scripting languages */
327 #ifndef SWIG
328 
334 void qof_book_mark_session_saved(QofBook *book);
335 
340 void qof_book_mark_session_dirty(QofBook *book);
341 
343 time64 qof_book_get_session_dirty_time(const QofBook *book);
344 
348 void qof_book_set_dirty_cb(QofBook *book, QofBookDirtyCB cb, gpointer user_data);
349 
353 gint64 qof_book_get_counter (QofBook *book, const char *counter_name);
354 
359 gchar *qof_book_increment_and_format_counter (QofBook *book, const char *counter_name);
360 
368 gchar * qof_book_normalize_counter_format(const gchar *format, gchar **err_msg);
369 
374 char *qof_book_get_counter_format (const QofBook *book,
375  const char *counter_name);
376 
377 const char* qof_book_get_string_option(const QofBook* book, const char* opt_name);
378 void qof_book_set_string_option(QofBook* book, const char* opt_name, const char* opt_val);
379 const GncGUID* qof_book_get_guid_option(QofBook* book, GSList* path);
380 void qof_book_option_frame_delete (QofBook *book, const char* opt_name);
381 
384 GHashTable *qof_book_get_features (QofBook *book);
385 void qof_book_set_feature (QofBook *book, const gchar *key, const gchar *descr);
386 
387 void qof_book_begin_edit(QofBook *book);
388 void qof_book_commit_edit(QofBook *book);
389 
390 /* Access functions for options. */
399 void qof_book_load_options (QofBook *book, GNCOptionLoad load_cb,
400  GNCOptionDB *odb);
407 void qof_book_save_options (QofBook *book, GNCOptionSave save_cb,
408  GNCOptionDB* odb, gboolean clear);
417 void qof_book_set_option (QofBook *book, KvpValue *value, GSList *path);
418 
426 KvpValue* qof_book_get_option (QofBook *book, GSList *path);
427 
434 void qof_book_options_delete (QofBook *book, GSList *path);
437 #define qof_book_get_guid(X) qof_entity_get_guid (QOF_INSTANCE(X))
438 
439 #endif /* SWIG */
440 #ifdef __cplusplus
441 }
442 #endif
443 
444 #endif /* QOF_BOOK_H */
445 
void qof_book_save_options(QofBook *book, GNCOptionSave save_cb, GNCOptionDB *odb, gboolean clear)
Save a GNCOptionsDB back to the book&#39;s KVP.
Definition: qofbook.cpp:1265
API for data storage Backend.
gboolean qof_book_register(void)
Register the book object with the QOF object system.
Definition: qofbook.cpp:1340
void qof_book_set_option(QofBook *book, KvpValue *value, GSList *path)
Save a single option value.
Definition: qofbook.cpp:1304
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: qofbook.cpp:510
void(* QofCollectionForeachCB)(QofCollection *, gpointer user_data)
Invoke the indicated callback on each collection in the book.
Definition: qofbook.h:235
time64 qof_book_get_session_dirty_time(const QofBook *book)
Retrieve the earliest modification time on the book.
Definition: qofbook.cpp:504
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.
Definition: qofbook.cpp:703
gint qof_book_get_num_days_autoreadonly(const QofBook *book)
Returns the number of days for auto-read-only transactions.
Definition: qofbook.cpp:1092
gboolean qof_book_use_split_action_for_num_field(const QofBook *book)
Returns TRUE if this book uses split action field as the &#39;Num&#39; field, FALSE if it uses transaction nu...
QofBook * qof_book_new(void)
Allocate, initialise and return a new QofBook.
Definition: qofbook.cpp:385
void qof_book_mark_closed(QofBook *book)
Close a book to editing.
Definition: qofbook.cpp:653
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:764
Object instance holds common fields that most gnucash objects use.
void qof_book_mark_readonly(QofBook *book)
Mark the book as read only.
Definition: qofbook.cpp:587
QOF entity type identification system.
GHashTable * qof_book_get_features(QofBook *book)
Access functions for reading and setting the used-features on this book.
Definition: qofbook.cpp:1223
const gchar * qof_book_get_default_gains_policy(QofBook *book)
Returns pointer to default gain/loss policy for book, if one exists in the KVP, or NULL; does not val...
Definition: qofbook.cpp:1006
gint64 qof_book_get_counter(QofBook *book, const char *counter_name)
This will get the named counter for this book.
Definition: qofbook.cpp:663
gboolean qof_book_empty(const QofBook *book)
Check if the book has had anything loaded into it.
Definition: qofbook.cpp:594
const gchar * QofIdType
QofIdType declaration.
Definition: qofid.h:85
KvpValue * qof_book_get_option(QofBook *book, GSList *path)
Read a single option value.
Definition: qofbook.cpp:1317
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:1112
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)...
Definition: qofbook.cpp:467
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...
void qof_book_options_delete(QofBook *book, GSList *path)
Delete the options.
Definition: qofbook.cpp:1324
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.
Implements KvpValue using boost::variant.
Definition: kvp-value.hpp:57
gchar * qof_book_normalize_counter_format(const gchar *format, gchar **err_msg)
Validate a counter format string.
Definition: qofbook.cpp:819
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 t...
Definition: qofbook.cpp:459
void qof_book_mark_session_dirty(QofBook *book)
The qof_book_mark_dirty() routine marks the book as having been modified.
Definition: qofbook.cpp:481
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:580
void qof_book_load_options(QofBook *book, GNCOptionLoad load_cb, GNCOptionDB *odb)
Load a GNCOptionsDB from KVP data.
Definition: qofbook.cpp:1259
const gchar * qof_book_get_book_currency_name(QofBook *book)
Returns pointer to book-currency name for book, if one exists in the KVP, or NULL; does not validate ...
Definition: qofbook.cpp:991
GncGUID * qof_book_get_default_gain_loss_acct_guid(QofBook *book)
Returns pointer to default gain/loss account GUID for book, if one exists in the KVP, or NULL; does not validate contents nor determine if there is a valid book-currency, both of which are required, for the &#39;book-currency&#39; currency accounting method to apply.
Definition: qofbook.cpp:1021
GList QofBookList
GList of QofBook.
Definition: qofbook.h:196
QofBook reference.
Definition: qofbook.h:83
QofCollection * qof_book_get_collection(const QofBook *, QofIdType)
Return The table of entities of the given type.
Definition: qofbook.cpp:604
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93
gboolean qof_book_uses_autoreadonly(const QofBook *book)
Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
Definition: qofbook.cpp:1086
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:531
The type used to store guids in C.
Definition: guid.h:75
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_use_trading_accounts(const QofBook *book)
Returns flag indicating whether this book uses trading accounts.
Definition: qofbook.cpp:1033
void qof_book_destroy(QofBook *book)
End any editing sessions associated with book, and free all memory associated with it...
Definition: qofbook.cpp:419