kvpframe.h File Reference

Detailed Description

A key-value frame system.

Copyright (C) 2000 Bill Gribble

Copyright (C) 2003 Linas Vepstas <linas@linas.org>

Copyright (c) 2006 Neil Williams <linux@codehelp.co.uk>

Definition in file kvpframe.h.

#include "qofnumeric.h"
#include "guid.h"
#include "qoftime.h"
#include "qofutil.h"

Go to the source code of this file.


typedef void(* KvpValueForeachCB )(const gchar *key, KvpValue *value, gpointer data)
void kvp_frame_for_each_slot (KvpFrame *f, KvpValueForeachCB, gpointer data)


#define QOF_MOD_KVP   "qof-kvp"


typedef struct _KvpFrame KvpFrame
typedef struct _KvpValue KvpValue


enum  KvpValueType {
 possible types in the union KvpValue More...


gchar * kvp_value_to_bare_string (const KvpValue *val)
 General purpose function to convert any KvpValue to a string.
gchar * kvp_value_to_string (const KvpValue *val)
 Debug version.
gboolean kvp_value_binary_append (KvpValue *v, gpointer data, guint64 size)
KvpFrame Constructors
KvpFramekvp_frame_new (void)
void kvp_frame_delete (KvpFrame *frame)
KvpFramekvp_frame_copy (const KvpFrame *frame)
gboolean kvp_frame_is_empty (KvpFrame *frame)
KvpFrame Basic Value Storing
void kvp_frame_set_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
 store the value of the gint64 at the indicated path.
void kvp_frame_set_double (KvpFrame *frame, const gchar *path, gdouble dval)
 store the value of the double at the indicated path.
void kvp_frame_set_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
 store the value of the QofNumeric at the indicated path.
void kvp_frame_set_string (KvpFrame *frame, const gchar *path, const gchar *str)
 Store a copy of the string at the indicated path.
void kvp_frame_set_guid (KvpFrame *frame, const gchar *path, const GUID *guid)
 Store a copy of the GUID at the indicated path.
void kvp_frame_set_time (KvpFrame *frame, const gchar *path, QofTime *qt)
 Store a copy of the QofTime at the indicated path.
void kvp_frame_set_boolean (KvpFrame *frame, const gchar *path, gboolean val)
 Store the value of the boolean at the indicated path.
void kvp_frame_set_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Store a copy of the KvpFrame at the indicated path.
void kvp_frame_set_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Store a KvpFrame at the indicated path without copying.
KvpFramekvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value)
 Copy the KvpValue into the frame.
KvpFramekvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
 Store the KvpValue in the frame without copying.
KvpValuekvp_frame_replace_value_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value)
KvpFrame Glist Bag Storing
void kvp_frame_add_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
 add the value of the gint64 to the glist bag
void kvp_frame_add_double (KvpFrame *frame, const gchar *path, gdouble dval)
 Add the value of the double to the glist bag.
void kvp_frame_add_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
 Add the value of the QofNumeric to the glist bag.
void kvp_frame_add_time (KvpFrame *frame, const gchar *path, QofTime *qt)
 Add the value of the QofTime to the glist bag.
void kvp_frame_add_string (KvpFrame *frame, const gchar *path, const gchar *str)
 Copy the string to the glist bag at the indicated path.
void kvp_frame_add_boolean (KvpFrame *frame, const gchar *path, gboolean val)
void kvp_frame_add_guid (KvpFrame *frame, const gchar *path, const GUID *guid)
 Copy the GUID to the glist bag at the indicated path.
void kvp_frame_add_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Copy the frame to the glist bag at the indicated path.
void kvp_frame_add_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Add the frame to the glist bag without copying.
KvpFramekvp_frame_add_value (KvpFrame *frame, const gchar *path, KvpValue *value)
 Add a copy of the value to the glist bag.
KvpFramekvp_frame_add_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
KvpFrame Value Fetching
Value accessors. These all take a unix-style slash-separated path as an argument, and return the value stored at that location. If the object at the end of that path is not of the type that was asked for, then a NULL or a zero is returned. So, for example, asking for a string when the path stored an int will return a NULL. In some future date, this may be changed to a looser type system, such as perl's automatic re-typing (e.g. an integer value might be converted to a printed string representing that value).

If any part of the path does not exist, then NULL or zero will be returned.

The values returned for GUID, binary, GList, KvpFrame and string are "non-copying" -- the returned item is the actual item stored. Do not delete this item unless you take the required care to avoid possible bad pointer derefrences (i.e. core dumps). Also, be careful hanging on to those references if you are also storing at the same path names: the referenced item will be freed during the store.

That is, if you get a string value (or guid, binary or frame), and then store something else at that path, the string that you've gotten will be freed during the store (internally, by the set_*() routines), and you will be left hanging onto an invalid pointer.

gint64 kvp_frame_get_gint64 (const KvpFrame *frame, const gchar *path)
gdouble kvp_frame_get_double (const KvpFrame *frame, const gchar *path)
QofNumeric kvp_frame_get_numeric (const KvpFrame *frame, const gchar *path)
gchar * kvp_frame_get_string (const KvpFrame *frame, const gchar *path)
GUID * kvp_frame_get_guid (const KvpFrame *frame, const gchar *path)
gpointer kvp_frame_get_binary (const KvpFrame *frame, const gchar *path, guint64 *size_return)
gboolean kvp_frame_get_boolean (const KvpFrame *frame, const gchar *path)
QofTimekvp_frame_get_time (const KvpFrame *frame, const gchar *path)
KvpValuekvp_frame_get_value (const KvpFrame *frame, const gchar *path)
KvpFramekvp_frame_get_frame (const KvpFrame *frame, const gchar *path)
KvpFramekvp_frame_get_frame_path (KvpFrame *frame, const gchar *,...)
KvpFramekvp_frame_get_frame_gslist (KvpFrame *frame, GSList *key_path)
KvpFramekvp_frame_get_frame_slash (KvpFrame *frame, const gchar *path)
KvpFrame KvpValue low-level storing routines.
You probably shouldn't be using these low-level routines

All of the kvp_frame_set_slot_*() routines set the slot values "destructively", in that if there was an old value there, that old value is destroyed (and the memory freed). Thus, one should not hang on to value pointers, as these will get trashed if set_slot is called on the corresponding key.

If you want the old value, use kvp_frame_replace_slot().

KvpValuekvp_frame_replace_slot_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value)
void kvp_frame_set_slot (KvpFrame *frame, const gchar *key, const KvpValue *value)
void kvp_frame_set_slot_nc (KvpFrame *frame, const gchar *key, KvpValue *value)
void kvp_frame_set_slot_path (KvpFrame *frame, const KvpValue *value, const gchar *first_key,...)
void kvp_frame_set_slot_path_gslist (KvpFrame *frame, const KvpValue *value, GSList *key_path)
KvpFrame KvpValue Low-Level Retrieval Routines
You probably shouldn't be using these low-level routines

Returns the KvpValue in the given KvpFrame 'frame' that is associated with 'key'. If there is no key in the frame, NULL is returned. If the value associated with the key is NULL, NULL is returned.

Pointers passed as arguments into get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

KvpValuekvp_frame_get_slot (const KvpFrame *frame, const gchar *key)
KvpValuekvp_frame_get_slot_path (KvpFrame *frame, const gchar *first_key,...)
KvpValuekvp_frame_get_slot_path_gslist (KvpFrame *frame, GSList *key_path)
gint kvp_glist_compare (const GList *list1, const GList *list2)
GList * kvp_glist_copy (const GList *list)
void kvp_glist_delete (GList *list)
KvpValue Constructors
The following routines are constructors for kvp_value. Those with pointer arguments copy in the value. The *_nc() versions do *not* copy in their values, but use them directly.

KvpValuekvp_value_new_gint64 (gint64 value)
KvpValuekvp_value_new_double (double value)
KvpValuekvp_value_new_numeric (QofNumeric value)
KvpValuekvp_value_new_string (const gchar *value)
KvpValuekvp_value_new_guid (const GUID *guid)
KvpValuekvp_value_new_time (QofTime *value)
KvpValuekvp_value_new_boolean (gboolean value)
KvpValuekvp_value_new_binary (const void *data, guint64 datasize)
KvpValuekvp_value_new_frame (const KvpFrame *value)
KvpValuekvp_value_new_glist (const GList *value)
KvpValuekvp_value_new_binary_nc (void *data, guint64 datasize)
KvpValuekvp_value_new_glist_nc (GList *lst)
KvpValuekvp_value_new_frame_nc (KvpFrame *value)
void kvp_value_delete (KvpValue *value)
KvpValuekvp_value_copy (const KvpValue *value)
KvpFramekvp_value_replace_frame_nc (KvpValue *value, KvpFrame *newframe)
GList * kvp_value_replace_glist_nc (KvpValue *value, GList *newlist)
KvpValue Value access
KvpValueType kvp_value_get_type (const KvpValue *value)
gint64 kvp_value_get_gint64 (const KvpValue *value)
gdouble kvp_value_get_double (const KvpValue *value)
QofNumeric kvp_value_get_numeric (const KvpValue *value)
gchar * kvp_value_get_string (const KvpValue *value)
GUID * kvp_value_get_guid (const KvpValue *value)
gpointer kvp_value_get_binary (const KvpValue *value, guint64 *size_return)
GList * kvp_value_get_glist (const KvpValue *value)
KvpFramekvp_value_get_frame (const KvpValue *value)
gboolean kvp_value_get_boolean (const KvpValue *value)
QofTimekvp_value_get_time (const KvpValue *value)
gint kvp_value_compare (const KvpValue *va, const KvpValue *vb)

Generated on Thu Jan 31 22:50:26 2008 for QOF by  doxygen 1.5.4