kvp_frame.h

Go to the documentation of this file.

/********************************************************************\
 * kvp_frame.h -- Implements a key-value frame system               *
 * This program is free software; you can redistribute it and/or    *
 * modify it under the terms of the GNU General Public License as   *
 * published by the Free Software Foundation; either version 2 of   *
 * the License, or (at your option) any later version.              *
 *                                                                  *
 * This program is distributed in the hope that it will be useful,  *
 * but WITHOUT ANY WARRANTY; without even the implied warranty of   *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the    *
 * GNU General Public License for more details.                     *
 *                                                                  *
 * You should have received a copy of the GNU General Public License*
 * along with this program; if not, contact:                        *
 *                                                                  *
 * Free Software Foundation           Voice:  +1-617-542-5942       *
 * 59 Temple Place - Suite 330        Fax:    +1-617-542-2652       *
 * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
 *                                                                  *
\********************************************************************/
#ifndef KVP_FRAME_H
#define KVP_FRAME_H

#include <glib.h>

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

#define QOF_MOD_KVP "qof-kvp"

typedef struct _KvpFrame KvpFrame;

typedef struct _KvpValue KvpValue;
 
typedef enum {
  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       
} KvpValueType;

#define kvp_frame KvpFrame

#define kvp_value KvpValue

#define kvp_value_t KvpValueType
  
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);

void kvp_frame_set_gint64(KvpFrame * frame, const char * path, gint64 ival);
void kvp_frame_set_double(KvpFrame * frame, const char * path, double dval);

#define kvp_frame_set_gnc_numeric kvp_frame_set_numeric

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

#define kvp_frame_set_str kvp_frame_set_string

void kvp_frame_set_string(KvpFrame * frame, const char * path, const char* str);
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);
void     kvp_frame_add_url_encoding (KvpFrame *frame, const char *enc);
void kvp_frame_add_gint64(KvpFrame * frame, const char * path, gint64 ival);
void kvp_frame_add_double(KvpFrame * frame, const char * path, double dval);
#define kvp_frame_add_gnc_numeric kvp_frame_add_numeric

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

#define kvp_frame_add_str kvp_frame_add_string

void kvp_frame_add_string(KvpFrame * frame, const char * path, const char* str);
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);

/* The kvp_frame_add_value() routine will  add a copy of the value
 *    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.  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).
 * 
 *    The *_nc() routine is analogous, except that it doesn't copy the
 *    value.
 */
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);


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

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

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);
gint        kvp_glist_compare(const GList * list1, const GList * list2);

GList     * kvp_glist_copy(const GList * list);

void        kvp_glist_delete(GList * list);
KvpValue   * kvp_value_new_gint64(gint64 value);
KvpValue   * kvp_value_new_double(double value);

#define kvp_value_new_gnc_numeric kvp_value_new_numeric
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);

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

gchar* kvp_value_to_bare_string(const KvpValue *val);

gchar* kvp_value_to_string(const KvpValue *val);

gboolean kvp_value_binary_append(KvpValue *v, void *data, guint64 size);

void kvp_frame_for_each_slot(KvpFrame *f,
                             void (*proc)(const char *key,
                                          KvpValue *value,
                                          gpointer data),
                             gpointer data);

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

#endif

---