Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

KVP_Private
[KVP: Key-Value Pairs]


Detailed Description

Private interfaces, not meant to be used by applications.


KvpBag Bags of GUID Pointers

KvpFramegnc_kvp_bag_add (KvpFrame *kvp_root, const char *path, time_t secs, const char *first_name,...)
void gnc_kvp_bag_merge (KvpFrame *kvp_into, const char *intopath, KvpFrame *kvp_from, const char *frompath)
KvpFramegnc_kvp_bag_find_by_guid (KvpFrame *root, const char *path, const char *guid_name, GUID *desired_guid)
void gnc_kvp_bag_remove_frame (KvpFrame *root, const char *path, KvpFrame *fr)


Function Documentation

KvpFrame* gnc_kvp_bag_add KvpFrame kvp_root,
const char *  path,
time_t  secs,
const char *  first_name,
  ...
 

The gnc_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:

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

KvpFrame* gnc_kvp_bag_find_by_guid KvpFrame root,
const char *  path,
const char *  guid_name,
GUID desired_guid
 

The gnc_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.

void gnc_kvp_bag_merge KvpFrame kvp_into,
const char *  intopath,
KvpFrame kvp_from,
const char *  frompath
 

The gnc_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.

void gnc_kvp_bag_remove_frame KvpFrame root,
const char *  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.


Generated on Sun May 23 15:41:47 2004 for QOF by doxygen 1.3.6-20040222