KVP: Key-Value Pairs
[Query Object Framework]

---

Detailed Description

A KvpFrame is a set of associations between character strings (keys) and KvpValue structures. A KvpValue is a union with possible types enumerated in the KvpValueType enum, and includes, among other things, ints, doubles, strings, guid's, lists, time and numeric values. KvpValues may also be other frames, so KVP is inherently hierarchical.

Values are stored in a 'slot' associated with a key. Pointers passed as arguments into set_slot and get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

A 'path' is a sequence of keys that can be followed to a value. Paths may be specified as varargs (variable number of arguments to a subrutine, NULL-terminated), as a GSList, or as a standard URL-like path name. The later is parsed and treated in the same way as file paths would be: / separates keys, /./ is treated as / and /../ means backup one level. Repeated slashes are treated as one slash.

Note that although, in principle, keys may contain the / and . and .. characters, doing so may lead to confusion, and will make path-string parsing routines fail. In other words, don't use a key such as 'some/key' or 'some/./other/../key' because you may get unexpected results.

To set a value into a frame, you will want to use one of the kvp_frame_set_xxx() routines. Most of the other routines provide only low-level access that you probably shouldn't use.

Files
file	kvpframe.h
	A key-value frame system.
file	kvputil-p.h
	misc odd-job kvp utils engine-private routines
file	kvputil.h
	QOF KVP utility functions.
Data Structures
struct	GHashTableKVPair
Iterators
typedef void(*	KvpValueForeachCB )(const gchar *key, KvpValue *value, gpointer data)
void	kvp_frame_for_each_slot (KvpFrame *f, KvpValueForeachCB, gpointer data)
KvpFrame Constructors
KvpFrame *	kvp_frame_new (void)
void	kvp_frame_delete (KvpFrame *frame)
KvpFrame *	kvp_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.
KvpFrame *	kvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value)
	Copy the KvpValue into the frame.
KvpFrame *	kvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
	Store the KvpValue in the frame without copying.
KvpValue *	kvp_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.
KvpFrame *	kvp_frame_add_value (KvpFrame *frame, const gchar *path, KvpValue *value)
	Add a copy of the value to the glist bag.
KvpFrame *	kvp_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)
QofTime *	kvp_frame_get_time (const KvpFrame *frame, const gchar *path)
KvpValue *	kvp_frame_get_value (const KvpFrame *frame, const gchar *path)
KvpFrame *	kvp_frame_get_frame (const KvpFrame *frame, const gchar *path)
KvpFrame *	kvp_frame_get_frame_path (KvpFrame *frame, const gchar *,...)
KvpFrame *	kvp_frame_get_frame_gslist (KvpFrame *frame, GSList *key_path)
KvpFrame *	kvp_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().
KvpValue *	kvp_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.
KvpValue *	kvp_frame_get_slot (const KvpFrame *frame, const gchar *key)
KvpValue *	kvp_frame_get_slot_path (KvpFrame *frame, const gchar *first_key,...)
KvpValue *	kvp_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.
KvpValue *	kvp_value_new_gint64 (gint64 value)
KvpValue *	kvp_value_new_double (double value)
KvpValue *	kvp_value_new_numeric (QofNumeric value)
KvpValue *	kvp_value_new_string (const gchar *value)
KvpValue *	kvp_value_new_guid (const GUID *guid)
KvpValue *	kvp_value_new_time (QofTime *value)
KvpValue *	kvp_value_new_boolean (gboolean value)
KvpValue *	kvp_value_new_binary (const void *data, guint64 datasize)
KvpValue *	kvp_value_new_frame (const KvpFrame *value)
KvpValue *	kvp_value_new_glist (const GList *value)
KvpValue *	kvp_value_new_binary_nc (void *data, guint64 datasize)
KvpValue *	kvp_value_new_glist_nc (GList *lst)
KvpValue *	kvp_value_new_frame_nc (KvpFrame *value)
void	kvp_value_delete (KvpValue *value)
KvpValue *	kvp_value_copy (const KvpValue *value)
KvpFrame *	kvp_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)
KvpFrame *	kvp_value_get_frame (const KvpValue *value)
gboolean	kvp_value_get_boolean (const KvpValue *value)
QofTime *	kvp_value_get_time (const KvpValue *value)
gint	kvp_value_compare (const KvpValue *va, const KvpValue *vb)
KvpBag Bags of GUID Pointers
KvpFrame *	qof_kvp_bag_add (KvpFrame *kvp_root, const gchar *path, QofTime *qt, const gchar *first_name,...)
void	qof_kvp_bag_merge (KvpFrame *kvp_into, const gchar *intopath, KvpFrame *kvp_from, const gchar *frompath)
KvpFrame *	qof_kvp_bag_find_by_guid (KvpFrame *root, const gchar *path, const gchar *guid_name, GUID *desired_guid)
void	qof_kvp_bag_remove_frame (KvpFrame *root, const gchar *path, KvpFrame *fr)
Hash Utilities
GSList *	g_hash_table_key_value_pairs (GHashTable *table)
void	g_hash_table_kv_pair_free_gfunc (gpointer data, gpointer user_data)
KvpFrame URL handling
void	kvp_frame_add_url_encoding (KvpFrame *frame, const gchar *enc)
Defines
#define	QOF_MOD_KVP   "qof-kvp"
Typedefs
typedef struct _KvpFrame	KvpFrame
typedef struct _KvpValue	KvpValue
Enumerations
enum	KvpValueType {   KVP_TYPE_GINT64 = 1, KVP_TYPE_DOUBLE, KVP_TYPE_NUMERIC, KVP_TYPE_STRING,   KVP_TYPE_GUID, KVP_TYPE_TIMESPEC, KVP_TYPE_TIME, KVP_TYPE_BINARY,   KVP_TYPE_GLIST, KVP_TYPE_FRAME, KVP_TYPE_BOOLEAN }
	possible types in the union KvpValue More...
Functions
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)
gint	kvp_frame_compare (const KvpFrame *fa, const KvpFrame *fb)
gchar *	kvp_frame_to_string (const KvpFrame *frame)
gchar *	binary_to_string (const void *data, guint32 size)
gchar *	kvp_value_glist_to_string (const GList *list)
GHashTable *	kvp_frame_get_hash (const KvpFrame *frame)

---

Typedef Documentation

typedef struct _KvpFrame KvpFrame

Opaque frame structure

Definition at line 74 of file kvpframe.h.

typedef struct _KvpValue KvpValue

A KvpValue is a union with possible types enumerated in the KvpValueType enum.

Definition at line 78 of file kvpframe.h.

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

Since:

0.7.2

Definition at line 770 of file kvpframe.h.

---

Enumeration Type Documentation

enum KvpValueType

possible types in the union KvpValue

Todo:

In the long run, this could be synchronised with the core QOF types, which in turn may or may not be synced to the GValue types in GLib. The QOF types currently unsupported are KVP_TYPE_GLIST and KVP_TYPE_BINARY.

Enumerator:

KVP_TYPE_GINT64	64bit integer QofType : QOF_TYPE_INT64 GType : G_TYPE_INT64 GLib type : gint64
KVP_TYPE_DOUBLE	standard C double type QofType : QOF_TYPE_DOUBLE GType : G_TYPE_DOUBLE GLib type : gdouble
KVP_TYPE_NUMERIC	128bit denominator/numerator maths. QofType : QOF_TYPE_NUMERIC GType : no direct equivalent, consider QOF_TYPE_DOUBLE GLib type : no direct equivalent, consider QOF_TYPE_DOUBLE
KVP_TYPE_STRING	standard C string QofType : QOF_TYPE_STRING GType : G_TYPE_STRING GLib type : gchar*
KVP_TYPE_GUID	Unique identifier. QofType : QOF_TYPE_GUID GType : no direct equivalent, can be stored as QOF_TYPE_STRING GLib : no direct equivalent, can be stored as QOF_TYPE_STRING.
KVP_TYPE_TIMESPEC	Deprecated: QOF_TYPE_DATE
KVP_TYPE_TIME	64bit time/date handling. QofType : QOF_TYPE_TIME GType : No equivalent. GLib type : GDate (not fully equivalent, see QofTime)
KVP_TYPE_BINARY	no QofType/GType/GLib equivalent.
KVP_TYPE_GLIST	no QofType/GType equivalent.
KVP_TYPE_FRAME	no QofType/GType/GLib equivalent.
KVP_TYPE_BOOLEAN	Simple boolean type. QofType : QOF_TYPE_BOOLEAN GType : G_TYPE_BOOLEAN GLib type : gboolean.

Definition at line 87 of file kvpframe.h.

{
    KVP_TYPE_GINT64 = 1,
    KVP_TYPE_DOUBLE,
    KVP_TYPE_NUMERIC,
    KVP_TYPE_STRING,
    KVP_TYPE_GUID,
#ifndef QOF_DISABLE_DEPRECATED

    KVP_TYPE_TIMESPEC,
#endif

    KVP_TYPE_TIME,
    KVP_TYPE_BINARY,
    KVP_TYPE_GLIST,
    KVP_TYPE_FRAME,
    KVP_TYPE_BOOLEAN
} KvpValueType;

---

Function Documentation

GSList* g_hash_table_key_value_pairs

(

GHashTable *

table

)

Returns a GSList* of all the keys and values in a given hash table. Data elements of lists are actual hash elements, so be careful, and deallocation of the GHashTableKVPairs in the result list are the caller's responsibility. A typical sequence might look like this:

GSList *kvps = g_hash_table_key_value_pairs(hash); ... use kvps->data->key and kvps->data->val, etc. here ... g_slist_foreach(kvps, g_hash_table_kv_pair_free_gfunc, NULL); g_slist_free(kvps);

Definition at line 212 of file kvputil.c.

{
    GSList *result_list = NULL;
    g_hash_table_foreach (table, kv_pair_helper, &result_list);
    return result_list;
}

void kvp_frame_add_double	(	KvpFrame *	frame,
		const gchar *	path,
		gdouble	dval
	)

Add the value of the double to the glist bag.

If not all frame components of the path exist, they are created. If the value previously stored at this path was not a glist bag, then a bag will be formed there, the old value placed in the bag, and the new value added to the bag.

Definition at line 601 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_double (dval);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_frame	(	KvpFrame *	frame,
		const gchar *	path,
		KvpFrame *	chld
	)

Copy the frame to the glist bag at the indicated path.

If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag.

Definition at line 662 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_frame (fr);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_frame_nc	(	KvpFrame *	frame,
		const gchar *	path,
		KvpFrame *	chld
	)

Add the frame to the glist bag without copying.

If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag.

Definition at line 672 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_frame_nc (fr);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_gint64	(	KvpFrame *	frame,
		const gchar *	path,
		gint64	ival
	)

add the value of the gint64 to the glist bag

If not all frame components of the path exist, they are created. If the value previously stored at this path was not a glist bag, then a bag will be formed there, the old value placed in the bag, and the new value added to the bag.

Definition at line 591 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_gint64 (ival);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_guid	(	KvpFrame *	frame,
		const gchar *	path,
		const GUID *	guid
	)

Copy the GUID to the glist bag at the indicated path.

If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag.

Definition at line 652 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_guid (guid);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_numeric	(	KvpFrame *	frame,
		const gchar *	path,
		QofNumeric	nval
	)

Add the value of the QofNumeric to the glist bag.

If not all frame components of the path exist, they are created. If the value previously stored at this path was not a glist bag, then a bag will be formed there, the old value placed in the bag, and the new value added to the bag.

Definition at line 611 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_numeric (nval);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_string	(	KvpFrame *	frame,
		const gchar *	path,
		const gchar *	str
	)

Copy the string to the glist bag at the indicated path.

If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag.

Definition at line 642 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_string (str);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_time	(	KvpFrame *	frame,
		const gchar *	path,
		QofTime *	qt
	)

Add the value of the QofTime to the glist bag.

If not all frame components of the path exist, they are created. If the value previously stored at this path was not a glist bag, then a bag will be formed there, the old value placed in the bag, and the new value added to the bag.

Definition at line 622 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_time (qt);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_add_url_encoding	(	KvpFrame *	frame,
		const gchar *	enc
	)

The kvp_frame_add_url_encoding() routine will parse the value string, assuming it to be URL-encoded in the standard way, turning it into a set of key-value pairs, and adding those to the indicated frame. URL-encoded strings are the things that are returned by web browsers when a form is filled out. For example, 'start-date=June&end-date=November' consists of two keys, 'start-date' and 'end-date', which have the values 'June' and 'November', respectively. This routine also handles % encoding.

This routine treats all values as strings; it does *not* attempt to perform any type-conversion.

Definition at line 880 of file kvpframe.c.

{
    gchar *buff, *p;
    if (!frame || !enc)
        return;

    /* Loop over all key-value pairs in the encoded string */
    buff = g_strdup (enc);
    p = buff;
    while (*p)
    {
        gchar *n, *v;
        n = strchr (p, '&');    /* n = next key-value */
        if (n)
            *n = 0x0;

        v = strchr (p, '=');    /* v =  pointer to value */
        if (!v)
            break;
        *v = 0x0;
        v++;

        decode (p);
        decode (v);
        kvp_frame_set_slot_nc (frame, p, kvp_value_new_string (v));

        if (!n)
            break;              /* no next key, we are done */
        p = ++n;
    }

    g_free (buff);
}

KvpFrame* kvp_frame_add_value	(	KvpFrame *	frame,
		const gchar *	path,
		KvpValue *	value
	)

Add a copy of the value to the glist bag.

If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag. This routine returns the pointer to the last frame (the actual frame to which the value was added), or NULL if there was an error of any sort (typically, a parse error in the path).

Definition at line 581 of file kvpframe.c.

{
    value = kvp_value_copy (value);
    frame = kvp_frame_add_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
    return frame;
}

gint kvp_frame_compare	(	const KvpFrame *	fa,
		const KvpFrame *	fb
	)

Similar returns as strcmp.

Definition at line 1757 of file kvpframe.c.

{
    KvpFrameCompare status;

    if (fa == fb)
        return 0;
    /* nothing is always less than something */
    if (!fa && fb)
        return -1;
    if (fa && !fb)
        return 1;

    /* nothing is always less than something */
    if (!fa->hash && fb->hash)
        return -1;
    if (fa->hash && !fb->hash)
        return 1;

    status.compare = 0;
    status.other_frame = (KvpFrame *) fb;

    kvp_frame_for_each_slot ((KvpFrame *) fa, kvp_frame_compare_helper,
        &status);

    if (status.compare != 0)
        return status.compare;

    status.other_frame = (KvpFrame *) fa;

    kvp_frame_for_each_slot ((KvpFrame *) fb, kvp_frame_compare_helper,
        &status);

    return (-status.compare);
}

KvpFrame* kvp_frame_copy

(

const KvpFrame *

frame

)

Perform a deep (recursive) value copy, copying the frame, subframes, and the values as well.

Definition at line 156 of file kvpframe.c.

{
    KvpFrame *retval = kvp_frame_new ();

    if (!frame)
        return retval;

    if (frame->hash)
    {
        if (!init_frame_body_if_needed (retval))
            return (NULL);
        g_hash_table_foreach (frame->hash,
            &kvp_frame_copy_worker, (gpointer) retval);
    }
    return retval;
}

void kvp_frame_delete

(

KvpFrame *

frame

)

Perform a deep (recursive) delete of the frame and any subframes.

Definition at line 118 of file kvpframe.c.

{
    if (!frame)
        return;

    if (frame->hash)
    {
        /* free any allocated resource for frame or its children */
        g_hash_table_foreach (frame->hash, &kvp_frame_delete_worker,
            (gpointer) frame);

        /* delete the hash table */
        g_hash_table_destroy (frame->hash);
        frame->hash = NULL;
    }
    g_free (frame);
}

void kvp_frame_for_each_slot	(	KvpFrame *	f,
		KvpValueForeachCB	,
		gpointer	data
	)

Traverse all of the slots in the given kvp_frame. This function does not descend recursively to traverse any kvp_frames stored as slot values. You must handle that in proc, with a suitable recursive call if desired.

Definition at line 1650 of file kvpframe.c.

{
    if (!f)
        return;
    if (!proc)
        return;
    if (!(f->hash))
        return;
    g_hash_table_foreach (f->hash, (GHFunc) proc, data);
}

KvpFrame* kvp_frame_get_frame	(	const KvpFrame *	frame,
		const gchar *	path
	)

Value accessor. Takes a unix-style slash-separated path as an argument, and return the KvpFrame stored at that location. If the KvpFrame does not exist, then a NULL is returned.

Returns:

The KvpFrame at the specified path, or NULL if it doesn't exist.

Definition at line 984 of file kvpframe.c.

{
    gchar *key = NULL;
    frame = get_trailer_or_null (frame, path, &key);
    return kvp_value_get_frame (kvp_frame_get_slot (frame, key));
}

KvpFrame* kvp_frame_get_frame_gslist	(	KvpFrame *	frame,
		GSList *	key_path
	)

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame()

Definition at line 1002 of file kvpframe.c.

{
    if (!frame)
        return frame;

    while (key_path)
    {
        const gchar *key = key_path->data;

        if (!key)
            return frame;       /* an unusual but valid exit for this routine. */

        frame = get_or_make (frame, key);
        if (!frame)
            return frame;       /* this should never happen */

        key_path = key_path->next;
    }
    return frame;               /* this is the normal exit for this func */
}

KvpFrame* kvp_frame_get_frame_path	(	KvpFrame *	frame,
		const gchar *	,
			...
	)

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame()

Definition at line 1024 of file kvpframe.c.

{
    va_list ap;
    if (!frame || !key)
        return frame;

    va_start (ap, key);

    while (key)
    {
        frame = get_or_make (frame, key);
        if (!frame)
            break;              /* error, should never occur */
        key = va_arg (ap, const char *);
    }

    va_end (ap);
    return frame;
}

KvpFrame* kvp_frame_get_frame_slash	(	KvpFrame *	frame,
		const gchar *	path
	)

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame()

The kvp_frame_get_frame_slash() routine takes a single string where the keys are separated by slashes; thus, for example: /this/is/a/valid/path and///so//is////this/ Multiple slashes are compresed. Leading slash is optional. The pointers . and .. are *not* currently followed/obeyed. (This is a bug that needs fixing).

Definition at line 1045 of file kvpframe.c.

{
    gchar *root;
    if (!frame || !key_path)
        return frame;

    root = g_strdup (key_path);
    frame = kvp_frame_get_frame_slash_trash (frame, root);
    g_free (root);
    return frame;
}

KvpValue* kvp_frame_get_slot_path	(	KvpFrame *	frame,
		const gchar *	first_key,
			...
	)

This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.

Definition at line 1060 of file kvpframe.c.

{
    va_list ap;
    KvpValue *value;
    const gchar *key;

    if (!frame || !first_key)
        return NULL;

    va_start (ap, first_key);

    key = first_key;
    value = NULL;

    while (TRUE)
    {
        value = kvp_frame_get_slot (frame, key);
        if (!value)
            break;

        key = va_arg (ap, const gchar *);
        if (!key)
            break;

        frame = kvp_value_get_frame (value);
        if (!frame)
        {
            value = NULL;
            break;
        }
    }

    va_end (ap);

    return value;
}

KvpValue* kvp_frame_get_slot_path_gslist	(	KvpFrame *	frame,
		GSList *	key_path
	)

This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.

Definition at line 1098 of file kvpframe.c.

{
    if (!frame || !key_path)
        return NULL;

    while (TRUE)
    {
        const gchar *key = key_path->data;
        KvpValue *value;

        if (!key)
            return NULL;

        value = kvp_frame_get_slot (frame, key);
        if (!value)
            return NULL;

        key_path = key_path->next;
        if (!key_path)
            return value;

        frame = kvp_value_get_frame (value);
        if (!frame)
            return NULL;
    }
}

gboolean kvp_frame_is_empty

(

KvpFrame *

frame

)

Return TRUE if the KvpFrame is empty

Definition at line 137 of file kvpframe.c.

{
    if (!frame)
        return TRUE;
    if (!frame->hash)
        return TRUE;
    return FALSE;
}

KvpFrame* kvp_frame_new

(

void

)

Return a new empty instance of KvpFrame

Definition at line 100 of file kvpframe.c.

{
    KvpFrame *retval = g_new0 (KvpFrame, 1);

    /* Save space until the frame is actually used */
    retval->hash = NULL;
    return retval;
}

KvpValue* kvp_frame_replace_slot_nc	(	KvpFrame *	frame,
		const gchar *	slot,
		KvpValue *	new_value
	)

The kvp_frame_replace_slot_nc() routine places the new value into the indicated frame, for the given key. It returns the old value, if any. It returns NULL if the slot doesn't exist, if there was some other an error, or if there was no old value. Passing in a NULL new_value has the effect of deleting that slot.

Definition at line 178 of file kvpframe.c.

{
    gpointer orig_key;
    gpointer orig_value = NULL;
    int key_exists;

    if (!frame || !slot)
        return NULL;
    if (!init_frame_body_if_needed (frame))
        return NULL;            /* Error ... */

    key_exists = g_hash_table_lookup_extended (frame->hash, slot,
        &orig_key, &orig_value);
    if (key_exists)
    {
        g_hash_table_remove (frame->hash, slot);
        qof_util_string_cache_remove (orig_key);
    }
    else
        orig_value = NULL;
    if (new_value)
        g_hash_table_insert (frame->hash,
            qof_util_string_cache_insert ((gpointer) slot), new_value);
    return (KvpValue *) orig_value;
}

KvpValue* kvp_frame_replace_value_nc	(	KvpFrame *	frame,
		const gchar *	slot,
		KvpValue *	new_value
	)

The kvp_frame_replace_value_nc() routine places the new value at the indicated path. It returns the old value, if any. It returns NULL if there was an error, or if there was no old value. If the path doesn't exist, it is created, unless new_value is NULL. Passing in a NULL new_value has the effect of deleting the trailing slot (i.e. the trailing path element).

Definition at line 516 of file kvpframe.c.

{
    KvpValue *old_value;
    gchar *last_key;

    last_key = NULL;
    if (new_value)
        frame = get_trailer_make (frame, key_path, &last_key);
    else
        frame =
            (KvpFrame *) get_trailer_or_null (frame, key_path, &last_key);
    if (!frame)
        return NULL;

    old_value = kvp_frame_replace_slot_nc (frame, last_key, new_value);
    return old_value;
}

void kvp_frame_set_boolean	(	KvpFrame *	frame,
		const gchar *	path,
		gboolean	val
	)

Store the value of the boolean at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 431 of file kvpframe.c.

{
    KvpValue * value;
    value = kvp_value_new_boolean (val);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_double	(	KvpFrame *	frame,
		const gchar *	path,
		gdouble	dval
	)

store the value of the double at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 400 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_double (dval);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_frame	(	KvpFrame *	frame,
		const gchar *	path,
		KvpFrame *	chld
	)

Store a copy of the KvpFrame at the indicated path.

If not all frame components of the path exist, they are created. If there was another QofTime previously stored at that path, the old frame is deleted.

Definition at line 464 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_frame (fr);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_frame_nc	(	KvpFrame *	frame,
		const gchar *	path,
		KvpFrame *	chld
	)

Store a KvpFrame at the indicated path without copying.

If not all frame components of the path exist, they are created. If there was another QofTime previously stored at that path, the old frame is deleted.

Definition at line 474 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_frame_nc (fr);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_gint64	(	KvpFrame *	frame,
		const gchar *	path,
		gint64	ival
	)

store the value of the gint64 at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 390 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_gint64 (ival);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_guid	(	KvpFrame *	frame,
		const gchar *	path,
		const GUID *	guid
	)

Store a copy of the GUID at the indicated path.

If not all frame components of the path exist, they are created. If there was another GUID previously stored at that path, the old copy is deleted.

Definition at line 453 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_guid (guid);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_numeric	(	KvpFrame *	frame,
		const gchar *	path,
		QofNumeric	nval
	)

store the value of the QofNumeric at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 420 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_numeric (nval);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_slot	(	KvpFrame *	frame,
		const gchar *	key,
		const KvpValue *	value
	)

The kvp_frame_set_slot() routine copies the value into the frame, associating it with a copy of 'key'. Pointers passed as arguments into kvp_frame_set_slot are the responsibility of the caller; the pointers are *not* taken over or managed. The old value at this location, if any, is destroyed.

Definition at line 684 of file kvpframe.c.

{
    KvpValue *new_value = NULL;

    if (!frame)
        return;

    g_return_if_fail (slot && *slot != '\0');

    if (value)
        new_value = kvp_value_copy (value);
    kvp_frame_set_slot_destructively (frame, slot, new_value);
}

void kvp_frame_set_slot_nc	(	KvpFrame *	frame,
		const gchar *	key,
		KvpValue *	value
	)

The kvp_frame_set_slot_nc() routine puts the value (without copying it) into the frame, associating it with a copy of 'key'. This routine is handy for avoiding excess memory allocations & frees. Note that because the KvpValue was grabbed, you can't just delete unless you remove the key as well (or unless you replace the value). The old value at this location, if any, is destroyed.

Definition at line 700 of file kvpframe.c.

{
    if (!frame)
        return;

    g_return_if_fail (slot && *slot != '\0');

    kvp_frame_set_slot_destructively (frame, slot, value);
}

void kvp_frame_set_slot_path	(	KvpFrame *	frame,
		const KvpValue *	value,
		const gchar *	first_key,
			...
	)

The kvp_frame_set_slot_path() routine walks the hierarchy, using the key values to pick each branch. When the terminal node is reached, the value is copied into it. The old value at this location, if any, is destroyed.

Definition at line 726 of file kvpframe.c.

{
    va_list ap;
    const gchar *key;

    if (!frame)
        return;

    g_return_if_fail (first_key && *first_key != '\0');

    va_start (ap, first_key);

    key = first_key;

    while (TRUE)
    {
        KvpValue *value;
        const gchar *next_key;

        next_key = va_arg (ap, const gchar *);
        if (!next_key)
        {
            kvp_frame_set_slot (frame, key, new_value);
            break;
        }

        g_return_if_fail (*next_key != '\0');

        value = kvp_frame_get_slot (frame, key);
        if (!value)
        {
            KvpFrame *new_frame = kvp_frame_new ();
            KvpValue *frame_value = kvp_value_new_frame (new_frame);

            kvp_frame_set_slot_nc (frame, key, frame_value);

            value = kvp_frame_get_slot (frame, key);
            if (!value)
                break;
        }

        frame = kvp_value_get_frame (value);
        if (!frame)
            break;

        key = next_key;
    }

    va_end (ap);
}

void kvp_frame_set_slot_path_gslist	(	KvpFrame *	frame,
		const KvpValue *	value,
		GSList *	key_path
	)

The kvp_frame_set_slot_path_gslist() routine walks the hierarchy, using the key values to pick each branch. When the terminal node is reached, the value is copied into it. The old value at this location, if any, is destroyed.

Definition at line 779 of file kvpframe.c.

{
    if (!frame || !key_path)
        return;

    while (TRUE)
    {
        const gchar *key = key_path->data;
        KvpValue *value;

        if (!key)
            return;

        g_return_if_fail (*key != '\0');

        key_path = key_path->next;
        if (!key_path)
        {
            kvp_frame_set_slot (frame, key, new_value);
            return;
        }

        value = kvp_frame_get_slot (frame, key);
        if (!value)
        {
            KvpFrame *new_frame = kvp_frame_new ();
            KvpValue *frame_value = kvp_value_new_frame (new_frame);

            kvp_frame_set_slot_nc (frame, key, frame_value);

            value = kvp_frame_get_slot (frame, key);
            if (!value)
                return;
        }

        frame = kvp_value_get_frame (value);
        if (!frame)
            return;
    }
}

void kvp_frame_set_string	(	KvpFrame *	frame,
		const gchar *	path,
		const gchar *	str
	)

Store a copy of the string at the indicated path.

If not all frame components of the path exist, they are created. If there was another string previously stored at that path, the old copy is deleted.

Definition at line 442 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_string (str);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

void kvp_frame_set_time	(	KvpFrame *	frame,
		const gchar *	path,
		QofTime *	qt
	)

Store a copy of the QofTime at the indicated path.

If not all frame components of the path exist, they are created. If there was another QofTime previously stored at that path, the old copy is deleted.

Definition at line 410 of file kvpframe.c.

{
    KvpValue *value;
    value = kvp_value_new_time (qt);
    frame = kvp_frame_set_value_nc (frame, path, value);
    if (!frame)
        kvp_value_delete (value);
}

KvpFrame* kvp_frame_set_value	(	KvpFrame *	frame,
		const gchar *	path,
		const KvpValue *	value
	)

Copy the KvpValue into the frame.

If the path contains slashes '/', these are assumed to represent a sequence of keys. The old value at this location, if any, is destroyed.

Pointers passed as arguments into this routine remain the responsibility of the caller.

Parameters:

	frame	The frame to hold the copied value.
	path	The location of the value in the frame.
	value	The value to be copied.

Returns:

a pointer to the actual frame into which the value was inserted or NULL if the frame could not be found.

Definition at line 499 of file kvpframe.c.

{
    KvpValue *new_value = NULL;
    gchar *last_key;

    frame = get_trailer_make (frame, key_path, &last_key);
    if (!frame)
        return NULL;

    if (value)
        new_value = kvp_value_copy (value);
    kvp_frame_set_slot_destructively (frame, last_key, new_value);
    return frame;
}

KvpFrame* kvp_frame_set_value_nc	(	KvpFrame *	frame,
		const gchar *	path,
		KvpValue *	value
	)

Store the KvpValue in the frame without copying.

If the path contains slashes '/', these are assumed to represent a sequence of keys.

The returned value is a pointer to the actual frame into which the value was inserted; it is NULL if the frame couldn't be found (and thus the value wasn't inserted). The old value at this location, if any, is destroyed.

This routine is handy for avoiding excess memory allocations & frees. Note that because the KvpValue was grabbed, you can't just delete unless you remove the key as well (or unless you replace the value).

Definition at line 486 of file kvpframe.c.

{
    gchar *last_key;

    frame = get_trailer_make (frame, key_path, &last_key);
    if (!frame)
        return NULL;
    kvp_frame_set_slot_destructively (frame, last_key, value);
    return frame;
}

gint kvp_glist_compare	(	const GList *	list1,
		const GList *	list2
	)

kvp_glist_compare() compares GLists of KvpValue values (not to be confused with GLists of something else): it iterates over the list elements, performing a kvp_value_compare on each.

Definition at line 1170 of file kvpframe.c.

{
    const GList *lp1;
    const GList *lp2;

    if (list1 == list2)
        return 0;

    /* Nothing is always less than something */
    if (!list1 && list2)
        return -1;
    if (list1 && !list2)
        return 1;

    lp1 = list1;
    lp2 = list2;
    while (lp1 && lp2)
    {
        KvpValue *v1 = (KvpValue *) lp1->data;
        KvpValue *v2 = (KvpValue *) lp2->data;
        gint vcmp = kvp_value_compare (v1, v2);
        if (vcmp != 0)
            return vcmp;
        lp1 = lp1->next;
        lp2 = lp2->next;
    }
    if (!lp1 && lp2)
        return -1;
    if (!lp2 && lp1)
        return 1;
    return 0;
}

GList* kvp_glist_copy

(

const GList *

list

)

kvp_glist_copy() performs a deep copy of a GList of kvp_values (not to be confused with GLists of something else): same as mapping kvp_value_copy() over the elements and then copying the spine.

Definition at line 1148 of file kvpframe.c.

{
    GList *retval = NULL;
    GList *lptr;

    if (!list)
        return retval;

    /* Duplicate the backbone of the list (this duplicates the POINTERS
     * to the values; we need to deep-copy the values separately) */
    retval = g_list_copy ((GList *) list);

    /* This step deep-copies the values */
    for (lptr = retval; lptr; lptr = lptr->next)
    {
        lptr->data = kvp_value_copy (lptr->data);
    }

    return retval;
}

void kvp_glist_delete

(

GList *

list

)

kvp_glist_delete() performs a deep delete of a GList of kvp_values (not to be confused with GLists of something else): same as mapping * kvp_value_delete() over the elements and then deleting the GList.

Definition at line 1130 of file kvpframe.c.

{
    GList *node;
    if (!list)
        return;

    /* Delete the data in the list */
    for (node = list; node; node = node->next)
    {
        KvpValue *val = node->data;
        kvp_value_delete (val);
    }

    /* Free the backbone */
    g_list_free (list);
}

gboolean kvp_value_binary_append	(	KvpValue *	v,
		gpointer	data,
		guint64	size
	)

Manipulator:

copying - but more efficient than creating a new KvpValue manually.

gint kvp_value_compare	(	const KvpValue *	va,
		const KvpValue *	vb
	)

Similar returns as strcmp.

Definition at line 1662 of file kvpframe.c.

{
    if (kva == kvb)
        return 0;
    /* nothing is always less than something */
    if (!kva && kvb)
        return -1;
    if (kva && !kvb)
        return 1;

    if (kva->type < kvb->type)
        return -1;
    if (kva->type > kvb->type)
        return 1;

    switch (kva->type)
    {
    case KVP_TYPE_GINT64:
        if (kva->value.int64 < kvb->value.int64)
            return -1;
        if (kva->value.int64 > kvb->value.int64)
            return 1;
        return 0;
        break;
    case KVP_TYPE_DOUBLE:
        return qof_util_double_compare (kva->value.dbl, kvb->value.dbl);
        break;
    case KVP_TYPE_NUMERIC:
        return qof_numeric_compare (kva->value.numeric,
            kvb->value.numeric);
        break;
    case KVP_TYPE_STRING:
        return strcmp (kva->value.str, kvb->value.str);
        break;
    case KVP_TYPE_GUID:
        return guid_compare (kva->value.guid, kvb->value.guid);
        break;
    case KVP_TYPE_BOOLEAN:
    {
        /* true > false */
        if (kva->value.gbool != kvb->value.gbool)
            return (kva->value.gbool) ? 1 : -1;
        return 0;
        break;
    }
    case KVP_TYPE_TIME :
        return qof_time_cmp (kva->value.qt, kvb->value.qt);
        break;
#ifndef QOF_DISABLE_DEPRECATED
    case KVP_TYPE_TIMESPEC:
        return timespec_cmp (&(kva->value.timespec),
            &(kvb->value.timespec));
        break;
#endif
    case KVP_TYPE_BINARY:
        if (kva->value.binary.datasize < kvb->value.binary.datasize)
            return -1;
        if (kva->value.binary.datasize > kvb->value.binary.datasize)
            return 1;
        return memcmp (kva->value.binary.data,
            kvb->value.binary.data, kva->value.binary.datasize);
        break;
    case KVP_TYPE_GLIST:
        return kvp_glist_compare (kva->value.list, kvb->value.list);
        break;
    case KVP_TYPE_FRAME:
        return kvp_frame_compare (kva->value.frame, kvb->value.frame);
        break;
    }
    return 0;
}

KvpValue* kvp_value_copy

(

const KvpValue *

value

)

This is a deep value copy.

Definition at line 1601 of file kvpframe.c.

{
    if (!value)
        return NULL;

    switch (value->type)
    {
    case KVP_TYPE_GINT64:
        return kvp_value_new_gint64 (value->value.int64);
        break;
    case KVP_TYPE_DOUBLE:
        return kvp_value_new_double (value->value.dbl);
        break;
    case KVP_TYPE_NUMERIC:
        return kvp_value_new_numeric (value->value.numeric);
        break;
    case KVP_TYPE_STRING:
        return kvp_value_new_string (value->value.str);
        break;
    case KVP_TYPE_GUID:
        return kvp_value_new_guid (value->value.guid);
        break;
    case KVP_TYPE_BOOLEAN:
        return NULL;
        return kvp_value_new_boolean (value->value.gbool);
        break;
    case KVP_TYPE_TIME :
        return kvp_value_new_time (value->value.qt);
        break;
#ifndef QOF_DISABLE_DEPRECATED
    case KVP_TYPE_TIMESPEC:
        return kvp_value_new_timespec (value->value.timespec);
        break;
#endif
    case KVP_TYPE_BINARY:
        return kvp_value_new_binary (value->value.binary.data,
            value->value.binary.datasize);
        break;
    case KVP_TYPE_GLIST:
        return kvp_value_new_glist (value->value.list);
        break;
    case KVP_TYPE_FRAME:
        return kvp_value_new_frame (value->value.frame);
        break;
    }
    return NULL;
}

void kvp_value_delete

(

KvpValue *

value

)

This is a deep (recursive) delete.

Definition at line 1361 of file kvpframe.c.

{
    if (!value)
        return;

    switch (value->type)
    {
    case KVP_TYPE_STRING:
        g_free (value->value.str);
        break;
    case KVP_TYPE_GUID:
        g_free (value->value.guid);
        break;
    case KVP_TYPE_BINARY:
        g_free (value->value.binary.data);
        break;
    case KVP_TYPE_GLIST:
        kvp_glist_delete (value->value.list);
        break;
    case KVP_TYPE_FRAME:
        kvp_frame_delete (value->value.frame);
        break;
    case KVP_TYPE_BOOLEAN:
    case KVP_TYPE_GINT64:
    case KVP_TYPE_DOUBLE:
    case KVP_TYPE_NUMERIC:
    default:
        break;
    }
    g_free (value);
}

gpointer kvp_value_get_binary	(	const KvpValue *	value,
		guint64 *	size_return
	)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1507 of file kvpframe.c.

{
    if (!value)
    {
        if (size_return)
            *size_return = 0;
        PERR (" no size specified");
        return NULL;
    }

    if (value->type == KVP_TYPE_BINARY)
    {
        if (size_return)
            *size_return = value->value.binary.datasize;
        return value->value.binary.data;
    }
    else
    {
        if (size_return)
            *size_return = 0;
        PERR (" value type %d does not match KVP_TYPE_BINARY",
            value->type);
        return NULL;
    }
}

KvpFrame* kvp_value_get_frame

(

const KvpValue *

value

)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1549 of file kvpframe.c.

{
    if (!value)
        return NULL;
    if (value->type == KVP_TYPE_FRAME)
        return value->value.frame;
    else
    {
        PERR (" value type %d does not match KVP_TYPE_FRAME",
            value->type);
        return NULL;
    }
}

gint64 kvp_value_get_gint64

(

const KvpValue *

value

)

Value accessors. Those for GUID, binary, GList, KvpFrame and string are non-copying -- the caller can modify the value directly. Just don't free it, or you screw up everything. Note that if another value is stored at the key location that this value came from, then this value will be uncermoniously deleted, and you will be left pointing to garbage. So don't store values at the same time you are examining their contents.

Todo:

kvp_value_get_ functions need to set QofError so that users can check that a NULL or zero value is actually a real value and not an error result.

Definition at line 1402 of file kvpframe.c.

{
    if (!value)
        return 0;
    if (value->type == KVP_TYPE_GINT64)
        return value->value.int64;
    else
    {
        PERR (" value type %d does not match KVP_TYPE_GINT64",
            value->type);
        return 0;
    }
}

GList* kvp_value_get_glist

(

const KvpValue *

value

)

Returns the GList of kvp_frame's (not to be confused with GList's of something else!) from the given kvp_frame. This one is non-copying -- the caller can modify the value directly.

Definition at line 1534 of file kvpframe.c.

{
    if (!value)
        return NULL;
    if (value->type == KVP_TYPE_GLIST)
        return value->value.list;
    else
    {
        PERR (" value type %d does not match KVP_TYPE_GLIST",
            value->type);
        return NULL;
    }
}

GUID* kvp_value_get_guid

(

const KvpValue *

value

)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1477 of file kvpframe.c.

{
    if (!value)
        return NULL;
    if (value->type == KVP_TYPE_GUID)
        return value->value.guid;
    else
    {
        PERR (" value type %d does not match KVP_TYPE_GUID",
            value->type);
        return NULL;
    }
}

gchar* kvp_value_get_string

(

const KvpValue *

value

)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1447 of file kvpframe.c.

{
    if (!value)
        return NULL;
    if (value->type == KVP_TYPE_STRING)
        return value->value.str;
    else
    {
        PERR (" value type %d does not match KVP_TYPE_STRING",
            value->type);
        return NULL;
    }
}

KvpValue* kvp_value_new_binary_nc	(	void *	data,
		guint64	datasize
	)

value constructors (non-copying - KvpValue takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.)

KvpValue* kvp_value_new_boolean

(

gboolean

value

)

Since:

0.7.2

Definition at line 1226 of file kvpframe.c.

{
    KvpValue * retval = g_new0 (KvpValue, 1);
    retval->type = KVP_TYPE_BOOLEAN;
    retval->value.gbool = value;
    return retval;
}

KvpValue* kvp_value_new_frame_nc

(

KvpFrame *

value

)

value constructors (non-copying - KvpValue takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.)

Definition at line 1348 of file kvpframe.c.

{
    KvpValue *retval;
    if (!value)
        return NULL;

    retval = g_new0 (KvpValue, 1);
    retval->type = KVP_TYPE_FRAME;
    retval->value.frame = value;
    return retval;
}

KvpValue* kvp_value_new_glist

(

const GList *

value

)

Creates a KvpValue from a GList of kvp_value's! (Not to be confused with GList's of something else!)

Definition at line 1309 of file kvpframe.c.

{
    KvpValue *retval;
    if (!value)
        return NULL;

    retval = g_new0 (KvpValue, 1);
    retval->type = KVP_TYPE_GLIST;
    retval->value.list = kvp_glist_copy (value);
    return retval;
}

KvpValue* kvp_value_new_glist_nc

(

GList *

lst

)

Creates a KvpValue from a GList of kvp_value's! (Not to be confused with GList's of something else!)

This value constructor is non-copying (KvpValue takes pointer ownership). The values *must* have been allocated via glib allocators! (gnew, etc.)

Definition at line 1322 of file kvpframe.c.

{
    KvpValue *retval;
    if (!value)
        return NULL;

    retval = g_new0 (KvpValue, 1);
    retval->type = KVP_TYPE_GLIST;
    retval->value.list = value;
    return retval;
}

KvpFrame* kvp_value_replace_frame_nc	(	KvpValue *	value,
		KvpFrame *	newframe
	)

Replace old frame value with new, return old frame

Definition at line 1564 of file kvpframe.c.

{
    KvpFrame *oldframe;
    if (!value)
        return NULL;
    if (KVP_TYPE_FRAME != value->type)
    {
        PERR (" value type %d does not match KVP_TYPE_FRAME",
            value->type);
        return NULL;
    }
    oldframe = value->value.frame;
    value->value.frame = newframe;
    return oldframe;
}

GList* kvp_value_replace_glist_nc	(	KvpValue *	value,
		GList *	newlist
	)

Replace old glist value with new, return old glist

Definition at line 1581 of file kvpframe.c.

{
    GList *oldlist;
    if (!value)
        return NULL;
    if (KVP_TYPE_GLIST != value->type)
    {
        PERR (" value type %d does not match KVP_TYPE_GLIST",
            value->type);
        return NULL;
    }

    oldlist = value->value.list;
    value->value.list = newlist;
    return oldlist;
}

gchar* kvp_value_to_bare_string

(

const KvpValue *

val

)

General purpose function to convert any KvpValue to a string.

Only the bare string is returned, there is no debugging information.

Definition at line 1848 of file kvpframe.c.

{
    gchar *tmp1;
    gchar *tmp2;
    const gchar *ctmp;

    g_return_val_if_fail (val, NULL);
    tmp1 = g_strdup ("");
    switch (kvp_value_get_type (val))
    {
        case KVP_TYPE_GINT64:
        {
            return g_strdup_printf ("%" G_GINT64_FORMAT,
                kvp_value_get_gint64 (val));
            break;
        }
        case KVP_TYPE_DOUBLE:
        {
            return g_strdup_printf ("(%g)", kvp_value_get_double (val));
            break;
        }
        case KVP_TYPE_NUMERIC:
        {
            tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
            tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
            g_free (tmp1);
            return tmp2;
            break;
        }
        case KVP_TYPE_STRING:
        {
            tmp1 = kvp_value_get_string (val);
            return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
            break;
        }
        case KVP_TYPE_GUID:
        {
            ctmp = guid_to_string (kvp_value_get_guid (val));
            tmp2 = g_strdup_printf ("%s", ctmp ? ctmp : "");
            return tmp2;
            break;
        }
#ifndef QOF_DISABLE_DEPRECATED
        case KVP_TYPE_TIMESPEC:
        {
            time_t t;
            t = timespecToTime_t (kvp_value_get_timespec (val));
            qof_date_format_set (QOF_DATE_FORMAT_UTC);
            return qof_print_date (t);
            break;
        }
#endif
        case KVP_TYPE_BOOLEAN :
            return (kvp_value_get_boolean (val)) ? "TRUE" : "FALSE";
        case KVP_TYPE_BINARY:
        {
            guint64 len;
            gpointer data;
            data = kvp_value_get_binary (val, &len);
            tmp1 = binary_to_string (data, len);
            return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
            break;
        }
        case KVP_TYPE_GLIST:
        /* borked. kvp_value_glist_to_string is a debug fcn */
        {
            tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
            tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
            g_free (tmp1);
            return tmp2;
            break;
        }
        case KVP_TYPE_FRAME:
        {
            KvpFrame *frame;

            frame = kvp_value_get_frame (val);
            if (frame->hash)
            {
                tmp1 = g_strdup ("");
                g_hash_table_foreach (frame->hash,
                    kvp_frame_to_bare_string_helper, &tmp1);
            }
            return tmp1;
            break;
        }
        default:
            return g_strdup_printf (" ");
            break;
    }
}

gchar* kvp_value_to_string

(

const KvpValue *

val

)

Debug version.

This version is used only by qof_query_printValueForParam, itself a debugging and development utility function.

Definition at line 1941 of file kvpframe.c.

{
    gchar *tmp1;
    gchar *tmp2;
    const gchar *ctmp;

    g_return_val_if_fail (val, NULL);

    switch (kvp_value_get_type (val))
    {
        case KVP_TYPE_GINT64:
        {
            return g_strdup_printf ("KVP_VALUE_GINT64(%" G_GINT64_FORMAT ")",
                kvp_value_get_gint64 (val));
            break;
        }
        case KVP_TYPE_DOUBLE:
        {
            return g_strdup_printf ("KVP_VALUE_DOUBLE(%g)",
                kvp_value_get_double (val));
            break;
        }
        case KVP_TYPE_NUMERIC:
        {
            tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
            tmp2 = g_strdup_printf ("KVP_VALUE_NUMERIC(%s)", tmp1 ? tmp1 : "");
            g_free (tmp1);
            return tmp2;
            break;
        }
        case KVP_TYPE_STRING:
        {
            tmp1 = kvp_value_get_string (val);
            return g_strdup_printf ("KVP_VALUE_STRING(%s)", tmp1 ? tmp1 : "");
            break;
        }
        case KVP_TYPE_GUID:
        {
            /* THREAD-UNSAFE */
            ctmp = guid_to_string (kvp_value_get_guid (val));
            tmp2 = g_strdup_printf ("KVP_VALUE_GUID(%s)", ctmp ? ctmp : "");
            return tmp2;
            break;
        }
#ifndef QOF_DISABLE_DEPRECATED
        case KVP_TYPE_TIMESPEC:
        {
            tmp1 = g_new0 (gchar, 40);
            gnc_timespec_to_iso8601_buff (kvp_value_get_timespec (val), tmp1);
            tmp2 = g_strdup_printf ("KVP_VALUE_TIMESPEC(%s)", tmp1);
            g_free (tmp1);
            return tmp2;
            break;
        }
#endif
        case KVP_TYPE_BINARY:
        {
            guint64 len;
            gpointer data;
            data = kvp_value_get_binary (val, &len);
            tmp1 = binary_to_string (data, len);
            return g_strdup_printf ("KVP_VALUE_BINARY(%s)",
                tmp1 ? tmp1 : "");
            break;
        }
        case KVP_TYPE_GLIST:
        {
            tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
            tmp2 = g_strdup_printf ("KVP_VALUE_GLIST(%s)", tmp1 ? tmp1 : "");
            g_free (tmp1);
            return tmp2;
            break;
        }
        case KVP_TYPE_FRAME:
        {
            tmp1 = kvp_frame_to_string (kvp_value_get_frame (val));
            tmp2 = g_strdup_printf ("KVP_VALUE_FRAME(%s)", tmp1 ? tmp1 : "");
            g_free (tmp1);
            return tmp2;
            break;
        }
        default:
            return g_strdup_printf (" ");
            break;
    }
}

KvpFrame* qof_kvp_bag_add	(	KvpFrame *	kvp_root,
		const gchar *	path,
		QofTime *	qt,
		const gchar *	first_name,
			...
	)

The qof_kvp_bag_add() routine is used to maintain a collection of pointers in a kvp tree.

The thing being pointed at is uniquely identified by its GUID. This routine is typically used to create a linked list, and/or a collection of pointers to objects that are 'related' to each other in some way.

The var-args should be pairs of strings (const char *) followed by the corresponding GUID pointer (const GUID *). Terminate the varargs with a NULL as the last string argument.

The actual 'pointer' is stored in a subdirectory in a bag located at the node directory 'path'. A 'bag' is merely a collection of (unamed) values. The name of our bag is 'path'. A bag can contain any kind of values, including frames. This routine will create a frame, and put it in the bag. The frame will contain named data from the subroutine arguments. Thus, for example:

qof_kvp_array (kvp, "foo", secs, "acct_guid", aguid, "book_guid", bguid, NULL);

will create a frame containing "/acct_guid" and "/book_guid", whose values are aguid and bguid respecitvely. The frame will also contain "/date", whose value will be secs. This frame will be placed into the bag located at "foo".

This routine returns a pointer to the frame that was created, or NULL if an error occured.

Definition at line 67 of file kvputil.c.

{
    KvpFrame *cwd;
    va_list ap;
    va_start (ap, first_name);
    cwd = qof_kvp_array_va (pwd, path, qt, first_name, ap);
    va_end (ap);
    return cwd;
}

KvpFrame* qof_kvp_bag_find_by_guid	(	KvpFrame *	root,
		const gchar *	path,
		const gchar *	guid_name,
		GUID *	desired_guid
	)

The qof_kvp_bag_find_by_guid() routine examines the bag pointed located at root. It looks for a frame in that bag that has the guid value of "desired_guid" filed under the key name "guid_name". If it finds that matching guid, then it returns a pointer to the KVP frame that contains it. If it is not found, or if there is any other error, NULL is returned.

Definition at line 89 of file kvputil.c.

{
    KvpValue *arr;
    KvpValueType valtype;
    GList *node;

    arr = kvp_frame_get_value (root, path);
    valtype = kvp_value_get_type (arr);
    if (KVP_TYPE_FRAME == valtype)
    {
        MATCH_GUID (arr);
        return NULL;
    }

    /* Its got to be a single isolated frame, or a list of them. */
    if (KVP_TYPE_GLIST != valtype)
        return NULL;

    for (node = kvp_value_get_glist (arr); node; node = node->next)
    {
        KvpValue *va = node->data;
        MATCH_GUID (va);
    }
    return NULL;
}

void qof_kvp_bag_merge	(	KvpFrame *	kvp_into,
		const gchar *	intopath,
		KvpFrame *	kvp_from,
		const gchar *	frompath
	)

The qof_kvp_bag_merge() routine will move the bag contents from the 'kvp_from', to the 'into' bag. It will then delete the 'from' bag from the kvp tree.

Definition at line 186 of file kvputil.c.

{
    KvpFrame *fr;

    fr = qof_kvp_bag_get_first (kvp_from, frompath);
    while (fr)
    {
        qof_kvp_bag_remove_frame (kvp_from, frompath, fr);
        kvp_frame_add_frame_nc (kvp_into, intopath, fr);
        fr = qof_kvp_bag_get_first (kvp_from, frompath);
    }
}

void qof_kvp_bag_remove_frame	(	KvpFrame *	root,
		const gchar *	path,
		KvpFrame *	fr
	)

Remove the given frame from the bag. The frame is removed, however, it is not deleted. Note that the frame pointer must be a pointer to the actual frame (for example, as returned by gnc_kvp_bag_find_by_guid() for by gnc_kvp_bag_add()), and not some copy of the frame.

Definition at line 119 of file kvputil.c.

{
    KvpValue *arr;
    KvpValueType valtype;
    GList *node, *listhead;

    arr = kvp_frame_get_value (root, path);
    valtype = kvp_value_get_type (arr);
    if (KVP_TYPE_FRAME == valtype)
    {
        if (fr == kvp_value_get_frame (arr))
        {
            KvpValue *old_val =
                kvp_frame_replace_value_nc (root, path, NULL);
            kvp_value_replace_frame_nc (old_val, NULL);
            kvp_value_delete (old_val);
        }
        return;
    }

    /* Its got to be a single isolated frame, or a list of them. */
    if (KVP_TYPE_GLIST != valtype)
        return;

    listhead = kvp_value_get_glist (arr);
    for (node = listhead; node; node = node->next)
    {
        KvpValue *va = node->data;
        if (fr == kvp_value_get_frame (va))
        {
            listhead = g_list_remove_link (listhead, node);
            g_list_free_1 (node);
            kvp_value_replace_glist_nc (arr, listhead);
            kvp_value_replace_frame_nc (va, NULL);
            kvp_value_delete (va);
            return;
        }
    }
}

---