KVP: Key-Value Pairs
[Query Object Framework]


Data Structures

struct  GHashTableKVPair

Files

file  kvpframe.h
 A key-value frame system.
file  kvputil-p.h
 Private KVP utilities for backends etc.
file  kvputil.h
 QOF KVP utility functions.

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_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)
KvpValueType qof_id_to_kvp_value_type (QofIdTypeConst type_string)
 Convert a QofIdType to a KvpValueType.
QofIdTypeConst kvp_value_type_to_qof_id (KvpValueType n)
 Convert a KvpValueType to a QofIdType.
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)

Iterators

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

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)

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)

KvpBag Bags of GUID Pointers

KvpFrameqof_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)
KvpFrameqof_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)

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.


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 766 of file kvpframe.h.


Enumeration Type Documentation

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_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.


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.

00213 {
00214     GSList *result_list = NULL;
00215     g_hash_table_foreach (table, kv_pair_helper, &result_list);
00216     return result_list;
00217 }

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 598 of file kvpframe.c.

00599 {
00600     KvpValue *value;
00601     value = kvp_value_new_double (dval);
00602     frame = kvp_frame_add_value_nc (frame, path, value);
00603     if (!frame)
00604         kvp_value_delete (value);
00605 }

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 659 of file kvpframe.c.

00660 {
00661     KvpValue *value;
00662     value = kvp_value_new_frame (fr);
00663     frame = kvp_frame_add_value_nc (frame, path, value);
00664     if (!frame)
00665         kvp_value_delete (value);
00666 }

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 669 of file kvpframe.c.

00670 {
00671     KvpValue *value;
00672     value = kvp_value_new_frame_nc (fr);
00673     frame = kvp_frame_add_value_nc (frame, path, value);
00674     if (!frame)
00675         kvp_value_delete (value);
00676 }

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 588 of file kvpframe.c.

00589 {
00590     KvpValue *value;
00591     value = kvp_value_new_gint64 (ival);
00592     frame = kvp_frame_add_value_nc (frame, path, value);
00593     if (!frame)
00594         kvp_value_delete (value);
00595 }

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 649 of file kvpframe.c.

00650 {
00651     KvpValue *value;
00652     value = kvp_value_new_guid (guid);
00653     frame = kvp_frame_add_value_nc (frame, path, value);
00654     if (!frame)
00655         kvp_value_delete (value);
00656 }

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 608 of file kvpframe.c.

00610 {
00611     KvpValue *value;
00612     value = kvp_value_new_numeric (nval);
00613     frame = kvp_frame_add_value_nc (frame, path, value);
00614     if (!frame)
00615         kvp_value_delete (value);
00616 }

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 639 of file kvpframe.c.

00640 {
00641     KvpValue *value;
00642     value = kvp_value_new_string (str);
00643     frame = kvp_frame_add_value_nc (frame, path, value);
00644     if (!frame)
00645         kvp_value_delete (value);
00646 }

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 619 of file kvpframe.c.

00620 {
00621     KvpValue *value;
00622     value = kvp_value_new_time (qt);
00623     frame = kvp_frame_add_value_nc (frame, path, value);
00624     if (!frame)
00625         kvp_value_delete (value);
00626 }

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 877 of file kvpframe.c.

00878 {
00879     gchar *buff, *p;
00880     if (!frame || !enc)
00881         return;
00882 
00883     /* Loop over all key-value pairs in the encoded string */
00884     buff = g_strdup (enc);
00885     p = buff;
00886     while (*p)
00887     {
00888         gchar *n, *v;
00889         n = strchr (p, '&');    /* n = next key-value */
00890         if (n)
00891             *n = 0x0;
00892 
00893         v = strchr (p, '=');    /* v =  pointer to value */
00894         if (!v)
00895             break;
00896         *v = 0x0;
00897         v++;
00898 
00899         decode (p);
00900         decode (v);
00901         kvp_frame_set_slot_nc (frame, p, kvp_value_new_string (v));
00902 
00903         if (!n)
00904             break;              /* no next key, we are done */
00905         p = ++n;
00906     }
00907 
00908     g_free (buff);
00909 }

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 578 of file kvpframe.c.

00579 {
00580     value = kvp_value_copy (value);
00581     frame = kvp_frame_add_value_nc (frame, path, value);
00582     if (!frame)
00583         kvp_value_delete (value);
00584     return frame;
00585 }

gint kvp_frame_compare ( const KvpFrame fa,
const KvpFrame fb 
)

Similar returns as strcmp.

Definition at line 1743 of file kvpframe.c.

01744 {
01745     KvpFrameCompare status;
01746 
01747     if (fa == fb)
01748         return 0;
01749     /* nothing is always less than something */
01750     if (!fa && fb)
01751         return -1;
01752     if (fa && !fb)
01753         return 1;
01754 
01755     /* nothing is always less than something */
01756     if (!fa->hash && fb->hash)
01757         return -1;
01758     if (fa->hash && !fb->hash)
01759         return 1;
01760 
01761     status.compare = 0;
01762     status.other_frame = (KvpFrame *) fb;
01763 
01764     kvp_frame_for_each_slot ((KvpFrame *) fa, kvp_frame_compare_helper,
01765         &status);
01766 
01767     if (status.compare != 0)
01768         return status.compare;
01769 
01770     status.other_frame = (KvpFrame *) fa;
01771 
01772     kvp_frame_for_each_slot ((KvpFrame *) fb, kvp_frame_compare_helper,
01773         &status);
01774 
01775     return (-status.compare);
01776 }

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 153 of file kvpframe.c.

00154 {
00155     KvpFrame *retval = kvp_frame_new ();
00156 
00157     if (!frame)
00158         return retval;
00159 
00160     if (frame->hash)
00161     {
00162         if (!init_frame_body_if_needed (retval))
00163             return (NULL);
00164         g_hash_table_foreach (frame->hash,
00165             &kvp_frame_copy_worker, (gpointer) retval);
00166     }
00167     return retval;
00168 }

void kvp_frame_delete ( KvpFrame frame  ) 

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

Definition at line 115 of file kvpframe.c.

00116 {
00117     if (!frame)
00118         return;
00119 
00120     if (frame->hash)
00121     {
00122         /* free any allocated resource for frame or its children */
00123         g_hash_table_foreach (frame->hash, &kvp_frame_delete_worker,
00124             (gpointer) frame);
00125 
00126         /* delete the hash table */
00127         g_hash_table_destroy (frame->hash);
00128         frame->hash = NULL;
00129     }
00130     g_free (frame);
00131 }

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 1642 of file kvpframe.c.

01643 {
01644     if (!f)
01645         return;
01646     if (!proc)
01647         return;
01648     if (!(f->hash))
01649         return;
01650     g_hash_table_foreach (f->hash, (GHFunc) proc, data);
01651 }

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 981 of file kvpframe.c.

00982 {
00983     gchar *key = NULL;
00984     frame = get_trailer_or_null (frame, path, &key);
00985     return kvp_value_get_frame (kvp_frame_get_slot (frame, key));
00986 }

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 999 of file kvpframe.c.

01000 {
01001     if (!frame)
01002         return frame;
01003 
01004     while (key_path)
01005     {
01006         const gchar *key = key_path->data;
01007 
01008         if (!key)
01009             return frame;       /* an unusual but valid exit for this routine. */
01010 
01011         frame = get_or_make (frame, key);
01012         if (!frame)
01013             return frame;       /* this should never happen */
01014 
01015         key_path = key_path->next;
01016     }
01017     return frame;               /* this is the normal exit for this func */
01018 }

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 1021 of file kvpframe.c.

01022 {
01023     va_list ap;
01024     if (!frame || !key)
01025         return frame;
01026 
01027     va_start (ap, key);
01028 
01029     while (key)
01030     {
01031         frame = get_or_make (frame, key);
01032         if (!frame)
01033             break;              /* error, should never occur */
01034         key = va_arg (ap, const char *);
01035     }
01036 
01037     va_end (ap);
01038     return frame;
01039 }

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 1042 of file kvpframe.c.

01043 {
01044     gchar *root;
01045     if (!frame || !key_path)
01046         return frame;
01047 
01048     root = g_strdup (key_path);
01049     frame = kvp_frame_get_frame_slash_trash (frame, root);
01050     g_free (root);
01051     return frame;
01052 }

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 1057 of file kvpframe.c.

01058 {
01059     va_list ap;
01060     KvpValue *value;
01061     const gchar *key;
01062 
01063     if (!frame || !first_key)
01064         return NULL;
01065 
01066     va_start (ap, first_key);
01067 
01068     key = first_key;
01069     value = NULL;
01070 
01071     while (TRUE)
01072     {
01073         value = kvp_frame_get_slot (frame, key);
01074         if (!value)
01075             break;
01076 
01077         key = va_arg (ap, const gchar *);
01078         if (!key)
01079             break;
01080 
01081         frame = kvp_value_get_frame (value);
01082         if (!frame)
01083         {
01084             value = NULL;
01085             break;
01086         }
01087     }
01088 
01089     va_end (ap);
01090 
01091     return value;
01092 }

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 1095 of file kvpframe.c.

01096 {
01097     if (!frame || !key_path)
01098         return NULL;
01099 
01100     while (TRUE)
01101     {
01102         const gchar *key = key_path->data;
01103         KvpValue *value;
01104 
01105         if (!key)
01106             return NULL;
01107 
01108         value = kvp_frame_get_slot (frame, key);
01109         if (!value)
01110             return NULL;
01111 
01112         key_path = key_path->next;
01113         if (!key_path)
01114             return value;
01115 
01116         frame = kvp_value_get_frame (value);
01117         if (!frame)
01118             return NULL;
01119     }
01120 }

gboolean kvp_frame_is_empty ( KvpFrame frame  ) 

Return TRUE if the KvpFrame is empty

Definition at line 134 of file kvpframe.c.

00135 {
00136     if (!frame)
00137         return TRUE;
00138     if (!frame->hash)
00139         return TRUE;
00140     return FALSE;
00141 }

KvpFrame* kvp_frame_new ( void   ) 

Return a new empty instance of KvpFrame

Definition at line 97 of file kvpframe.c.

00098 {
00099     KvpFrame *retval = g_new0 (KvpFrame, 1);
00100 
00101     /* Save space until the frame is actually used */
00102     retval->hash = NULL;
00103     return retval;
00104 }

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 175 of file kvpframe.c.

00177 {
00178     gpointer orig_key;
00179     gpointer orig_value = NULL;
00180     int key_exists;
00181 
00182     if (!frame || !slot)
00183         return NULL;
00184     if (!init_frame_body_if_needed (frame))
00185         return NULL;            /* Error ... */
00186 
00187     key_exists = g_hash_table_lookup_extended (frame->hash, slot,
00188         &orig_key, &orig_value);
00189     if (key_exists)
00190     {
00191         g_hash_table_remove (frame->hash, slot);
00192         qof_util_string_cache_remove (orig_key);
00193     }
00194     else
00195         orig_value = NULL;
00196     if (new_value)
00197         g_hash_table_insert (frame->hash,
00198             qof_util_string_cache_insert ((gpointer) slot), new_value);
00199     return (KvpValue *) orig_value;
00200 }

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 513 of file kvpframe.c.

00515 {
00516     KvpValue *old_value;
00517     gchar *last_key;
00518 
00519     last_key = NULL;
00520     if (new_value)
00521         frame = get_trailer_make (frame, key_path, &last_key);
00522     else
00523         frame =
00524             (KvpFrame *) get_trailer_or_null (frame, key_path, &last_key);
00525     if (!frame)
00526         return NULL;
00527 
00528     old_value = kvp_frame_replace_slot_nc (frame, last_key, new_value);
00529     return old_value;
00530 }

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 428 of file kvpframe.c.

00430 {
00431     KvpValue * value;
00432     value = kvp_value_new_boolean (val);
00433     frame = kvp_frame_set_value_nc (frame, path, value);
00434     if (!frame)
00435         kvp_value_delete (value);
00436 }

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 397 of file kvpframe.c.

00398 {
00399     KvpValue *value;
00400     value = kvp_value_new_double (dval);
00401     frame = kvp_frame_set_value_nc (frame, path, value);
00402     if (!frame)
00403         kvp_value_delete (value);
00404 }

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 461 of file kvpframe.c.

00462 {
00463     KvpValue *value;
00464     value = kvp_value_new_frame (fr);
00465     frame = kvp_frame_set_value_nc (frame, path, value);
00466     if (!frame)
00467         kvp_value_delete (value);
00468 }

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 471 of file kvpframe.c.

00472 {
00473     KvpValue *value;
00474     value = kvp_value_new_frame_nc (fr);
00475     frame = kvp_frame_set_value_nc (frame, path, value);
00476     if (!frame)
00477         kvp_value_delete (value);
00478 }

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 387 of file kvpframe.c.

00388 {
00389     KvpValue *value;
00390     value = kvp_value_new_gint64 (ival);
00391     frame = kvp_frame_set_value_nc (frame, path, value);
00392     if (!frame)
00393         kvp_value_delete (value);
00394 }

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 450 of file kvpframe.c.

00452 {
00453     KvpValue *value;
00454     value = kvp_value_new_guid (guid);
00455     frame = kvp_frame_set_value_nc (frame, path, value);
00456     if (!frame)
00457         kvp_value_delete (value);
00458 }

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 417 of file kvpframe.c.

00419 {
00420     KvpValue *value;
00421     value = kvp_value_new_numeric (nval);
00422     frame = kvp_frame_set_value_nc (frame, path, value);
00423     if (!frame)
00424         kvp_value_delete (value);
00425 }

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 681 of file kvpframe.c.

00683 {
00684     KvpValue *new_value = NULL;
00685 
00686     if (!frame)
00687         return;
00688 
00689     g_return_if_fail (slot && *slot != '\0');
00690 
00691     if (value)
00692         new_value = kvp_value_copy (value);
00693     kvp_frame_set_slot_destructively (frame, slot, new_value);
00694 }

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 697 of file kvpframe.c.

00699 {
00700     if (!frame)
00701         return;
00702 
00703     g_return_if_fail (slot && *slot != '\0');
00704 
00705     kvp_frame_set_slot_destructively (frame, slot, value);
00706 }

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 723 of file kvpframe.c.

00725 {
00726     va_list ap;
00727     const gchar *key;
00728 
00729     if (!frame)
00730         return;
00731 
00732     g_return_if_fail (first_key && *first_key != '\0');
00733 
00734     va_start (ap, first_key);
00735 
00736     key = first_key;
00737 
00738     while (TRUE)
00739     {
00740         KvpValue *value;
00741         const gchar *next_key;
00742 
00743         next_key = va_arg (ap, const gchar *);
00744         if (!next_key)
00745         {
00746             kvp_frame_set_slot (frame, key, new_value);
00747             break;
00748         }
00749 
00750         g_return_if_fail (*next_key != '\0');
00751 
00752         value = kvp_frame_get_slot (frame, key);
00753         if (!value)
00754         {
00755             KvpFrame *new_frame = kvp_frame_new ();
00756             KvpValue *frame_value = kvp_value_new_frame (new_frame);
00757 
00758             kvp_frame_set_slot_nc (frame, key, frame_value);
00759 
00760             value = kvp_frame_get_slot (frame, key);
00761             if (!value)
00762                 break;
00763         }
00764 
00765         frame = kvp_value_get_frame (value);
00766         if (!frame)
00767             break;
00768 
00769         key = next_key;
00770     }
00771 
00772     va_end (ap);
00773 }

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 776 of file kvpframe.c.

00778 {
00779     if (!frame || !key_path)
00780         return;
00781 
00782     while (TRUE)
00783     {
00784         const gchar *key = key_path->data;
00785         KvpValue *value;
00786 
00787         if (!key)
00788             return;
00789 
00790         g_return_if_fail (*key != '\0');
00791 
00792         key_path = key_path->next;
00793         if (!key_path)
00794         {
00795             kvp_frame_set_slot (frame, key, new_value);
00796             return;
00797         }
00798 
00799         value = kvp_frame_get_slot (frame, key);
00800         if (!value)
00801         {
00802             KvpFrame *new_frame = kvp_frame_new ();
00803             KvpValue *frame_value = kvp_value_new_frame (new_frame);
00804 
00805             kvp_frame_set_slot_nc (frame, key, frame_value);
00806 
00807             value = kvp_frame_get_slot (frame, key);
00808             if (!value)
00809                 return;
00810         }
00811 
00812         frame = kvp_value_get_frame (value);
00813         if (!frame)
00814             return;
00815     }
00816 }

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 439 of file kvpframe.c.

00441 {
00442     KvpValue *value;
00443     value = kvp_value_new_string (str);
00444     frame = kvp_frame_set_value_nc (frame, path, value);
00445     if (!frame)
00446         kvp_value_delete (value);
00447 }

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 407 of file kvpframe.c.

00408 {
00409     KvpValue *value;
00410     value = kvp_value_new_time (qt);
00411     frame = kvp_frame_set_value_nc (frame, path, value);
00412     if (!frame)
00413         kvp_value_delete (value);
00414 }

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 496 of file kvpframe.c.

00498 {
00499     KvpValue *new_value = NULL;
00500     gchar *last_key;
00501 
00502     frame = get_trailer_make (frame, key_path, &last_key);
00503     if (!frame)
00504         return NULL;
00505 
00506     if (value)
00507         new_value = kvp_value_copy (value);
00508     kvp_frame_set_slot_destructively (frame, last_key, new_value);
00509     return frame;
00510 }

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 483 of file kvpframe.c.

00485 {
00486     gchar *last_key;
00487 
00488     frame = get_trailer_make (frame, key_path, &last_key);
00489     if (!frame)
00490         return NULL;
00491     kvp_frame_set_slot_destructively (frame, last_key, value);
00492     return frame;
00493 }

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 1167 of file kvpframe.c.

01168 {
01169     const GList *lp1;
01170     const GList *lp2;
01171 
01172     if (list1 == list2)
01173         return 0;
01174 
01175     /* Nothing is always less than something */
01176     if (!list1 && list2)
01177         return -1;
01178     if (list1 && !list2)
01179         return 1;
01180 
01181     lp1 = list1;
01182     lp2 = list2;
01183     while (lp1 && lp2)
01184     {
01185         KvpValue *v1 = (KvpValue *) lp1->data;
01186         KvpValue *v2 = (KvpValue *) lp2->data;
01187         gint vcmp = kvp_value_compare (v1, v2);
01188         if (vcmp != 0)
01189             return vcmp;
01190         lp1 = lp1->next;
01191         lp2 = lp2->next;
01192     }
01193     if (!lp1 && lp2)
01194         return -1;
01195     if (!lp2 && lp1)
01196         return 1;
01197     return 0;
01198 }

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 1145 of file kvpframe.c.

01146 {
01147     GList *retval = NULL;
01148     GList *lptr;
01149 
01150     if (!list)
01151         return retval;
01152 
01153     /* Duplicate the backbone of the list (this duplicates the POINTERS
01154      * to the values; we need to deep-copy the values separately) */
01155     retval = g_list_copy ((GList *) list);
01156 
01157     /* This step deep-copies the values */
01158     for (lptr = retval; lptr; lptr = lptr->next)
01159     {
01160         lptr->data = kvp_value_copy (lptr->data);
01161     }
01162 
01163     return retval;
01164 }

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 1127 of file kvpframe.c.

01128 {
01129     GList *node;
01130     if (!list)
01131         return;
01132 
01133     /* Delete the data in the list */
01134     for (node = list; node; node = node->next)
01135     {
01136         KvpValue *val = node->data;
01137         kvp_value_delete (val);
01138     }
01139 
01140     /* Free the backbone */
01141     g_list_free (list);
01142 }

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 1654 of file kvpframe.c.

01655 {
01656     if (kva == kvb)
01657         return 0;
01658     /* nothing is always less than something */
01659     if (!kva && kvb)
01660         return -1;
01661     if (kva && !kvb)
01662         return 1;
01663 
01664     if (kva->type < kvb->type)
01665         return -1;
01666     if (kva->type > kvb->type)
01667         return 1;
01668 
01669     switch (kva->type)
01670     {
01671     case KVP_TYPE_GINT64:
01672         if (kva->value.int64 < kvb->value.int64)
01673             return -1;
01674         if (kva->value.int64 > kvb->value.int64)
01675             return 1;
01676         return 0;
01677         break;
01678     case KVP_TYPE_DOUBLE:
01679         return qof_util_double_compare (kva->value.dbl, kvb->value.dbl);
01680         break;
01681     case KVP_TYPE_NUMERIC:
01682         return qof_numeric_compare (kva->value.numeric,
01683             kvb->value.numeric);
01684         break;
01685     case KVP_TYPE_STRING:
01686         return strcmp (kva->value.str, kvb->value.str);
01687         break;
01688     case KVP_TYPE_GUID:
01689         return guid_compare (kva->value.guid, kvb->value.guid);
01690         break;
01691     case KVP_TYPE_BOOLEAN:
01692     {
01693         /* true > false */
01694         if (kva->value.gbool != kvb->value.gbool)
01695             return (kva->value.gbool) ? 1 : -1;
01696         return 0;
01697         break;
01698     }
01699     case KVP_TYPE_TIME :
01700         return qof_time_cmp (kva->value.qt, kvb->value.qt);
01701         break;
01702     case KVP_TYPE_BINARY:
01703         if (kva->value.binary.datasize < kvb->value.binary.datasize)
01704             return -1;
01705         if (kva->value.binary.datasize > kvb->value.binary.datasize)
01706             return 1;
01707         return memcmp (kva->value.binary.data,
01708             kvb->value.binary.data, kva->value.binary.datasize);
01709         break;
01710     case KVP_TYPE_GLIST:
01711         return kvp_glist_compare (kva->value.list, kvb->value.list);
01712         break;
01713     case KVP_TYPE_FRAME:
01714         return kvp_frame_compare (kva->value.frame, kvb->value.frame);
01715         break;
01716     }
01717     return 0;
01718 }

KvpValue* kvp_value_copy ( const KvpValue value  ) 

This is a deep value copy.

Definition at line 1598 of file kvpframe.c.

01599 {
01600     if (!value)
01601         return NULL;
01602 
01603     switch (value->type)
01604     {
01605     case KVP_TYPE_GINT64:
01606         return kvp_value_new_gint64 (value->value.int64);
01607         break;
01608     case KVP_TYPE_DOUBLE:
01609         return kvp_value_new_double (value->value.dbl);
01610         break;
01611     case KVP_TYPE_NUMERIC:
01612         return kvp_value_new_numeric (value->value.numeric);
01613         break;
01614     case KVP_TYPE_STRING:
01615         return kvp_value_new_string (value->value.str);
01616         break;
01617     case KVP_TYPE_GUID:
01618         return kvp_value_new_guid (value->value.guid);
01619         break;
01620     case KVP_TYPE_BOOLEAN:
01621         return NULL;
01622         return kvp_value_new_boolean (value->value.gbool);
01623         break;
01624     case KVP_TYPE_TIME :
01625         return kvp_value_new_time (value->value.qt);
01626         break;
01627     case KVP_TYPE_BINARY:
01628         return kvp_value_new_binary (value->value.binary.data,
01629             value->value.binary.datasize);
01630         break;
01631     case KVP_TYPE_GLIST:
01632         return kvp_value_new_glist (value->value.list);
01633         break;
01634     case KVP_TYPE_FRAME:
01635         return kvp_value_new_frame (value->value.frame);
01636         break;
01637     }
01638     return NULL;
01639 }

void kvp_value_delete ( KvpValue value  ) 

This is a deep (recursive) delete.

Definition at line 1358 of file kvpframe.c.

01359 {
01360     if (!value)
01361         return;
01362 
01363     switch (value->type)
01364     {
01365     case KVP_TYPE_STRING:
01366         g_free (value->value.str);
01367         break;
01368     case KVP_TYPE_GUID:
01369         g_free (value->value.guid);
01370         break;
01371     case KVP_TYPE_BINARY:
01372         g_free (value->value.binary.data);
01373         break;
01374     case KVP_TYPE_GLIST:
01375         kvp_glist_delete (value->value.list);
01376         break;
01377     case KVP_TYPE_FRAME:
01378         kvp_frame_delete (value->value.frame);
01379         break;
01380     case KVP_TYPE_BOOLEAN:
01381     case KVP_TYPE_GINT64:
01382     case KVP_TYPE_DOUBLE:
01383     case KVP_TYPE_NUMERIC:
01384     default:
01385         break;
01386     }
01387     g_free (value);
01388 }

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 1504 of file kvpframe.c.

01505 {
01506     if (!value)
01507     {
01508         if (size_return)
01509             *size_return = 0;
01510         PERR (" no size specified");
01511         return NULL;
01512     }
01513 
01514     if (value->type == KVP_TYPE_BINARY)
01515     {
01516         if (size_return)
01517             *size_return = value->value.binary.datasize;
01518         return value->value.binary.data;
01519     }
01520     else
01521     {
01522         if (size_return)
01523             *size_return = 0;
01524         PERR (" value type %d does not match KVP_TYPE_BINARY",
01525             value->type);
01526         return NULL;
01527     }
01528 }

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 1546 of file kvpframe.c.

01547 {
01548     if (!value)
01549         return NULL;
01550     if (value->type == KVP_TYPE_FRAME)
01551         return value->value.frame;
01552     else
01553     {
01554         PERR (" value type %d does not match KVP_TYPE_FRAME",
01555             value->type);
01556         return NULL;
01557     }
01558 }

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 1399 of file kvpframe.c.

01400 {
01401     if (!value)
01402         return 0;
01403     if (value->type == KVP_TYPE_GINT64)
01404         return value->value.int64;
01405     else
01406     {
01407         PERR (" value type %d does not match KVP_TYPE_GINT64",
01408             value->type);
01409         return 0;
01410     }
01411 }

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 1531 of file kvpframe.c.

01532 {
01533     if (!value)
01534         return NULL;
01535     if (value->type == KVP_TYPE_GLIST)
01536         return value->value.list;
01537     else
01538     {
01539         PERR (" value type %d does not match KVP_TYPE_GLIST",
01540             value->type);
01541         return NULL;
01542     }
01543 }

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 1474 of file kvpframe.c.

01475 {
01476     if (!value)
01477         return NULL;
01478     if (value->type == KVP_TYPE_GUID)
01479         return value->value.guid;
01480     else
01481     {
01482         PERR (" value type %d does not match KVP_TYPE_GUID",
01483             value->type);
01484         return NULL;
01485     }
01486 }

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 1444 of file kvpframe.c.

01445 {
01446     if (!value)
01447         return NULL;
01448     if (value->type == KVP_TYPE_STRING)
01449         return value->value.str;
01450     else
01451     {
01452         PERR (" value type %d does not match KVP_TYPE_STRING",
01453             value->type);
01454         return NULL;
01455     }
01456 }

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 1223 of file kvpframe.c.

01224 {
01225     KvpValue * retval = g_new0 (KvpValue, 1);
01226     retval->type = KVP_TYPE_BOOLEAN;
01227     retval->value.gbool = value;
01228     return retval;
01229 }

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 1345 of file kvpframe.c.

01346 {
01347     KvpValue *retval;
01348     if (!value)
01349         return NULL;
01350 
01351     retval = g_new0 (KvpValue, 1);
01352     retval->type = KVP_TYPE_FRAME;
01353     retval->value.frame = value;
01354     return retval;
01355 }

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 1306 of file kvpframe.c.

01307 {
01308     KvpValue *retval;
01309     if (!value)
01310         return NULL;
01311 
01312     retval = g_new0 (KvpValue, 1);
01313     retval->type = KVP_TYPE_GLIST;
01314     retval->value.list = kvp_glist_copy (value);
01315     return retval;
01316 }

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 1319 of file kvpframe.c.

01320 {
01321     KvpValue *retval;
01322     if (!value)
01323         return NULL;
01324 
01325     retval = g_new0 (KvpValue, 1);
01326     retval->type = KVP_TYPE_GLIST;
01327     retval->value.list = value;
01328     return retval;
01329 }

KvpFrame* kvp_value_replace_frame_nc ( KvpValue value,
KvpFrame newframe 
)

Replace old frame value with new, return old frame

Definition at line 1561 of file kvpframe.c.

01562 {
01563     KvpFrame *oldframe;
01564     if (!value)
01565         return NULL;
01566     if (KVP_TYPE_FRAME != value->type)
01567     {
01568         PERR (" value type %d does not match KVP_TYPE_FRAME",
01569             value->type);
01570         return NULL;
01571     }
01572     oldframe = value->value.frame;
01573     value->value.frame = newframe;
01574     return oldframe;
01575 }

GList* kvp_value_replace_glist_nc ( KvpValue value,
GList *  newlist 
)

Replace old glist value with new, return old glist

Definition at line 1578 of file kvpframe.c.

01579 {
01580     GList *oldlist;
01581     if (!value)
01582         return NULL;
01583     if (KVP_TYPE_GLIST != value->type)
01584     {
01585         PERR (" value type %d does not match KVP_TYPE_GLIST",
01586             value->type);
01587         return NULL;
01588     }
01589 
01590     oldlist = value->value.list;
01591     value->value.list = newlist;
01592     return oldlist;
01593 }

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 1834 of file kvpframe.c.

01835 {
01836     gchar *tmp1;
01837     gchar *tmp2;
01838     const gchar *ctmp;
01839 
01840     g_return_val_if_fail (val, NULL);
01841     tmp1 = g_strdup ("");
01842     switch (kvp_value_get_type (val))
01843     {
01844         case KVP_TYPE_GINT64:
01845         {
01846             return g_strdup_printf ("%" G_GINT64_FORMAT,
01847                 kvp_value_get_gint64 (val));
01848             break;
01849         }
01850         case KVP_TYPE_DOUBLE:
01851         {
01852             return g_strdup_printf ("(%g)", kvp_value_get_double (val));
01853             break;
01854         }
01855         case KVP_TYPE_NUMERIC:
01856         {
01857             tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
01858             tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
01859             g_free (tmp1);
01860             return tmp2;
01861             break;
01862         }
01863         case KVP_TYPE_STRING:
01864         {
01865             tmp1 = kvp_value_get_string (val);
01866             return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
01867             break;
01868         }
01869         case KVP_TYPE_GUID:
01870         {
01871             ctmp = guid_to_string (kvp_value_get_guid (val));
01872             tmp2 = g_strdup_printf ("%s", ctmp ? ctmp : "");
01873             return tmp2;
01874             break;
01875         }
01876         case KVP_TYPE_BOOLEAN :
01877             return (kvp_value_get_boolean (val)) ? "TRUE" : "FALSE";
01878         case KVP_TYPE_BINARY:
01879         {
01880             guint64 len;
01881             gpointer data;
01882             data = kvp_value_get_binary (val, &len);
01883             tmp1 = binary_to_string (data, len);
01884             return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
01885             break;
01886         }
01887         case KVP_TYPE_GLIST:
01888         /* borked. kvp_value_glist_to_string is a debug fcn */
01889         {
01890             tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
01891             tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
01892             g_free (tmp1);
01893             return tmp2;
01894             break;
01895         }
01896         case KVP_TYPE_FRAME:
01897         {
01898             KvpFrame *frame;
01899 
01900             frame = kvp_value_get_frame (val);
01901             if (frame->hash)
01902             {
01903                 tmp1 = g_strdup ("");
01904                 g_hash_table_foreach (frame->hash,
01905                     kvp_frame_to_bare_string_helper, &tmp1);
01906             }
01907             return tmp1;
01908             break;
01909         }
01910         default:
01911             return g_strdup_printf (" ");
01912             break;
01913     }
01914 }

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 1917 of file kvpframe.c.

01918 {
01919     gchar *tmp1;
01920     gchar *tmp2;
01921     const gchar *ctmp;
01922 
01923     g_return_val_if_fail (val, NULL);
01924 
01925     switch (kvp_value_get_type (val))
01926     {
01927         case KVP_TYPE_GINT64:
01928         {
01929             return g_strdup_printf ("KVP_VALUE_GINT64(%" G_GINT64_FORMAT ")",
01930                 kvp_value_get_gint64 (val));
01931             break;
01932         }
01933         case KVP_TYPE_DOUBLE:
01934         {
01935             return g_strdup_printf ("KVP_VALUE_DOUBLE(%g)",
01936                 kvp_value_get_double (val));
01937             break;
01938         }
01939         case KVP_TYPE_NUMERIC:
01940         {
01941             tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
01942             tmp2 = g_strdup_printf ("KVP_VALUE_NUMERIC(%s)", tmp1 ? tmp1 : "");
01943             g_free (tmp1);
01944             return tmp2;
01945             break;
01946         }
01947         case KVP_TYPE_STRING:
01948         {
01949             tmp1 = kvp_value_get_string (val);
01950             return g_strdup_printf ("KVP_VALUE_STRING(%s)", tmp1 ? tmp1 : "");
01951             break;
01952         }
01953         case KVP_TYPE_GUID:
01954         {
01955             /* THREAD-UNSAFE */
01956             ctmp = guid_to_string (kvp_value_get_guid (val));
01957             tmp2 = g_strdup_printf ("KVP_VALUE_GUID(%s)", ctmp ? ctmp : "");
01958             return tmp2;
01959             break;
01960         }
01961         case KVP_TYPE_BINARY:
01962         {
01963             guint64 len;
01964             gpointer data;
01965             data = kvp_value_get_binary (val, &len);
01966             tmp1 = binary_to_string (data, len);
01967             return g_strdup_printf ("KVP_VALUE_BINARY(%s)",
01968                 tmp1 ? tmp1 : "");
01969             break;
01970         }
01971         case KVP_TYPE_GLIST:
01972         {
01973             tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
01974             tmp2 = g_strdup_printf ("KVP_VALUE_GLIST(%s)", tmp1 ? tmp1 : "");
01975             g_free (tmp1);
01976             return tmp2;
01977             break;
01978         }
01979         case KVP_TYPE_FRAME:
01980         {
01981             tmp1 = kvp_frame_to_string (kvp_value_get_frame (val));
01982             tmp2 = g_strdup_printf ("KVP_VALUE_FRAME(%s)", tmp1 ? tmp1 : "");
01983             g_free (tmp1);
01984             return tmp2;
01985             break;
01986         }
01987         default:
01988             return g_strdup_printf (" ");
01989             break;
01990     }
01991 }

QofIdTypeConst kvp_value_type_to_qof_id ( KvpValueType  n  ) 

Convert a KvpValueType to a QofIdType.

Used by various backends to convert QofParam into SQL structures.

Note:
Not all KvpValueType types can be converted to QofIdTypeConst, in particular KVP_TYPE_BINARY, KVP_TYPE_GLIST and KVP_TYPE_FRAME
Returns:
The QofIdTypeConst or NULL if the type cannot be converted.

Definition at line 246 of file kvputil.c.

00247 {
00248     switch (n)
00249     {
00250         case KVP_TYPE_GINT64:
00251         {
00252             return QOF_TYPE_INT64;
00253             break;
00254         }
00255         case KVP_TYPE_DOUBLE:
00256         {
00257             return QOF_TYPE_DOUBLE;
00258             break;
00259         }
00260         case KVP_TYPE_NUMERIC:
00261         {
00262             return QOF_TYPE_NUMERIC;
00263             break;
00264         }
00265         case KVP_TYPE_STRING:
00266         {
00267             return QOF_TYPE_STRING;
00268             break;
00269         }
00270         case KVP_TYPE_GUID:
00271         {
00272             return QOF_TYPE_GUID;
00273             break;
00274         }
00275         case KVP_TYPE_BOOLEAN :
00276         {
00277             return QOF_TYPE_BOOLEAN;
00278             break;
00279         }
00280         case KVP_TYPE_TIME :
00281         {
00282             return QOF_TYPE_TIME;
00283             break;
00284         }
00285         default:
00286         {
00287             return NULL;
00288         }
00289     }
00290 }

KvpValueType qof_id_to_kvp_value_type ( QofIdTypeConst  type_string  ) 

Convert a QofIdType to a KvpValueType.

Used by various backends to convert QofParam into SQL structures.

Note:
Not all KvpValueType types can be converted to QofIdTypeConst, in particular KVP_TYPE_BINARY, KVP_TYPE_GLIST and KVP_TYPE_FRAME
Returns:
The KvpValueType or zero if the type cannot be converted.

Definition at line 228 of file kvputil.c.

00229 {
00230     if (0 == safe_strcmp (QOF_TYPE_INT64, type_string))
00231         return KVP_TYPE_GINT64;
00232     if (0 == safe_strcmp (QOF_TYPE_DOUBLE, type_string))
00233         return KVP_TYPE_DOUBLE;
00234     if (0 == safe_strcmp (QOF_TYPE_NUMERIC, type_string))
00235         return KVP_TYPE_NUMERIC;
00236     if (0 == safe_strcmp (QOF_TYPE_STRING, type_string))
00237         return KVP_TYPE_STRING;
00238     if (0 == safe_strcmp (QOF_TYPE_GUID, type_string))
00239         return KVP_TYPE_GUID;
00240     if (0 == safe_strcmp (QOF_TYPE_TIME, type_string))
00241         return KVP_TYPE_TIME;
00242     return 0;
00243 }

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.

00069 {
00070     KvpFrame *cwd;
00071     va_list ap;
00072     va_start (ap, first_name);
00073     cwd = qof_kvp_array_va (pwd, path, qt, first_name, ap);
00074     va_end (ap);
00075     return cwd;
00076 }

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.

00091 {
00092     KvpValue *arr;
00093     KvpValueType valtype;
00094     GList *node;
00095 
00096     arr = kvp_frame_get_value (root, path);
00097     valtype = kvp_value_get_type (arr);
00098     if (KVP_TYPE_FRAME == valtype)
00099     {
00100         MATCH_GUID (arr);
00101         return NULL;
00102     }
00103 
00104     /* Its got to be a single isolated frame, or a list of them. */
00105     if (KVP_TYPE_GLIST != valtype)
00106         return NULL;
00107 
00108     for (node = kvp_value_get_glist (arr); node; node = node->next)
00109     {
00110         KvpValue *va = node->data;
00111         MATCH_GUID (va);
00112     }
00113     return NULL;
00114 }

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.

00188 {
00189     KvpFrame *fr;
00190 
00191     fr = qof_kvp_bag_get_first (kvp_from, frompath);
00192     while (fr)
00193     {
00194         qof_kvp_bag_remove_frame (kvp_from, frompath, fr);
00195         kvp_frame_add_frame_nc (kvp_into, intopath, fr);
00196         fr = qof_kvp_bag_get_first (kvp_from, frompath);
00197     }
00198 }

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.

00120 {
00121     KvpValue *arr;
00122     KvpValueType valtype;
00123     GList *node, *listhead;
00124 
00125     arr = kvp_frame_get_value (root, path);
00126     valtype = kvp_value_get_type (arr);
00127     if (KVP_TYPE_FRAME == valtype)
00128     {
00129         if (fr == kvp_value_get_frame (arr))
00130         {
00131             KvpValue *old_val =
00132                 kvp_frame_replace_value_nc (root, path, NULL);
00133             kvp_value_replace_frame_nc (old_val, NULL);
00134             kvp_value_delete (old_val);
00135         }
00136         return;
00137     }
00138 
00139     /* Its got to be a single isolated frame, or a list of them. */
00140     if (KVP_TYPE_GLIST != valtype)
00141         return;
00142 
00143     listhead = kvp_value_get_glist (arr);
00144     for (node = listhead; node; node = node->next)
00145     {
00146         KvpValue *va = node->data;
00147         if (fr == kvp_value_get_frame (va))
00148         {
00149             listhead = g_list_remove_link (listhead, node);
00150             g_list_free_1 (node);
00151             kvp_value_replace_glist_nc (arr, listhead);
00152             kvp_value_replace_frame_nc (va, NULL);
00153             kvp_value_delete (va);
00154             return;
00155         }
00156     }
00157 }


Generated on Sat Aug 15 15:46:32 2009 for QOF by  doxygen 1.5.9