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 \********************************************************************/ 22 /** @addtogroup KVP 23 24 * A KvpFrame is a set of associations between character strings 25 * (keys) and KvpValue structures. A KvpValue is a union with 26 * possible types enumerated in the KvpValueType enum, and includes, 27 * among other things, ints, doubles, strings, guid's, lists, time 28 * and numeric values. KvpValues may also be other frames, so 29 * KVP is inherently hierarchical. 30 * 31 * Values are stored in a 'slot' associated with a key. 32 * Pointers passed as arguments into set_slot and get_slot are the 33 * responsibility of the caller. Pointers returned by get_slot are 34 * owned by the kvp_frame. Make copies as needed. 35 * 36 * A 'path' is a sequence of keys that can be followed to a value. 37 * Paths may be specified as varargs (variable number of arguments 38 * to a subrutine, NULL-terminated), as a GSList, or as a standard 39 * URL-like path name. The later is parsed and treated in the same 40 * way as file paths would be: / separates keys, /./ is treated as / 41 * and /../ means backup one level. Repeated slashes are treated 42 * as one slash. 43 * 44 * Note that although, in principle, keys may contain the / and . and 45 * .. characters, doing so may lead to confusion, and will make 46 * path-string parsing routines fail. In other words, don't use 47 * a key such as 'some/key' or 'some/./other/../key' because you 48 * may get unexpected results. 49 * 50 * To set a value into a frame, you will want to use one of the 51 * kvp_frame_set_xxx() routines. Most of the other routines provide 52 * only low-level access that you probably shouldn't use. 53 54 @{ 55 */ 56 /** @file kvpframe.h 57 @brief A key-value frame system 58 @author Copyright (C) 2000 Bill Gribble 59 @author Copyright (C) 2003 Linas Vepstas <linas@linas.org> 60 @author Copyright (c) 2006 Neil Williams <linux@codehelp.co.uk> 61 */ 62 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 73 /** Opaque frame structure */ 74 typedef struct _KvpFrame KvpFrame; 75 76 /** A KvpValue is a union with possible types enumerated in the 77 * KvpValueType enum. */ 78 typedef struct _KvpValue KvpValue; 79 80 /** \brief possible types in the union KvpValue 81 82 \todo In the long run, this could be synchronised with the 83 core QOF types, which in turn may or may not be synced to the 84 GValue types in GLib. The QOF types currently unsupported 85 are KVP_TYPE_GLIST and KVP_TYPE_BINARY. 86 */ 87 typedef enum 88 { 89 /** \brief 64bit integer 90 - QofType : QOF_TYPE_INT64 91 - GType : G_TYPE_INT64 92 - GLib type : gint64 93 */ 94 KVP_TYPE_GINT64 = 1, 95 /** \brief standard C double type 96 - QofType : QOF_TYPE_DOUBLE 97 - GType : G_TYPE_DOUBLE 98 - GLib type : gdouble 99 */ 100 KVP_TYPE_DOUBLE, 101 /** \brief 128bit denominator/numerator maths. 102 - QofType : QOF_TYPE_NUMERIC 103 - GType : no direct equivalent, consider QOF_TYPE_DOUBLE 104 - GLib type : no direct equivalent, consider QOF_TYPE_DOUBLE 105 */ 106 KVP_TYPE_NUMERIC, 107 /** \brief standard C string 108 - QofType : QOF_TYPE_STRING 109 - GType : G_TYPE_STRING 110 - GLib type : gchar* 111 */ 112 KVP_TYPE_STRING, 113 /** \brief Unique identifier. 114 - QofType : QOF_TYPE_GUID 115 - GType : no direct equivalent, can be stored as QOF_TYPE_STRING 116 - GLib : no direct equivalent, can be stored as QOF_TYPE_STRING 117 */ 118 KVP_TYPE_GUID, 119 /** \brief 64bit time/date handling. 120 - QofType : QOF_TYPE_TIME 121 - GType : No equivalent. 122 - GLib type : GDate (not fully equivalent, see ::QofTime) 123 */ 124 KVP_TYPE_TIME, 125 /** no QofType/GType/GLib equivalent. */ 126 KVP_TYPE_BINARY, 127 /** no QofType/GType equivalent. */ 128 KVP_TYPE_GLIST, 129 /** no QofType/GType/GLib equivalent. */ 130 KVP_TYPE_FRAME, 131 /** \brief Simple boolean type. 132 - QofType : QOF_TYPE_BOOLEAN 133 - GType : G_TYPE_BOOLEAN 134 - GLib type : gboolean 135 */ 136 KVP_TYPE_BOOLEAN 137 } KvpValueType; 138 139 /** @name KvpFrame Constructors 140 @{ 141 */ 142 143 /** Return a new empty instance of KvpFrame */ 144 KvpFrame * 145 kvp_frame_new (void); 146 147 /** Perform a deep (recursive) delete of the frame and any subframes. */ 148 void 149 kvp_frame_delete (KvpFrame * frame); 150 151 /** Perform a deep (recursive) value copy, copying the frame, 152 * subframes, and the values as well. */ 153 KvpFrame * 154 kvp_frame_copy (const KvpFrame * frame); 155 156 /** Return TRUE if the KvpFrame is empty */ 157 gboolean 158 kvp_frame_is_empty (KvpFrame * frame); 159 160 /** @} */ 161 162 /** @name KvpFrame Basic Value Storing 163 @{ 164 */ 165 166 /** \brief store the value of the gint64 at the indicated path. 167 168 If not all frame components of the path exist, they are created. 169 */ 170 void 171 kvp_frame_set_gint64 (KvpFrame * frame, const gchar * path, gint64 ival); 172 173 /** \brief store the value of the double at the indicated path. 174 175 If not all frame components of the path exist, they are created. 176 */ 177 void 178 kvp_frame_set_double (KvpFrame * frame, const gchar * path, gdouble dval); 179 180 /** \brief store the value of the QofNumeric at the indicated path. 181 182 If not all frame components of the path exist, they are created. 183 */ 184 void 185 kvp_frame_set_numeric (KvpFrame * frame, const gchar * path, 186 QofNumeric nval); 187 188 /** \brief Store a copy of the string at the indicated path. 189 190 If not all frame components of the path exist, they are created. 191 If there was another string previously stored at that path, 192 the old copy is deleted. 193 */ 194 void 195 kvp_frame_set_string (KvpFrame * frame, const gchar * path, 196 const gchar *str); 197 198 /** \brief Store a copy of the GUID at the indicated path. 199 200 If not all frame components of the path exist, they are created. 201 If there was another GUID previously stored at that path, 202 the old copy is deleted. 203 */ 204 void 205 kvp_frame_set_guid (KvpFrame * frame, const gchar * path, 206 const GUID * guid); 207 208 /** \brief Store a copy of the QofTime at the indicated path. 209 210 If not all frame components of the path exist, they are created. 211 If there was another QofTime previously stored at that path, 212 the old copy is deleted. 213 */ 214 void 215 kvp_frame_set_time (KvpFrame * frame, const gchar *path, QofTime *qt); 216 217 /** \brief Store the value of the boolean at the indicated path. 218 219 If not all frame components of the path exist, they are created. 220 */ 221 void 222 kvp_frame_set_boolean (KvpFrame * frame, const gchar * path, gboolean val); 223 224 /** \brief Store a copy of the KvpFrame at the indicated path. 225 226 If not all frame components of the path exist, they are created. 227 If there was another QofTime previously stored at that path, 228 the old frame is deleted. 229 */ 230 void 231 kvp_frame_set_frame (KvpFrame * frame, const gchar * path, 232 KvpFrame * chld); 233 234 /** \brief Store a KvpFrame at the indicated path without copying. 235 236 If not all frame components of the path exist, they are created. 237 If there was another QofTime previously stored at that path, 238 the old frame is deleted. 239 */ 240 void kvp_frame_set_frame_nc (KvpFrame * frame, const gchar * path, 241 KvpFrame * chld); 242 243 /** \brief Copy the KvpValue into the frame 244 245 If the path contains slashes '/', these are assumed to represent 246 a sequence of keys. The old value at this location, if any, 247 is destroyed. 248 249 Pointers passed as arguments into this routine remain 250 the responsibility of the caller. 251 252 \param frame The frame to hold the copied value. 253 \param path The location of the value in the frame. 254 \param value The value to be copied. 255 256 \return a pointer to the actual frame into which the value 257 was inserted or NULL if the frame could not be found. 258 */ 259 KvpFrame * 260 kvp_frame_set_value (KvpFrame * frame, const gchar * path, 261 const KvpValue * value); 262 263 /** \brief Store the KvpValue in the frame without copying 264 265 If the path contains slashes '/', these are assumed to 266 represent a sequence of keys. 267 268 * The returned value is a pointer to the actual frame into which the value 269 * was inserted; it is NULL if the frame couldn't be found (and thus the 270 * value wasn't inserted). The old value at this location, if any, 271 * is destroyed. 272 * 273 * This routine is handy for avoiding excess memory allocations & frees. 274 * Note that because the KvpValue was grabbed, you can't just delete 275 * unless you remove the key as well (or unless you replace the value). 276 */ 277 KvpFrame * 278 kvp_frame_set_value_nc (KvpFrame * frame, const gchar * path, KvpValue * value); 279 280 /** The kvp_frame_replace_value_nc() routine places the new value 281 * at the indicated path. It returns the old value, if any. 282 * It returns NULL if there was an error, or if there was no 283 * old value. If the path doesn't exist, it is created, unless 284 * new_value is NULL. Passing in a NULL new_value has the 285 * effect of deleting the trailing slot (i.e. the trailing path 286 * element). 287 */ 288 KvpValue * 289 kvp_frame_replace_value_nc (KvpFrame * frame, const gchar * slot, 290 KvpValue * new_value); 291 /** @} */ 292 293 /** @name KvpFrame Glist Bag Storing 294 @{ 295 */ 296 297 /** \brief add the value of the gint64 to the glist bag 298 299 If not all frame components of the path exist, they are 300 created. If the value previously stored at this path was 301 not a glist bag, then a bag will be formed there, the old 302 value placed in the bag, and the new value added to the bag. 303 */ 304 void 305 kvp_frame_add_gint64 (KvpFrame * frame, const gchar * path, gint64 ival); 306 307 /** \brief Add the value of the double to the glist bag 308 309 If not all frame components of the path exist, they are 310 created. If the value previously stored at this path was 311 not a glist bag, then a bag will be formed there, the old 312 value placed in the bag, and the new value added to the bag. 313 */ 314 void 315 kvp_frame_add_double (KvpFrame * frame, const gchar * path, gdouble dval); 316 317 /** \brief Add the value of the QofNumeric to the glist bag. 318 319 If not all frame components of the path exist, they are 320 created. If the value previously stored at this path was 321 not a glist bag, then a bag will be formed there, the old 322 value placed in the bag, and the new value added to the bag. 323 */ 324 void 325 kvp_frame_add_numeric (KvpFrame * frame, const gchar * path, 326 QofNumeric nval); 327 328 /** \brief Add the value of the QofTime to the glist bag 329 330 If not all frame components of the path exist, they are 331 created. If the value previously stored at this path was 332 not a glist bag, then a bag will be formed there, the old 333 value placed in the bag, and the new value added to the bag. 334 */ 335 void 336 kvp_frame_add_time (KvpFrame * frame, const gchar *path, QofTime *qt); 337 338 /** \brief Copy the string to the glist bag at the indicated path. 339 340 If not all frame components of the path exist, they are created. 341 If there was another item previously stored at that path, then the 342 path is converted to a bag, and the old value, along with the new 343 value, is added to the bag. 344 345 */ 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 352 /** \brief Copy the GUID to the glist bag at the indicated path. 353 354 If not all frame components of the path exist, they are created. 355 If there was another item previously stored at that path, then the 356 path is converted to a bag, and the old value, along with the new 357 value, is added to the bag. 358 */ 359 void kvp_frame_add_guid (KvpFrame * frame, const gchar * path, 360 const GUID * guid); 361 362 /** \brief Copy the frame to the glist bag at the indicated path. 363 364 If not all frame components of the path exist, they are created. 365 If there was another item previously stored at that path, then the 366 path is converted to a bag, and the old value, along with the new 367 value, is added to the bag. 368 */ 369 void kvp_frame_add_frame (KvpFrame * frame, const gchar * path, 370 KvpFrame * chld); 371 /** \brief Add the frame to the glist bag \b without copying. 372 373 If not all frame components of the path exist, they are created. 374 If there was another item previously stored at that path, then the 375 path is converted to a bag, and the old value, along with the new 376 value, is added to the bag. 377 */ 378 void kvp_frame_add_frame_nc (KvpFrame * frame, const gchar * path, 379 KvpFrame * chld); 380 381 /** \brief Add a copy of the value to the glist bag 382 383 If not all frame components of the path exist, they are created. 384 If there was another item previously stored at that path, then the 385 path is converted to a bag, and the old value, along with the new 386 value, is added to the bag. This routine returns the pointer to the 387 last frame (the actual frame to which the value was added), or NULL 388 if there was an error of any sort (typically, a parse error in the path). 389 */ 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 408 /** @} */ 409 410 /** @name KvpFrame Value Fetching 411 412 Value accessors. These all take a unix-style slash-separated 413 path as an argument, and return the value stored at that location. 414 If the object at the end of that path is not of the type that was 415 asked for, then a NULL or a zero is returned. So, for example, 416 asking for a string when the path stored an int will return a NULL. 417 In some future date, this may be changed to a looser type system, 418 such as perl's automatic re-typing (e.g. an integer value might be 419 converted to a printed string representing that value). 420 421 If any part of the path does not exist, then NULL or zero will be 422 returned. 423 424 The values returned for GUID, binary, GList, KvpFrame and string 425 are "non-copying" -- the returned item is the actual item stored. 426 Do not delete this item unless you take the required care to avoid 427 possible bad pointer derefrences (i.e. core dumps). Also, be 428 careful hanging on to those references if you are also storing 429 at the same path names: the referenced item will be freed during 430 the store. 431 432 That is, if you get a string value (or guid, binary or frame), 433 and then store something else at that path, the string that you've 434 gotten will be freed during the store (internally, by the set_*() 435 routines), and you will be left hanging onto an invalid pointer. 436 @{ 437 */ 438 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 461 /** Value accessor. Takes a unix-style slash-separated path as an 462 * argument, and return the KvpFrame stored at that location. If the 463 * KvpFrame does not exist, then a NULL is returned. 464 * 465 * 466 * @return The KvpFrame at the specified path, or NULL if it doesn't 467 * exist. 468 */ 469 KvpFrame *kvp_frame_get_frame (const KvpFrame * frame, const gchar * path); 470 471 /** This routine returns the last frame of the path. 472 * If the frame path doesn't exist, it is created. 473 * Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame() 474 */ 475 KvpFrame * 476 kvp_frame_get_frame_path (KvpFrame * frame, const gchar *, ...); 477 478 /** This routine returns the last frame of the path. 479 * If the frame path doesn't exist, it is created. 480 * Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame() 481 */ 482 KvpFrame * 483 kvp_frame_get_frame_gslist (KvpFrame * frame, GSList * key_path); 484 485 /** This routine returns the last frame of the path. 486 * If the frame path doesn't exist, it is created. 487 * Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame() 488 * 489 * The kvp_frame_get_frame_slash() routine takes a single string 490 * where the keys are separated by slashes; thus, for example: 491 * /this/is/a/valid/path and///so//is////this/ 492 * Multiple slashes are compresed. Leading slash is optional. 493 * The pointers . and .. are *not* currently followed/obeyed. 494 * (This is a bug that needs fixing). 495 */ 496 KvpFrame *kvp_frame_get_frame_slash (KvpFrame * frame, const gchar * path); 497 498 /** @} */ 499 /** @name KvpFrame KvpValue low-level storing routines. 500 501 You probably shouldn't be using these low-level routines 502 503 All of the kvp_frame_set_slot_*() routines set the slot values 504 "destructively", in that if there was an old value there, that 505 old value is destroyed (and the memory freed). Thus, one 506 should not hang on to value pointers, as these will get 507 trashed if set_slot is called on the corresponding key. 508 509 If you want the old value, use kvp_frame_replace_slot(). 510 @{ 511 */ 512 513 /** The kvp_frame_replace_slot_nc() routine places the new value into 514 * the indicated frame, for the given key. It returns the old 515 * value, if any. It returns NULL if the slot doesn't exist, 516 * if there was some other an error, or if there was no old value. 517 * Passing in a NULL new_value has the effect of deleting that 518 * slot. 519 */ 520 KvpValue * 521 kvp_frame_replace_slot_nc (KvpFrame * frame, const gchar * slot, 522 KvpValue * new_value); 523 524 525 /** The kvp_frame_set_slot() routine copies the value into the frame, 526 * associating it with a copy of 'key'. Pointers passed as arguments 527 * into kvp_frame_set_slot are the responsibility of the caller; 528 * the pointers are *not* taken over or managed. The old value at 529 * this location, if any, is destroyed. 530 */ 531 void kvp_frame_set_slot (KvpFrame * frame, 532 const gchar * key, const KvpValue * value); 533 /** 534 * The kvp_frame_set_slot_nc() routine puts the value (without copying 535 * it) into the frame, associating it with a copy of 'key'. This 536 * routine is handy for avoiding excess memory allocations & frees. 537 * Note that because the KvpValue was grabbed, you can't just delete 538 * unless you remove the key as well (or unless you replace the value). 539 * The old value at this location, if any, is destroyed. 540 */ 541 void kvp_frame_set_slot_nc (KvpFrame * frame, 542 const gchar * key, KvpValue * value); 543 544 /** The kvp_frame_set_slot_path() routine walks the hierarchy, 545 * using the key values to pick each branch. When the terminal 546 * node is reached, the value is copied into it. The old value 547 * at this location, if any, is destroyed. 548 */ 549 void kvp_frame_set_slot_path (KvpFrame * frame, 550 const KvpValue * value, 551 const gchar * first_key, ...); 552 553 /** The kvp_frame_set_slot_path_gslist() routine walks the hierarchy, 554 * using the key values to pick each branch. When the terminal node 555 * is reached, the value is copied into it. The old value at this 556 * location, if any, is destroyed. 557 */ 558 void kvp_frame_set_slot_path_gslist (KvpFrame * frame, 559 const KvpValue * value, 560 GSList * key_path); 561 562 /** @} */ 563 564 /** @name KvpFrame KvpValue Low-Level Retrieval Routines 565 566 You probably shouldn't be using these low-level routines 567 568 Returns the KvpValue in the given KvpFrame 'frame' that is 569 associated with 'key'. If there is no key in the frame, NULL 570 is returned. If the value associated with the key is NULL, 571 NULL is returned. 572 573 Pointers passed as arguments into get_slot are the responsibility 574 of the caller. Pointers returned by get_slot are owned by the 575 kvp_frame. Make copies as needed. 576 @{ 577 */ 578 KvpValue *kvp_frame_get_slot (const KvpFrame * frame, const gchar * key); 579 580 /** This routine return the value at the end of the 581 * path, or NULL if any portion of the path doesn't exist. 582 */ 583 KvpValue *kvp_frame_get_slot_path (KvpFrame * frame, 584 const gchar * first_key, ...); 585 586 /** This routine return the value at the end of the 587 * path, or NULL if any portion of the path doesn't exist. 588 */ 589 KvpValue *kvp_frame_get_slot_path_gslist (KvpFrame * frame, 590 GSList * key_path); 591 592 /** @} */ 593 594 /** 595 kvp_glist_compare() compares <b>GLists of KvpValue values</b> (not to 596 be confused with GLists of something else): it iterates over 597 the list elements, performing a kvp_value_compare on each. 598 @{ 599 */ 600 gint kvp_glist_compare (const GList * list1, const GList * list2); 601 602 /** kvp_glist_copy() performs a deep copy of a <b>GList of 603 * kvp_values</b> (not to be confused with GLists of something 604 * else): same as mapping kvp_value_copy() over the elements and 605 * then copying the spine. 606 */ 607 GList *kvp_glist_copy (const GList * list); 608 609 /** kvp_glist_delete() performs a deep delete of a <b>GList of 610 * kvp_values</b> (not to be confused with GLists of something 611 * else): same as mapping * kvp_value_delete() over the elements 612 * and then deleting the GList. 613 */ 614 void kvp_glist_delete (GList * list); 615 616 617 /** @name KvpValue Constructors 618 619 The following routines are constructors for kvp_value. 620 Those with pointer arguments copy in the value. 621 The *_nc() versions do *not* copy in their values, 622 but use them directly. 623 @{ 624 */ 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); 632 /** \since 0.7.2 */ 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 638 /** Creates a KvpValue from a <b>GList of kvp_value's</b>! (Not to be 639 * confused with GList's of something else!) */ 640 KvpValue *kvp_value_new_glist (const GList * value); 641 642 /** value constructors (non-copying - KvpValue takes pointer ownership) 643 values *must* have been allocated via glib allocators! (gnew, etc.) */ 644 KvpValue *kvp_value_new_binary_nc (void *data, guint64 datasize); 645 646 /** Creates a KvpValue from a <b>GList of kvp_value's</b>! (Not to be 647 * confused with GList's of something else!) 648 * 649 * This value constructor is non-copying (KvpValue takes pointer 650 * ownership). The values *must* have been allocated via glib 651 * allocators! (gnew, etc.) */ 652 KvpValue *kvp_value_new_glist_nc (GList * lst); 653 654 /** value constructors (non-copying - KvpValue takes pointer ownership) 655 values *must* have been allocated via glib allocators! (gnew, etc.) */ 656 KvpValue *kvp_value_new_frame_nc (KvpFrame * value); 657 658 /** This is a deep (recursive) delete. */ 659 void kvp_value_delete (KvpValue * value); 660 661 /** This is a deep value copy. */ 662 KvpValue *kvp_value_copy (const KvpValue * value); 663 664 /** Replace old frame value with new, return old frame */ 665 KvpFrame *kvp_value_replace_frame_nc (KvpValue * value, KvpFrame * newframe); 666 667 /** Replace old glist value with new, return old glist */ 668 GList *kvp_value_replace_glist_nc (KvpValue * value, GList * newlist); 669 670 /** @} */ 671 672 673 /** @name KvpValue Value access 674 675 @{ 676 */ 677 678 KvpValueType kvp_value_get_type (const KvpValue * value); 679 680 /** Value accessors. Those for GUID, binary, GList, KvpFrame and 681 * string are non-copying -- the caller can modify the value 682 * directly. Just don't free it, or you screw up everything. 683 * Note that if another value is stored at the key location 684 * that this value came from, then this value will be 685 * uncermoniously deleted, and you will be left pointing to 686 * garbage. So don't store values at the same time you are 687 * examining their contents. 688 689 \todo kvp_value_get_ functions need to set QofError so that 690 users can check that a NULL or zero value is actually a 691 real value and not an error result. 692 693 */ 694 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 699 /** Value accessor. This one is non-copying -- the caller can modify 700 * the value directly. */ 701 gchar * 702 kvp_value_get_string (const KvpValue * value); 703 704 /** Value accessor. This one is non-copying -- the caller can modify 705 * the value directly. */ 706 GUID * 707 kvp_value_get_guid (const KvpValue * value); 708 709 /** Value accessor. This one is non-copying -- the caller can modify 710 * the value directly. */ 711 gpointer 712 kvp_value_get_binary (const KvpValue * value, guint64 * size_return); 713 714 /** Returns the GList of kvp_frame's (not to be confused with GList's 715 * of something else!) from the given kvp_frame. This one is 716 * non-copying -- the caller can modify the value directly. */ 717 GList * 718 kvp_value_get_glist (const KvpValue * value); 719 720 /** Value accessor. This one is non-copying -- the caller can modify 721 * the value directly. */ 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 732 /** 733 * Similar returns as strcmp. 734 **/ 735 gint 736 kvp_value_compare (const KvpValue * va, const KvpValue * vb); 737 738 /** @} */ 739 740 /** \brief General purpose function to convert any KvpValue to a string. 741 742 Only the bare string is returned, there is no debugging information. 743 */ 744 gchar * 745 kvp_value_to_bare_string (const KvpValue * val); 746 747 /** \brief Debug version 748 749 This version is used only by ::qof_query_printValueForParam, 750 itself a debugging and development utility function. 751 */ 752 gchar * 753 kvp_value_to_string (const KvpValue * val); 754 755 /** Manipulator: 756 * 757 * copying - but more efficient than creating a new KvpValue manually. */ 758 gboolean 759 kvp_value_binary_append (KvpValue * v, gpointer data, guint64 size); 760 761 /** @name Iterators 762 @{ 763 */ 764 765 /** \since 0.7.2 */ 766 typedef void (*KvpValueForeachCB) (const gchar *key, KvpValue * value, gpointer data); 767 768 /** Traverse all of the slots in the given kvp_frame. This function 769 does not descend recursively to traverse any kvp_frames stored as 770 slot values. You must handle that in proc, with a suitable 771 recursive call if desired. */ 772 void 773 kvp_frame_for_each_slot (KvpFrame * f, KvpValueForeachCB, gpointer data); 774 775 /** @} */ 776 777 /** @} */ 778 #endif 779