GnuCash  4.11-354-g0815ab64c1
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 class GncOptionDB;
46 #else
47 typedef struct GncOptionDB GncOptionDB;
48 #endif
49 #ifdef __cplusplus
50 extern "C"
51 {
52 #endif
53 
54 /* We only want a few things exported to Guile */
55 #ifndef SWIG
56 
57 typedef struct _QofBookClass QofBookClass;
58 #ifndef __KVP_VALUE
59 typedef struct KvpValueImpl KvpValue;
60 #define __KVP_VALUE
61 #endif
62 
63 #include "qofid.h"
64 #include "qofinstance.h"
65 #include "qofbackend.h"
66 
67 /* --- type macros --- */
68 #define QOF_TYPE_BOOK (qof_book_get_type ())
69 #define QOF_BOOK(o) \
70  (G_TYPE_CHECK_INSTANCE_CAST ((o), QOF_TYPE_BOOK, QofBook))
71 #define QOF_BOOK_CLASS(k) \
72  (G_TYPE_CHECK_CLASS_CAST((k), QOF_TYPE_BOOK, QofBookClass))
73 #define QOF_IS_BOOK(o) \
74  (G_TYPE_CHECK_INSTANCE_TYPE ((o), QOF_TYPE_BOOK))
75 #define QOF_IS_BOOK_CLASS(k) \
76  (G_TYPE_CHECK_CLASS_TYPE ((k), QOF_TYPE_BOOK))
77 #define QOF_BOOK_GET_CLASS(o) \
78  (G_TYPE_INSTANCE_GET_CLASS ((o), QOF_TYPE_BOOK, QofBookClass))
79 
80 typedef void (*QofBookDirtyCB) (QofBook *, gboolean dirty, gpointer user_data);
81 
82 typedef void (*GncOptionSave) (GncOptionDB*, QofBook*, gboolean);
83 typedef void (*GncOptionLoad) (GncOptionDB*, QofBook*);
84 
85 /* Book structure */
86 struct _QofBook
87 {
88  QofInstance inst; /* Unique guid for this book. */
89 
90  /* Boolean indicates that the session is dirty -- that is, it has
91  * not yet been written out to disk after the last time the
92  * backend ran commit_edit(). This is distinct from the inherited
93  * QofInstance::dirty, which indicates that some persisitent
94  * property of the book object itself has been edited and not
95  * committed. Some backends write data out as part of
96  * commit_edit() and so don't use this flag.
97  */
98  gboolean session_dirty;
99 
100  /* The time when the book was first dirtied. This is a secondary
101  * indicator. It should only be used when session_saved is FALSE. */
102  time64 dirty_time;
103 
104  /* This callback function is called any time the book dirty flag
105  * changes state. Both clean->dirty and dirty->clean transitions
106  * trigger a callback. */
107  QofBookDirtyCB dirty_cb;
108 
109  /* This is the user supplied data that is returned in the dirty
110  * callback function.*/
111  gpointer dirty_data;
112 
113  /* The entity table associates the GUIDs of all the objects
114  * belonging to this book, with their pointers to the respective
115  * objects. This allows a lookup of objects based on their guid.
116  */
117  GHashTable * hash_of_collections;
118 
119  /* In order to store arbitrary data, for extensibility, add a table
120  * that will be used to hold arbitrary pointers.
121  */
122  GHashTable *data_tables;
123 
124  /* Hash table of destroy callbacks for the data table. */
125  GHashTable *data_table_finalizers;
126 
127  /* Boolean indicates whether book is safe to write to (true means
128  * that it isn't). The usual reason will be a database version
129  * mismatch with the running instance of Gnucash.
130  */
131  gboolean read_only;
132 
133  /* state flag: 'y' means 'open for editing',
134  * 'n' means 'book is closed'
135  * xxxxx shouldn't this be replaced by the instance editlevel ???
136  */
137  char book_open;
138 
139  /* a flag denoting whether the book is closing down, used to
140  * help the QOF objects shut down cleanly without maintaining
141  * internal consistency.
142  * XXX shouldn't this be replaced by instance->do_free ???
143  */
144  gboolean shutting_down;
145 
146  /* version number, used for tracking multiuser updates */
147  gint32 version;
148 
149  /* To be technically correct, backends belong to sessions and
150  * not books. So the pointer below "really shouldn't be here",
151  * except that it provides a nice convenience, avoiding a lookup
152  * from the session. Better solutions welcome ... */
153  QofBackend *backend;
154 
155  /* A cached value of the OPTION_NAME_NUM_FIELD_SOURCE option value
156  * because it is queried quite a lot, so we want to avoid a KVP
157  * lookup on each query */
158  gboolean cached_num_field_source;
159  /* Whether the above cached value is valid. */
160  gboolean cached_num_field_source_isvalid;
161 
162  /* A cahed value of the "autoreadonly-days" option value because
163  * it is queried quite a lot, so we want to avoid a KVP lookup on
164  * each query */
165  gint cached_num_days_autoreadonly;
166  /* Whether the above cached value is valid. */
167  gboolean cached_num_days_autoreadonly_isvalid;
168 };
169 
171 {
172  QofInstanceClass parent_class;
173 };
174 
175 GType qof_book_get_type(void);
176 
186 #define QOF_BOOK_RETURN_ENTITY(book,guid,e_type,c_type) { \
187  QofInstance *val = NULL; \
188  if ((guid != NULL) && (book != NULL)) { \
189  const QofCollection *col; \
190  col = qof_book_get_collection (book, e_type); \
191  val = qof_collection_lookup_entity (col, guid); \
192  } \
193  return (c_type *) val; \
194 }
195 
196 
197 
199 typedef GList QofBookList;
200 
201 typedef void (*QofBookFinalCB) (QofBook *, gpointer key, gpointer user_data);
202 
204 gboolean qof_book_register (void);
205 
208 QofBook * qof_book_new (void);
209 
212 void qof_book_destroy (QofBook *book);
213 
219 void qof_book_mark_closed (QofBook *book);
220 
234 /*@ dependent @*/
235 QofCollection * qof_book_get_collection (const QofBook *, QofIdType);
236 
238 typedef void (*QofCollectionForeachCB) (QofCollection *, gpointer user_data);
239 void qof_book_foreach_collection (const QofBook *, QofCollectionForeachCB, gpointer);
240 
247 void qof_book_set_data (QofBook *book, const gchar *key, gpointer data);
248 
253 void qof_book_set_data_fin (QofBook *book, const gchar *key, gpointer data,
254  QofBookFinalCB);
255 
257 gpointer qof_book_get_data (const QofBook *book, const gchar *key);
258 
260 gboolean qof_book_is_readonly(const QofBook *book);
261 
263 void qof_book_mark_readonly(QofBook *book);
264 
266 gboolean qof_book_empty(const QofBook *book);
267 
268 #endif /* SWIG */
269 
271 gboolean qof_book_use_trading_accounts (const QofBook *book);
272 
275 gboolean qof_book_uses_autoreadonly (const QofBook *book);
276 
280 gint qof_book_get_num_days_autoreadonly (const QofBook *book);
281 
290 GDate* qof_book_get_autoreadonly_gdate (const QofBook *book);
291 
294 gboolean qof_book_use_split_action_for_num_field (const QofBook *book);
295 
297 gboolean qof_book_shutting_down (const QofBook *book);
298 
306 gboolean qof_book_session_not_saved (const QofBook *book);
307 
308 /* The following functions are not useful in scripting languages */
309 #ifndef SWIG
310 
316 void qof_book_mark_session_saved(QofBook *book);
317 
322 void qof_book_mark_session_dirty(QofBook *book);
323 
325 time64 qof_book_get_session_dirty_time(const QofBook *book);
326 
330 void qof_book_set_dirty_cb(QofBook *book, QofBookDirtyCB cb, gpointer user_data);
331 
335 gint64 qof_book_get_counter (QofBook *book, const char *counter_name);
336 
341 gchar *qof_book_increment_and_format_counter (QofBook *book, const char *counter_name);
342 
350 gchar * qof_book_normalize_counter_format(const gchar *format, gchar **err_msg);
351 
356 char *qof_book_get_counter_format (const QofBook *book,
357  const char *counter_name);
358 
359 const char* qof_book_get_string_option(const QofBook* book, const char* opt_name);
360 void qof_book_set_string_option(QofBook* book, const char* opt_name, const char* opt_val);
361 const GncGUID* qof_book_get_guid_option(QofBook* book, GSList* path);
362 void qof_book_option_frame_delete (QofBook *book, const char* opt_name);
363 
366 GHashTable *qof_book_get_features (QofBook *book);
367 void qof_book_unset_feature (QofBook *book, const gchar *key, const gchar *descr);
368 void qof_book_set_feature (QofBook *book, const gchar *key, const gchar *descr);
369 
370 void qof_book_begin_edit(QofBook *book);
371 void qof_book_commit_edit(QofBook *book);
372 
373 /* Access functions for options. */
382 void qof_book_load_options (QofBook *book, GncOptionLoad load_cb,
383  GncOptionDB *odb);
390 void qof_book_save_options (QofBook *book, GncOptionSave save_cb,
391  GncOptionDB* odb, gboolean clear);
400 void qof_book_set_option (QofBook *book, KvpValue *value, GSList *path);
401 
409 KvpValue* qof_book_get_option (QofBook *book, GSList *path);
410 
417 void qof_book_options_delete (QofBook *book, GSList *path);
420 #define qof_book_get_guid(X) qof_entity_get_guid (QOF_INSTANCE(X))
421 
422 #endif /* SWIG */
423 #ifdef __cplusplus
424 }
425 #endif
426 
427 #endif /* QOF_BOOK_H */
428 
Holds all of the options for a book, report, or stylesheet, organized by GncOptionSections.
API for data storage Backend.
gboolean qof_book_register(void)
Register the book object with the QOF object system.
Definition: qofbook.cpp:1241
void qof_book_load_options(QofBook *book, GncOptionLoad load_cb, GncOptionDB *odb)
Load a GncOptionsDB from KVP data.
Definition: qofbook.cpp:1160
void qof_book_set_option(QofBook *book, KvpValue *value, GSList *path)
Save a single option value.
Definition: qofbook.cpp:1205
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:436
void(* QofCollectionForeachCB)(QofCollection *, gpointer user_data)
Invoke the indicated callback on each collection in the book.
Definition: qofbook.h:238
time64 qof_book_get_session_dirty_time(const QofBook *book)
Retrieve the earliest modification time on the book.
Definition: qofbook.cpp:430
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:629
gint qof_book_get_num_days_autoreadonly(const QofBook *book)
Returns the number of days for auto-read-only transactions.
Definition: qofbook.cpp:972
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:311
void qof_book_mark_closed(QofBook *book)
Close a book to editing.
Definition: qofbook.cpp:579
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:690
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:513
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:1103
gint64 qof_book_get_counter(QofBook *book, const char *counter_name)
This will get the named counter for this book.
Definition: qofbook.cpp:589
gboolean qof_book_empty(const QofBook *book)
Check if the book has had anything loaded into it.
Definition: qofbook.cpp:520
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:1218
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:992
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:393
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:1225
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:745
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:385
void qof_book_mark_session_dirty(QofBook *book)
The qof_book_mark_dirty() routine marks the book as having been modified.
Definition: qofbook.cpp:407
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:506
GList QofBookList
GList of QofBook.
Definition: qofbook.h:199
QofBook reference.
Definition: qofbook.h:86
QofCollection * qof_book_get_collection(const QofBook *, QofIdType)
Return The table of entities of the given type.
Definition: qofbook.cpp:530
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:966
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:457
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:913
void qof_book_destroy(QofBook *book)
End any editing sessions associated with book, and free all memory associated with it...
Definition: qofbook.cpp:345
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:1166