QOF: kvpframe.h File Reference

QOF 0.7.5

Macros | Typedefs | Enumerations | Functions
kvpframe.h File Reference
Query Object Framework » KVP: Key-Value Pairs

A key-value frame system. More...

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

Go to the source code of this file.

## Macros
#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. More...
gchar * | kvp_value_to_string (const KvpValue *val)
| Debug version. More...
gboolean | kvp_value_binary_append (KvpValue *v, gpointer data, guint64 size)
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. More...
void | kvp_frame_set_double (KvpFrame *frame, const gchar *path, gdouble dval)
| store the value of the double at the indicated path. More...
void | kvp_frame_set_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
| store the value of the QofNumeric at the indicated path. More...
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 GUID *guid)
| Store a copy of the GUID at the indicated path. More...
void | kvp_frame_set_time (KvpFrame *frame, const gchar *path, QofTime *qt)
| Store a copy of the QofTime at the indicated path. More...
void | kvp_frame_set_boolean (KvpFrame *frame, const gchar *path, gboolean val)
| Store the value of the boolean at the indicated path. More...
void | kvp_frame_set_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Store a copy of the KvpFrame at the indicated path. More...
void | kvp_frame_set_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Store a KvpFrame at the indicated path without copying. More...
KvpFrame * | kvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value)
| Copy the KvpValue into the frame. More...
KvpFrame * | kvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
| Store the KvpValue in the frame without copying. More...
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 More...
void | kvp_frame_add_double (KvpFrame *frame, const gchar *path, gdouble dval)
| Add the value of the double to the glist bag. More...
void | kvp_frame_add_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
| Add the value of the QofNumeric to the glist bag. More...
void | kvp_frame_add_time (KvpFrame *frame, const gchar *path, QofTime *qt)
| Add the value of the QofTime to the glist bag. More...
void | kvp_frame_add_string (KvpFrame *frame, const gchar *path, const gchar *str)
| Copy the string to the glist bag at the indicated path. More...
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. More...
void | kvp_frame_add_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Copy the frame to the glist bag at the indicated path. More...
void | kvp_frame_add_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Add the frame to the glist bag without copying. More...
KvpFrame * | kvp_frame_add_value (KvpFrame *frame, const gchar *path, KvpValue *value)
| Add a copy of the value to the glist bag. More...
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)

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

## 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
  Copyright (c) 2006 Neil Williams linux.nosp@m.@cod.nosp@m.ehelp.nosp@m..co..nosp@m.uk

Definition in file kvpframe.h.