Definition in file kvp-util-p.h.
#include "guid.h"
#include "kvp_frame.h"
Go to the source code of this file.
KvpBag Bags of GUID Pointers | |
KvpFrame * | gnc_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) |
KvpFrame * | gnc_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) |
|
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. Definition at line 74 of file kvp-util.c. 00076 { 00077 KvpFrame *cwd; 00078 va_list ap; 00079 va_start (ap, first_name); 00080 cwd = gnc_kvp_array_va (pwd, path, secs, first_name, ap); 00081 va_end (ap); 00082 return cwd; 00083 }
|
|
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. Definition at line 96 of file kvp-util.c. 00098 { 00099 KvpValue *arr; 00100 KvpValueType valtype; 00101 GList *node; 00102 00103 arr = kvp_frame_get_value (root, path); 00104 valtype = kvp_value_get_type (arr); 00105 if (KVP_TYPE_FRAME == valtype) 00106 { 00107 MATCH_GUID (arr); 00108 return NULL; 00109 } 00110 00111 /* Its gotta be a single isolated frame, or a list of them. */ 00112 if (KVP_TYPE_GLIST != valtype) return NULL; 00113 00114 for (node = kvp_value_get_glist(arr); node; node=node->next) 00115 { 00116 KvpValue *va = node->data; 00117 MATCH_GUID (va); 00118 } 00119 return NULL; 00120 }
|
|
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. Definition at line 190 of file kvp-util.c. 00192 { 00193 KvpFrame *fr; 00194 00195 fr = gnc_kvp_bag_get_first (kvp_from, frompath); 00196 while (fr) 00197 { 00198 gnc_kvp_bag_remove_frame (kvp_from, frompath, fr); 00199 kvp_frame_add_frame_nc (kvp_into, intopath, fr); 00200 fr = gnc_kvp_bag_get_first (kvp_from, frompath); 00201 } 00202 }
|
|
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. Definition at line 125 of file kvp-util.c. 00126 { 00127 KvpValue *arr; 00128 KvpValueType valtype; 00129 GList *node, *listhead; 00130 00131 arr = kvp_frame_get_value (root, path); 00132 valtype = kvp_value_get_type (arr); 00133 if (KVP_TYPE_FRAME == valtype) 00134 { 00135 if (fr == kvp_value_get_frame (arr)) 00136 { 00137 KvpValue *old_val = kvp_frame_replace_value_nc (root, path, NULL); 00138 kvp_value_replace_frame_nc (old_val, NULL); 00139 kvp_value_delete (old_val); 00140 } 00141 return; 00142 } 00143 00144 /* Its gotta be a single isolated frame, or a list of them. */ 00145 if (KVP_TYPE_GLIST != valtype) return; 00146 00147 listhead = kvp_value_get_glist(arr); 00148 for (node = listhead; node; node=node->next) 00149 { 00150 KvpValue *va = node->data; 00151 if (fr == kvp_value_get_frame (va)) 00152 { 00153 listhead = g_list_remove_link (listhead, node); 00154 g_list_free_1 (node); 00155 kvp_value_replace_glist_nc (arr, listhead); 00156 kvp_value_replace_frame_nc (va, NULL); 00157 kvp_value_delete (va); 00158 return; 00159 } 00160 } 00161 }
|