QOF  0.8.7
kvpframe.h
Go to the documentation of this file.
1 /********************************************************************\
2  * kvpframe.h -- Implements a key-value frame system *
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 \********************************************************************/
63 #ifndef KVP_FRAME_H
64 #define KVP_FRAME_H
65 
66 #include "qofnumeric.h"
67 #include "guid.h"
68 #include "qoftime.h"
69 #include "qofutil.h"
70 
71 #define QOF_MOD_KVP "qof-kvp"
72 
74 typedef struct _KvpFrame KvpFrame;
75 
78 typedef struct _KvpValue KvpValue;
79 
87 typedef enum
88 {
137 } KvpValueType;
138 
144 KvpFrame *
145 kvp_frame_new (void);
146 
148 void
149 kvp_frame_delete (KvpFrame * frame);
150 
153 KvpFrame *
154 kvp_frame_copy (const KvpFrame * frame);
155 
157 gboolean
158 kvp_frame_is_empty (KvpFrame * frame);
159 
170 void
171 kvp_frame_set_gint64 (KvpFrame * frame, const gchar * path, gint64 ival);
172 
177 void
178 kvp_frame_set_double (KvpFrame * frame, const gchar * path, gdouble dval);
179 
184 void
185 kvp_frame_set_numeric (KvpFrame * frame, const gchar * path,
186  QofNumeric nval);
187 
194 void
195 kvp_frame_set_string (KvpFrame * frame, const gchar * path,
196  const gchar *str);
197 
204 void
205 kvp_frame_set_guid (KvpFrame * frame, const gchar * path,
206  const GUID * guid);
207 
214 void
215 kvp_frame_set_time (KvpFrame * frame, const gchar *path, QofTime *qt);
216 
221 void
222 kvp_frame_set_boolean (KvpFrame * frame, const gchar * path, gboolean val);
223 
230 void
231 kvp_frame_set_frame (KvpFrame * frame, const gchar * path,
232  KvpFrame * chld);
233 
240 void kvp_frame_set_frame_nc (KvpFrame * frame, const gchar * path,
241  KvpFrame * chld);
242 
259 KvpFrame *
260 kvp_frame_set_value (KvpFrame * frame, const gchar * path,
261  const KvpValue * value);
262 
277 KvpFrame *
278 kvp_frame_set_value_nc (KvpFrame * frame, const gchar * path, KvpValue * value);
279 
288 KvpValue *
289 kvp_frame_replace_value_nc (KvpFrame * frame, const gchar * slot,
290  KvpValue * new_value);
304 void
305 kvp_frame_add_gint64 (KvpFrame * frame, const gchar * path, gint64 ival);
306 
314 void
315 kvp_frame_add_double (KvpFrame * frame, const gchar * path, gdouble dval);
316 
324 void
325 kvp_frame_add_numeric (KvpFrame * frame, const gchar * path,
326  QofNumeric nval);
327 
335 void
336 kvp_frame_add_time (KvpFrame * frame, const gchar *path, QofTime *qt);
337 
346 void kvp_frame_add_string (KvpFrame * frame, const gchar * path,
347  const gchar * str);
348 
349 void
350 kvp_frame_add_boolean (KvpFrame * frame, const gchar * path, gboolean val);
351 
359 void kvp_frame_add_guid (KvpFrame * frame, const gchar * path,
360  const GUID * guid);
361 
369 void kvp_frame_add_frame (KvpFrame * frame, const gchar * path,
370  KvpFrame * chld);
378 void kvp_frame_add_frame_nc (KvpFrame * frame, const gchar * path,
379  KvpFrame * chld);
380 
390 KvpFrame *
391 kvp_frame_add_value (KvpFrame * frame, const gchar * path,
392  KvpValue * value);
393 
394 /* \brief Add the value directly to the glist bag
395 
396  If not all frame components of the path exist, they are created.
397  If there was another item previously stored at that path, then the
398  path is converted to a bag, and the old value, along with the new
399  value, is added to the bag. This routine returns the pointer to the
400  last frame (the actual frame to which the value was added), or NULL
401  if there was an error of any sort (typically, a parse error in the path).
402 */
403 KvpFrame *
404 kvp_frame_add_value_nc (KvpFrame * frame, const gchar * path,
405  KvpValue * value);
406 
407 
439 gint64
440 kvp_frame_get_gint64 (const KvpFrame * frame, const gchar * path);
441 gdouble
442 kvp_frame_get_double (const KvpFrame * frame, const gchar * path);
443 QofNumeric
444 kvp_frame_get_numeric (const KvpFrame * frame, const gchar * path);
445 gchar *
446 kvp_frame_get_string (const KvpFrame * frame, const gchar * path);
447 GUID *
448 kvp_frame_get_guid (const KvpFrame * frame, const gchar * path);
449 gpointer
450 kvp_frame_get_binary (const KvpFrame * frame, const gchar * path,
451  guint64 * size_return);
452 
453 gboolean
454 kvp_frame_get_boolean (const KvpFrame * frame, const gchar * path);
455 
456 QofTime *
457 kvp_frame_get_time (const KvpFrame * frame, const gchar *path);
458 
459 KvpValue *kvp_frame_get_value (const KvpFrame * frame, const gchar * path);
460 
469 KvpFrame *kvp_frame_get_frame (const KvpFrame * frame, const gchar * path);
470 
475 KvpFrame *
476 kvp_frame_get_frame_path (KvpFrame * frame, const gchar *, ...);
477 
482 KvpFrame *
483 kvp_frame_get_frame_gslist (KvpFrame * frame, GSList * key_path);
484 
496 KvpFrame *kvp_frame_get_frame_slash (KvpFrame * frame, const gchar * path);
497 
520 KvpValue *
521 kvp_frame_replace_slot_nc (KvpFrame * frame, const gchar * slot,
522  KvpValue * new_value);
523 
524 
531 void kvp_frame_set_slot (KvpFrame * frame,
532  const gchar * key, const KvpValue * value);
541 void kvp_frame_set_slot_nc (KvpFrame * frame,
542  const gchar * key, KvpValue * value);
543 
549 void kvp_frame_set_slot_path (KvpFrame * frame,
550  const KvpValue * value,
551  const gchar * first_key, ...);
552 
559  const KvpValue * value,
560  GSList * key_path);
561 
578 KvpValue *kvp_frame_get_slot (const KvpFrame * frame, const gchar * key);
579 
584  const gchar * first_key, ...);
585 
590  GSList * key_path);
591 
600 gint kvp_glist_compare (const GList * list1, const GList * list2);
601 
607 GList *kvp_glist_copy (const GList * list);
608 
614 void kvp_glist_delete (GList * list);
615 
616 
625 KvpValue *kvp_value_new_gint64 (gint64 value);
626 KvpValue *kvp_value_new_double (double value);
627 
628 KvpValue *kvp_value_new_numeric (QofNumeric value);
629 KvpValue *kvp_value_new_string (const gchar * value);
630 KvpValue *kvp_value_new_guid (const GUID * guid);
631 KvpValue *kvp_value_new_time (QofTime *value);
633 KvpValue *kvp_value_new_boolean (gboolean value);
634 
635 KvpValue *kvp_value_new_binary (const void *data, guint64 datasize);
636 KvpValue *kvp_value_new_frame (const KvpFrame * value);
637 
640 KvpValue *kvp_value_new_glist (const GList * value);
641 
644 KvpValue *kvp_value_new_binary_nc (void *data, guint64 datasize);
645 
652 KvpValue *kvp_value_new_glist_nc (GList * lst);
653 
657 
659 void kvp_value_delete (KvpValue * value);
660 
662 KvpValue *kvp_value_copy (const KvpValue * value);
663 
666 
668 GList *kvp_value_replace_glist_nc (KvpValue * value, GList * newlist);
669 
678 KvpValueType kvp_value_get_type (const KvpValue * value);
679 
695 gint64 kvp_value_get_gint64 (const KvpValue * value);
696 gdouble kvp_value_get_double (const KvpValue * value);
697 QofNumeric kvp_value_get_numeric (const KvpValue * value);
698 
701 gchar *
702 kvp_value_get_string (const KvpValue * value);
703 
706 GUID *
707 kvp_value_get_guid (const KvpValue * value);
708 
711 gpointer
712 kvp_value_get_binary (const KvpValue * value, guint64 * size_return);
713 
717 GList *
718 kvp_value_get_glist (const KvpValue * value);
719 
722 KvpFrame *
723 kvp_value_get_frame (const KvpValue * value);
724 
725 
726 gboolean
727 kvp_value_get_boolean (const KvpValue * value);
728 
729 QofTime*
730 kvp_value_get_time (const KvpValue * value);
731 
735 gint
736 kvp_value_compare (const KvpValue * va, const KvpValue * vb);
737 
744 gchar *
745 kvp_value_to_bare_string (const KvpValue * val);
746 
752 gchar *
753 kvp_value_to_string (const KvpValue * val);
754 
758 gboolean
759 kvp_value_binary_append (KvpValue * v, gpointer data, guint64 size);
760 
766 typedef void (*KvpValueForeachCB) (const gchar *key, KvpValue * value, gpointer data);
767 
772 void
774 
778 #endif
GUID * kvp_value_get_guid(const KvpValue *value)
Definition: kvpframe.c:1474
KvpFrame * kvp_frame_get_frame_path(KvpFrame *frame, const gchar *,...)
Definition: kvpframe.c:1021
void kvp_frame_add_time(KvpFrame *frame, const gchar *path, QofTime *qt)
Add the value of the QofTime to the glist bag.
Definition: kvpframe.c:619
gboolean kvp_value_binary_append(KvpValue *v, gpointer data, guint64 size)
GList * kvp_value_replace_glist_nc(KvpValue *value, GList *newlist)
Definition: kvpframe.c:1578
GList * kvp_glist_copy(const GList *list)
Definition: kvpframe.c:1145
void kvp_frame_set_guid(KvpFrame *frame, const gchar *path, const GUID *guid)
Store a copy of the GUID at the indicated path.
Definition: kvpframe.c:450
KvpValueType
possible types in the union KvpValue
Definition: kvpframe.h:87
An exact-rational-number library for QOF.
void kvp_frame_set_numeric(KvpFrame *frame, const gchar *path, QofNumeric nval)
store the value of the QofNumeric at the indicated path.
Definition: kvpframe.c:417
Unique identifier.
Definition: kvpframe.h:118
void kvp_frame_set_frame_nc(KvpFrame *frame, const gchar *path, KvpFrame *chld)
Store a KvpFrame at the indicated path without copying.
Definition: kvpframe.c:471
void kvp_frame_set_time(KvpFrame *frame, const gchar *path, QofTime *qt)
Store a copy of the QofTime at the indicated path.
Definition: kvpframe.c:407
KvpFrame * kvp_frame_add_value(KvpFrame *frame, const gchar *path, KvpValue *value)
Add a copy of the value to the glist bag.
Definition: kvpframe.c:578
void kvp_frame_add_frame_nc(KvpFrame *frame, const gchar *path, KvpFrame *chld)
Add the frame to the glist bag without copying.
Definition: kvpframe.c:669
KvpFrame * kvp_frame_get_frame_slash(KvpFrame *frame, const gchar *path)
Definition: kvpframe.c:1042
KvpFrame * kvp_frame_copy(const KvpFrame *frame)
Definition: kvpframe.c:153
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
globally unique ID User API
void kvp_frame_set_slot_path(KvpFrame *frame, const KvpValue *value, const gchar *first_key,...)
Definition: kvpframe.c:723
gint kvp_glist_compare(const GList *list1, const GList *list2)
Definition: kvpframe.c:1167
void kvp_frame_set_gint64(KvpFrame *frame, const gchar *path, gint64 ival)
store the value of the gint64 at the indicated path.
Definition: kvpframe.c:387
KvpValue * kvp_value_new_boolean(gboolean value)
Definition: kvpframe.c:1223
gboolean kvp_frame_is_empty(KvpFrame *frame)
Definition: kvpframe.c:134
KvpValue * kvp_value_new_frame_nc(KvpFrame *value)
Definition: kvpframe.c:1345
void kvp_frame_set_slot_path_gslist(KvpFrame *frame, const KvpValue *value, GSList *key_path)
Definition: kvpframe.c:776
KvpFrame * kvp_frame_get_frame_gslist(KvpFrame *frame, GSList *key_path)
Definition: kvpframe.c:999
KvpFrame * kvp_frame_set_value(KvpFrame *frame, const gchar *path, const KvpValue *value)
Copy the KvpValue into the frame.
Definition: kvpframe.c:496
gpointer kvp_value_get_binary(const KvpValue *value, guint64 *size_return)
Definition: kvpframe.c:1504
128bit denominator/numerator maths.
Definition: kvpframe.h:106
void kvp_frame_delete(KvpFrame *frame)
Definition: kvpframe.c:115
gint64 kvp_value_get_gint64(const KvpValue *value)
Definition: kvpframe.c:1399
KvpValue * kvp_frame_replace_value_nc(KvpFrame *frame, const gchar *slot, KvpValue *new_value)
Definition: kvpframe.c:513
void kvp_frame_set_frame(KvpFrame *frame, const gchar *path, KvpFrame *chld)
Store a copy of the KvpFrame at the indicated path.
Definition: kvpframe.c:461
void(* KvpValueForeachCB)(const gchar *key, KvpValue *value, gpointer data)
Definition: kvpframe.h:766
struct _KvpValue KvpValue
Definition: kvpframe.h:78
KvpValue * kvp_frame_replace_slot_nc(KvpFrame *frame, const gchar *slot, KvpValue *new_value)
Definition: kvpframe.c:175
void kvp_frame_set_slot(KvpFrame *frame, const gchar *key, const KvpValue *value)
Definition: kvpframe.c:681
KvpValue * kvp_value_copy(const KvpValue *value)
Definition: kvpframe.c:1598
KvpValue * kvp_value_new_binary_nc(void *data, guint64 datasize)
64bit integer
Definition: kvpframe.h:94
void kvp_frame_add_double(KvpFrame *frame, const gchar *path, gdouble dval)
Add the value of the double to the glist bag.
Definition: kvpframe.c:598
void kvp_frame_set_slot_nc(KvpFrame *frame, const gchar *key, KvpValue *value)
Definition: kvpframe.c:697
void kvp_frame_set_boolean(KvpFrame *frame, const gchar *path, gboolean val)
Store the value of the boolean at the indicated path.
Definition: kvpframe.c:428
GList * kvp_value_get_glist(const KvpValue *value)
Definition: kvpframe.c:1531
gchar * kvp_value_to_bare_string(const KvpValue *val)
General purpose function to convert any KvpValue to a string.
Definition: kvpframe.c:1834
KvpFrame * kvp_value_replace_frame_nc(KvpValue *value, KvpFrame *newframe)
Definition: kvpframe.c:1561
void kvp_glist_delete(GList *list)
Definition: kvpframe.c:1127
gchar * kvp_value_get_string(const KvpValue *value)
Definition: kvpframe.c:1444
void kvp_frame_add_frame(KvpFrame *frame, const gchar *path, KvpFrame *chld)
Copy the frame to the glist bag at the indicated path.
Definition: kvpframe.c:659
void kvp_frame_add_string(KvpFrame *frame, const gchar *path, const gchar *str)
Copy the string to the glist bag at the indicated path.
Definition: kvpframe.c:639
KvpValue * kvp_frame_get_slot_path(KvpFrame *frame, const gchar *first_key,...)
Definition: kvpframe.c:1057
64bit UTC Time handling routines
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:483
void kvp_frame_for_each_slot(KvpFrame *f, KvpValueForeachCB, gpointer data)
Definition: kvpframe.c:1642
Definition: guid.h:53
KvpValue * kvp_value_new_glist(const GList *value)
Definition: kvpframe.c:1306
KvpValue * kvp_value_new_glist_nc(GList *lst)
Definition: kvpframe.c:1319
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:112
Simple boolean type.
Definition: kvpframe.h:136
void kvp_frame_add_gint64(KvpFrame *frame, const gchar *path, gint64 ival)
add the value of the gint64 to the glist bag
Definition: kvpframe.c:588
standard C string
Definition: kvpframe.h:112
void kvp_frame_set_double(KvpFrame *frame, const gchar *path, gdouble dval)
store the value of the double at the indicated path.
Definition: kvpframe.c:397
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:97
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1546
standard C double type
Definition: kvpframe.h:100
KvpFrame * kvp_frame_get_frame(const KvpFrame *frame, const gchar *path)
Definition: kvpframe.c:981
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1358
KvpValue * kvp_frame_get_slot_path_gslist(KvpFrame *frame, GSList *key_path)
Definition: kvpframe.c:1095
gint kvp_value_compare(const KvpValue *va, const KvpValue *vb)
Definition: kvpframe.c:1654
gchar * kvp_value_to_string(const KvpValue *val)
Debug version.
Definition: kvpframe.c:1917
QOF utility functions.
void kvp_frame_set_string(KvpFrame *frame, const gchar *path, const gchar *str)
Store a copy of the string at the indicated path.
Definition: kvpframe.c:439
void kvp_frame_add_numeric(KvpFrame *frame, const gchar *path, QofNumeric nval)
Add the value of the QofNumeric to the glist bag.
Definition: kvpframe.c:608
64bit time/date handling.
Definition: kvpframe.h:124
void kvp_frame_add_guid(KvpFrame *frame, const gchar *path, const GUID *guid)
Copy the GUID to the glist bag at the indicated path.
Definition: kvpframe.c:649