kvp_frame.h File Reference

---

Detailed Description

A key-value frame system.

Author:

Copyright (C) 2000 Bill Gribble

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

Definition in file kvp_frame.h.

#include <glib.h>
#include "gnc-date.h"
#include "gnc-numeric.h"
#include "guid.h"

Go to the source code of this file.

KvpFrame Basic Value Storing
#define	kvp_frame_set_gnc_numeric   kvp_frame_set_numeric
#define	kvp_frame_set_str   kvp_frame_set_string
void	kvp_frame_set_gint64 (KvpFrame *frame, const char *path, gint64 ival)
void	kvp_frame_set_double (KvpFrame *frame, const char *path, double dval)
void	kvp_frame_set_numeric (KvpFrame *frame, const char *path, gnc_numeric nval)
void	kvp_frame_set_timespec (KvpFrame *frame, const char *path, Timespec ts)
void	kvp_frame_set_string (KvpFrame *frame, const char *path, const char *str)
	Store a copy of the string at the indicated path.
void	kvp_frame_set_guid (KvpFrame *frame, const char *path, const GUID *guid)
void	kvp_frame_set_frame (KvpFrame *frame, const char *path, KvpFrame *chld)
void	kvp_frame_set_frame_nc (KvpFrame *frame, const char *path, KvpFrame *chld)
KvpFrame *	kvp_frame_set_value (KvpFrame *frame, const char *path, const KvpValue *value)
KvpFrame *	kvp_frame_set_value_nc (KvpFrame *frame, const char *path, KvpValue *value)
KvpValue *	kvp_frame_replace_value_nc (KvpFrame *frame, const char *slot, KvpValue *new_value)
KvpFrame Glist Bag Storing
#define	kvp_frame_add_gnc_numeric   kvp_frame_add_numeric
#define	kvp_frame_add_str   kvp_frame_add_string
void	kvp_frame_add_gint64 (KvpFrame *frame, const char *path, gint64 ival)
void	kvp_frame_add_double (KvpFrame *frame, const char *path, double dval)
void	kvp_frame_add_numeric (KvpFrame *frame, const char *path, gnc_numeric nval)
void	kvp_frame_add_timespec (KvpFrame *frame, const char *path, Timespec ts)
void	kvp_frame_add_string (KvpFrame *frame, const char *path, const char *str)
	Copy of the string to the glist bag at the indicated path.
void	kvp_frame_add_guid (KvpFrame *frame, const char *path, const GUID *guid)
void	kvp_frame_add_frame (KvpFrame *frame, const char *path, KvpFrame *chld)
void	kvp_frame_add_frame_nc (KvpFrame *frame, const char *path, KvpFrame *chld)
KvpFrame *	kvp_frame_add_value (KvpFrame *frame, const char *path, KvpValue *value)
KvpFrame *	kvp_frame_add_value_nc (KvpFrame *frame, const char *path, KvpValue *value)
KvpValue Constructors
You probably shouldn't be using these low-level routines The following routines are constructors for kvp_value. Those with pointer arguments copy in the value. The *_nc() versions do *not* copy in thier values, but use them directly.
#define	kvp_value_new_gnc_numeric   kvp_value_new_numeric
KvpValue *	kvp_value_new_gint64 (gint64 value)
KvpValue *	kvp_value_new_double (double value)
KvpValue *	kvp_value_new_numeric (gnc_numeric value)
KvpValue *	kvp_value_new_string (const char *value)
KvpValue *	kvp_value_new_guid (const GUID *guid)
KvpValue *	kvp_value_new_timespec (Timespec timespec)
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)
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 URL handling
void	kvp_frame_add_url_encoding (KvpFrame *frame, const char *enc)
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 char *path)
double	kvp_frame_get_double (const KvpFrame *frame, const char *path)
gnc_numeric	kvp_frame_get_numeric (const KvpFrame *frame, const char *path)
char *	kvp_frame_get_string (const KvpFrame *frame, const char *path)
GUID *	kvp_frame_get_guid (const KvpFrame *frame, const char *path)
void *	kvp_frame_get_binary (const KvpFrame *frame, const char *path, guint64 *size_return)
Timespec	kvp_frame_get_timespec (const KvpFrame *frame, const char *path)
KvpValue *	kvp_frame_get_value (const KvpFrame *frame, const char *path)
KvpFrame *	kvp_frame_get_frame (const KvpFrame *frame, const char *path)
KvpFrame *	kvp_frame_get_frame_path (KvpFrame *frame, const char *,...)
KvpFrame *	kvp_frame_get_frame_gslist (KvpFrame *frame, GSList *key_path)
KvpFrame *	kvp_frame_get_frame_slash (KvpFrame *frame, const char *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 char *slot, KvpValue *new_value)
void	kvp_frame_set_slot (KvpFrame *frame, const char *key, const KvpValue *value)
void	kvp_frame_set_slot_nc (KvpFrame *frame, const char *key, KvpValue *value)
void	kvp_frame_set_slot_path (KvpFrame *frame, const KvpValue *value, const char *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 char *key)
KvpValue *	kvp_frame_get_slot_path (KvpFrame *frame, const char *first_key,...)
KvpValue *	kvp_frame_get_slot_path_gslist (KvpFrame *frame, GSList *key_path)
gint	kvp_frame_compare (const KvpFrame *fa, const KvpFrame *fb)
gint	double_compare (double v1, double v2)
KvpValue List Convenience Functions
You probably shouldn't be using these low-level routines kvp_glist_compare() compares GLists of kvp_values (not to be confused with GLists of something else): it iterates over the list elements, performing a kvp_value_compare on each.
gint	kvp_glist_compare (const GList *list1, const GList *list2)
GList *	kvp_glist_copy (const GList *list)
void	kvp_glist_delete (GList *list)
KvpValue Value access
You probably shouldn't be using these low-level routines
KvpValueType	kvp_value_get_type (const KvpValue *value)
gint64	kvp_value_get_gint64 (const KvpValue *value)
double	kvp_value_get_double (const KvpValue *value)
gnc_numeric	kvp_value_get_numeric (const KvpValue *value)
char *	kvp_value_get_string (const KvpValue *value)
GUID *	kvp_value_get_guid (const KvpValue *value)
void *	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)
Timespec	kvp_value_get_timespec (const KvpValue *value)
gint	kvp_value_compare (const KvpValue *va, const KvpValue *vb)
Iterators
void	kvp_frame_for_each_slot (KvpFrame *f, void(*proc)(const char *key, KvpValue *value, gpointer data), gpointer data)
Defines
#define	QOF_MOD_KVP   "qof-kvp"
#define	kvp_frame   KvpFrame
#define	kvp_value   KvpValue
#define	kvp_value_t   KvpValueType
Typedefs
typedef _KvpFrame	KvpFrame
typedef _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_BINARY, KVP_TYPE_GLIST,   KVP_TYPE_FRAME }
	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 of kvp_value_to_string.
gboolean	kvp_value_binary_append (KvpValue *v, void *data, guint64 size)
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)

---