kvp_frame.h File Reference

A key-value frame system. More...

#include "gnc-date.h"
#include "gnc-numeric.h"
#include "guid.h"

Go to the source code of this file.

Data Structures
struct	KvpItem
	Transfer of KVP to and from GValue, with the key. More...

Macros
#define	QOF_MOD_KVP   "qof.kvp"
#define	kvp_value_t   KvpValueType
#define	GNC_TYPE_VALUE_LIST   (gnc_value_list_get_type ())

Typedefs
typedef struct KvpFrameImpl	KvpFrame
typedef struct KvpValueImpl	KvpValue

Enumerations
enum	KvpValueType {   KVP_TYPE_INVALID = -1, KVP_TYPE_GINT64 = 1, KVP_TYPE_DOUBLE, KVP_TYPE_NUMERIC,   KVP_TYPE_STRING, KVP_TYPE_GUID, KVP_TYPE_TIMESPEC, KVP_TYPE_PLACEHOLDER_DONT_USE,   KVP_TYPE_GLIST, KVP_TYPE_FRAME, KVP_TYPE_GDATE }
	possible types in the union KvpValue More...

Functions
gchar *	kvp_value_to_string (const KvpValue *val)
	Debug version of kvp_value_to_string. More...
gchar *	kvp_frame_to_string (const KvpFrame *frame)
GValue *	kvp_frame_get_gvalue (KvpFrame *frame, const gchar *key)
void	kvp_frame_set_gvalue (KvpFrame *frame, const gchar *key, const GValue *value)
void	gnc_gvalue_free (GValue *value)
	Convenience function to release the value in a GValue acquired by kvp_frame_get_gvalue and to free the GValue. More...
GType	gnc_value_list_get_type (void)
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 (const KvpFrame *frame)
KvpFrame Glist Bag Storing
void	kvp_frame_add_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
	Store the given kvp_frame to the glist bag at the indicated path (non-copying) More...
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 GncGUID, 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 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)
double	kvp_frame_get_double (const KvpFrame *frame, const gchar *path)
gnc_numeric	kvp_frame_get_numeric (const KvpFrame *frame, const gchar *path)
const gchar *	kvp_frame_get_string (const KvpFrame *frame, const gchar *path)
GncGUID *	kvp_frame_get_guid (const KvpFrame *frame, const gchar *path)
Timespec	kvp_frame_get_timespec (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_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().
void	kvp_frame_set_slot (KvpFrame *frame, const gchar *key, KvpValue *value)
void	kvp_frame_set_slot_nc (KvpFrame *frame, const gchar *key, KvpValue *value)
void	kvp_frame_set_slot_path (KvpFrame *frame, KvpValue *value, const gchar *first_key,...)
void	kvp_frame_set_slot_path_gslist (KvpFrame *frame, 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, const 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)
GncGUID *	kvp_value_get_guid (const KvpValue *value)
GList *	kvp_value_get_glist (const KvpValue *value)
KvpFrame *	kvp_value_get_frame (const KvpValue *value)
Timespec	kvp_value_get_timespec (const KvpValue *value)
GDate	kvp_value_get_gdate (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 gchar *key, KvpValue *value, gpointer data), gpointer data)

KvpFrame Basic Value Storing
#define	kvp_frame_set_gnc_numeric   kvp_frame_set_numeric
const char **	kvp_frame_get_keys (const KvpFrame *frame)
void	kvp_frame_set_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
void	kvp_frame_set_double (KvpFrame *frame, const gchar *path, double dval)
void	kvp_frame_set_numeric (KvpFrame *frame, const gchar *path, gnc_numeric nval)
void	kvp_frame_set_timespec (KvpFrame *frame, const gchar *path, Timespec ts)
void	kvp_frame_set_string (KvpFrame *frame, const gchar *path, const gchar *str)
	Store a copy of the string at the indicated path. More...
void	kvp_frame_set_guid (KvpFrame *frame, const gchar *path, const GncGUID *guid)
void	kvp_frame_set_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
void	kvp_frame_set_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
KvpFrame *	kvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value)
KvpFrame *	kvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
KvpValue *	kvp_frame_replace_value_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_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 gchar *value)
KvpValue *	kvp_value_new_guid (const GncGUID *guid)
KvpValue *	kvp_value_new_timespec (Timespec timespec)
KvpValue *	kvp_value_new_frame (const KvpFrame *value)
KvpValue *	kvp_value_new_gdate (GDate date)
KvpValue *	kvp_value_new_glist (const GList *value)
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)

Detailed Description

A key-value frame system.

Author

Copyright (C) 2000 Bill Gribble

Copyright (C) 2003 Linas Vepstas linas.nosp@m.@lin.nosp@m.as.or.nosp@m.g

Definition in file kvp_frame.h.