1 /********************************************************************\
2 * qofinstance-p.h -- private fields common to all object instances *
3 * *
4 * This program is free software; you can redistribute it and/or *
5 * modify it under the terms of the GNU General Public License as *
6 * published by the Free Software Foundation; either version 2 of *
7 * the License, or (at your option) any later version. *
8 * *
9 * This program is distributed in the hope that it will be useful, *
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
12 * GNU General Public License for more details. *
13 * *
14 * You should have received a copy of the GNU General Public License*
15 * along with this program; if not, contact: *
16 * *
17 * Free Software Foundation Voice: +1-617-542-5942 *
18 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
19 * Boston, MA 02110-1301, USA gnu@gnu.org *
20 * *
21 \********************************************************************/
22 /*
23 * Object instance holds many common fields that most
24 * gnucash objects use.
25 *
26 * Copyright (C) 2003 Linas Vepstas <linas@linas.org>
27 * Copyright (c) 2007 David Hampton <hampton@employees.org>
28 * Copyright 2017 Aaron Laws <dartme18@gmail.com>
29 */
30
31 #ifndef QOF_INSTANCE_P_H
32 #define QOF_INSTANCE_P_H
33
34 #include "qofinstance.h"
35
36 #ifdef __cplusplus
37 #include "kvp-frame.hpp"
38 #include <string>
39 extern "C"
40 {
41 #endif
42
43 /** Set the collection this instance belongs to. This function should never
44 * be called by user code. Instead call the qof_collection_insert_entity()
45 * function. */
46 void qof_instance_set_collection (gconstpointer ptr, QofCollection *col);
47
48 void qof_instance_set_slots (QofInstance *, KvpFrame *);
49
50 /* Set the last_update time. Reserved for use by the SQL backend;
51 * used for comparing version in local memory to that in remote
52 * server.
53 */
54 void qof_instance_set_last_update (QofInstance *inst, time64 time);
55
56 /** Set the dirty flag of just the instance. Don't modify the
57 * collection flag at all. */
58 void qof_instance_set_dirty_flag (gconstpointer inst, gboolean flag);
59
60 /** Set the GncGUID of this instance */
61 void qof_instance_set_guid (gpointer inst, const GncGUID *guid);
62
63 /** Copy the GncGUID from one instance to another. This routine should
64 * be used with extreme caution, since GncGUID values are everywhere
65 * assumed to be unique. */
66 void qof_instance_copy_guid (gpointer to, gconstpointer from);
67
68 //QofIdType qof_instance_get_e_type (const QofInstance *inst);
69 //void qof_instance_set_e_type (QofInstance *ent, QofIdType e_type);
70
71 /** Return the pointer to the kvp_data */
72 /*@ dependent @*/
73 KvpFrame* qof_instance_get_slots (const QofInstance *);
74 void qof_instance_set_editlevel(gpointer inst, gint level);
75 void qof_instance_increase_editlevel (gpointer ptr);
76 void qof_instance_decrease_editlevel (gpointer ptr);
77 void qof_instance_reset_editlevel (gpointer ptr);
78 /** Set the flag that indicates whether or not this object is about to
79 * be destroyed.
80 *
81 * @param ptr The object whose flag should be set.
82 *
83 * @param value The new value to be set for this object. */
84 void qof_instance_set_destroying (gpointer ptr, gboolean value);
85
86 /** \brief Set the dirty flag
87 Sets this instance AND the collection as dirty.
88 */
89 void qof_instance_set_dirty(QofInstance* inst);
90
91 /* reset the dirty flag */
92 void qof_instance_mark_clean (QofInstance *);
93 /** Get the version number on this instance. The version number is
94 * used to manage multi-user updates. */
95 gint32 qof_instance_get_version (gconstpointer inst);
96
97 /** Set the version number on this instance. The version number is
98 * used to manage multi-user updates. */
99 void qof_instance_set_version (gpointer inst, gint32 value);
100 /** Copy the version number on this instance. The version number is
101 * used to manage multi-user updates. */
102 void qof_instance_copy_version (gpointer to, gconstpointer from);
103
104 /** Get the instance version_check number */
105 guint32 qof_instance_get_version_check (gconstpointer inst);
106 /** Set the instance version_check number */
107 void qof_instance_set_version_check (gpointer inst, guint32 value);
108 /** copy the instance version_check number */
109 void qof_instance_copy_version_check (gpointer to, gconstpointer from);
110 void qof_instance_set_idata(gpointer inst, guint32 idata);
111 /* Convenience functions to save some typing in property handlers */
112 /** @ingroup KVP
113 * @{ */
114 /** Report whether a QofInstance has anything stored in KVP
115 * @param inst The QofInstance
116 * @return TRUE if Kvp isn't empty.
117 */
118 gboolean qof_instance_has_kvp (QofInstance *inst);
119
120 /** Sets a KVP slot to a value from a GValue. Intermediate container
121 * frames will be created if necessary. Commits the change to the QofInstance.
122 * @param inst: The QofInstance on which to set the value.
123 * @param key: The path to the slot.
124 * @param value: A GValue containing an item of a type which KvpValue knows
125 * how to store.
126 */
127 void qof_instance_set_kvp (QofInstance *, GValue const * value, unsigned count, ...);
128
129 /** Retrieves the contents of a KVP slot into a provided GValue.
130 * @param inst: The QofInstance
131 * @param key: The path to the slot.
132 * @param value: A GValue into which to store the value of the slot. It will be
133 * set to the correct type.
134 */
135 void qof_instance_get_kvp (QofInstance *, GValue * value, unsigned count, ...);
136
137 /** @} Close out the DOxygen ingroup */
138 /* Functions to isolate the KVP mechanism inside QOF for cases where
139 GValue * operations won't work.
140 */
141 void qof_instance_copy_kvp (QofInstance *to, const QofInstance *from);
142 void qof_instance_swap_kvp (QofInstance *a, QofInstance *b);
143 int qof_instance_compare_kvp (const QofInstance *a, const QofInstance *b);
144 /** Returns a g_strdup'd string which must be g_freed. */
145 char* qof_instance_kvp_as_string (const QofInstance *inst);
146 void qof_instance_kvp_add_guid (const QofInstance *inst, const char* path,
147 time64 time, const char* key,
148 const GncGUID *guid);
149 void qof_instance_kvp_remove_guid (const QofInstance *inst, const char *path,
150 const char* key, const GncGUID *guid);
151 gboolean qof_instance_kvp_has_guid (const QofInstance *inst, const char *path,
152 const char* key, const GncGUID *guid);
153 void qof_instance_kvp_merge_guids (const QofInstance *target,
154 const QofInstance *donor, const char* path);
155 gboolean qof_instance_has_slot (const QofInstance *inst, const char *path);
156 void qof_instance_slot_delete (const QofInstance *, const char * path);
157 void qof_instance_slot_delete_if_empty (const QofInstance *, const char * path);
158 void qof_instance_foreach_slot (const QofInstance *inst, const char *head,
159 const char *category, void(*proc)(const char*,
160 const GValue*, void*), void* data);
161 #ifdef __cplusplus
162 } /* extern "C" */
163
164 void qof_instance_get_path_kvp (QofInstance *, GValue *, std::vector<std::string> const &);
165
166 void qof_instance_set_path_kvp (QofInstance *, GValue const *, std::vector<std::string> const &);
167
168 bool qof_instance_has_path_slot (QofInstance const *, std::vector<std::string> const &);
169
170 void qof_instance_slot_path_delete (QofInstance const *, std::vector<std::string> const &);
171
172 void qof_instance_slot_path_delete_if_empty (QofInstance const *, std::vector<std::string> const &);
173
174 /** Returns all keys that match the given prefix and their corresponding values.*/
175 std::vector <std::pair <std::string, KvpValue*>>
176 qof_instance_get_slots_prefix (QofInstance const *, std::string const & prefix);
177
178 /**
179 * Similar to qof_instance_foreach_slot, but we don't traverse the depth of the key value frame,
180 * we only check the root level for keys that match the specified prefix.
181 */
182 template<typename func_type, typename data_type>
qof_instance_foreach_slot_prefix(QofInstance const * inst,std::string const & path_prefix,func_type const & func,data_type & data)183 void qof_instance_foreach_slot_prefix(QofInstance const * inst, std::string const & path_prefix,
184 func_type const & func, data_type & data)
185 {
186 inst->kvp_data->for_each_slot_prefix(path_prefix, func, data);
187 }
188
189 #endif
190
191 #endif /* QOF_INSTANCE_P_H */
192