The idea here is that a GUID can be used to uniquely identify some thing. By adding a type, one can then talk about the type of thing identified. By adding a collection, one can then work with a handle to a collection of things of a given type, each uniquely identified by a given ID. QOF Entities can be used independently of any other part of the system. In particular, Entities can be useful even if one is not using the Query ond Object parts of the QOF system.
Identifiers are globally-unique and permanent, i.e., once an entity has been assigned an identifier, it retains that same identifier for its lifetime. Identifiers can be encoded as hex strings.
GUID Identifiers are 'typed' with strings. The native ids used by QOF are defined below.
If you have a type name, and you want to have a way of finding a collection that is associated with that type, then you must use Books.
Entities can refer to other entities as well as to the basic QOF types, using the qofclass parameters.
Files | |
file | qofid.h |
QOF entity type identification system. | |
Data Structures | |
struct | QofEntity_s |
Collections of Entities | |
typedef void(* | QofEntityForeachCB )(QofEntity *, gpointer user_data) |
QofCollection * | qof_collection_new (QofIdType type) |
guint | qof_collection_count (QofCollection *col) |
void | qof_collection_destroy (QofCollection *col) |
QofIdType | qof_collection_get_type (QofCollection *) |
QofEntity * | qof_collection_lookup_entity (QofCollection *, const GUID *) |
void | qof_collection_foreach (QofCollection *, QofEntityForeachCB, gpointer user_data) |
gpointer | qof_collection_get_data (QofCollection *col) |
void | qof_collection_set_data (QofCollection *col, gpointer user_data) |
gboolean | qof_collection_is_dirty (QofCollection *col) |
QOF Entity Initialization & Shutdown | |
void | qof_entity_init (QofEntity *, QofIdType, QofCollection *) |
void | qof_entity_release (QofEntity *) |
QOF_TYPE_COLLECT: Linking one entity to many of one type | |
| |
gboolean | qof_collection_add_entity (QofCollection *coll, QofEntity *ent) |
Add an entity to a QOF_TYPE_COLLECT. | |
gboolean | qof_collection_merge (QofCollection *target, QofCollection *merge) |
Merge two QOF_TYPE_COLLECT of the same type. | |
gint | qof_collection_compare (QofCollection *target, QofCollection *merge) |
Compare two secondary collections. | |
QofCollection * | qof_collection_from_glist (QofIdType type, GList *glist) |
Create a secondary collection from a GList. | |
Defines | |
#define | QOF_ID_NONE NULL |
#define | QOF_ID_NULL "null" |
#define | QOF_ID_BOOK "Book" |
#define | QOF_ID_SESSION "Session" |
#define | QOF_ENTITY(object) ((QofEntity *)(object)) |
#define | QSTRCMP(da, db) |
#define | QOF_CHECK_TYPE(obj, type) |
#define | QOF_CHECK_CAST(obj, e_type, c_type) |
Typedefs | |
typedef const gchar * | QofIdType |
typedef const gchar * | QofIdTypeConst |
typedef const gchar * | QofLogModule |
typedef QofEntity_s | QofEntity |
typedef QofCollection_s | QofCollection |
Functions | |
const GUID * | qof_entity_get_guid (QofEntity *) |
|
Value: ( \ QOF_CHECK_TYPE((obj),(e_type)) ? \ (c_type *) (obj) : \ (c_type *) ({ \ g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \ "Error: Bad QofEntity at %s:%d", __FILE__, __LINE__); \ (obj); \ })) |
|
Value: return TRUE if object is of the given type |
|
simple,cheesy cast but holds water for now |
|
Value: ({ \ gint val = 0; \ if ((da) && (db)) { \ if ((da) != (db)) { \ val = strcmp ((da), (db)); \ } \ } else \ if ((!(da)) && (db)) { \ val = -1; \ } else \ if ((da) && (!(db))) { \ val = 1; \ } \ val; /* block assumes value of last statment */ \ }) |
|
QofCollection declaration
|
|
QofEntity declaration |
|
Callback type for qof_entity_foreach |
|
QofIdType declaration |
|
QofIdTypeConst declaration |
|
QofLogModule declaration |
|
Add an entity to a QOF_TYPE_COLLECT.
Definition at line 211 of file qofid.c. 00212 { 00213 QofEntity *e; 00214 00215 e = NULL; 00216 if (!coll || !ent) 00217 { 00218 return FALSE; 00219 } 00220 if (guid_equal (&ent->guid, guid_null ())) 00221 { 00222 return FALSE; 00223 } 00224 g_return_val_if_fail (coll->e_type == ent->e_type, FALSE); 00225 e = qof_collection_lookup_entity (coll, &ent->guid); 00226 if (e != NULL) 00227 { 00228 return FALSE; 00229 } 00230 g_hash_table_insert (coll->hash_of_entities, &ent->guid, ent); 00231 qof_collection_mark_dirty (coll); 00232 return TRUE; 00233 }
|
|
Compare two secondary collections. Performs a deep comparision of the collections. Each QofEntity in each collection is looked up in the other collection, via the GUID.
Definition at line 293 of file qofid.c. 00294 { 00295 gint value; 00296 00297 value = 0; 00298 if (!target && !merge) 00299 return 0; 00300 if (target == merge) 00301 return 0; 00302 if (!target && merge) 00303 return -1; 00304 if (target && !merge) 00305 return 1; 00306 if (target->e_type != merge->e_type) 00307 return -1; 00308 qof_collection_set_data (target, &value); 00309 qof_collection_foreach (merge, collection_compare_cb, target); 00310 value = *(gint *) qof_collection_get_data (target); 00311 if (value == 0) 00312 { 00313 qof_collection_set_data (merge, &value); 00314 qof_collection_foreach (target, collection_compare_cb, merge); 00315 value = *(gint *) qof_collection_get_data (merge); 00316 } 00317 return value; 00318 }
|
|
return the number of entities in the collection. Definition at line 351 of file qofid.c. 00352 { 00353 guint c; 00354 00355 c = g_hash_table_size (col->hash_of_entities); 00356 return c; 00357 }
|
|
XXX there should be a destroy notifier for this Definition at line 161 of file qofid.c. 00162 { 00163 CACHE_REMOVE (col->e_type); 00164 g_hash_table_destroy (col->hash_of_entities); 00165 col->e_type = NULL; 00166 col->hash_of_entities = NULL; 00167 col->data = NULL; 00168 g_free (col); 00169 }
|
|
Call the callback for each entity in the collection. Definition at line 420 of file qofid.c. 00422 { 00423 struct _iterate qiter; 00424 00425 g_return_if_fail (col); 00426 g_return_if_fail (cb_func); 00427 00428 qiter.fcn = cb_func; 00429 qiter.data = user_data; 00430 00431 g_hash_table_foreach (col->hash_of_entities, foreach_cb, &qiter); 00432 }
|
|
Create a secondary collection from a GList.
Definition at line 332 of file qofid.c. 00333 { 00334 QofCollection *coll; 00335 QofEntity *ent; 00336 GList *list; 00337 00338 coll = qof_collection_new (type); 00339 for (list = glist; list != NULL; list = list->next) 00340 { 00341 ent = (QofEntity *) list->data; 00342 if (FALSE == qof_collection_add_entity (coll, ent)) 00343 { 00344 return NULL; 00345 } 00346 } 00347 return coll; 00348 }
|
|
Store arbitrary object-defined data XXX We need to add a callback for when the collection is being destroyed, so that the user has a chance to clean up anything that was put in the 'data' member here. Definition at line 388 of file qofid.c.
|
|
return the type that the collection stores Definition at line 175 of file qofid.c.
|
|
Return value of 'dirty' flag on collection Definition at line 362 of file qofid.c.
|
|
Find the entity going only from its guid Definition at line 321 of file qofid.c. 00322 { 00323 QofEntity *ent; 00324 g_return_val_if_fail (col, NULL); 00325 if (guid == NULL) 00326 return NULL; 00327 ent = g_hash_table_lookup (col->hash_of_entities, guid); 00328 return ent; 00329 }
|
|
Merge two QOF_TYPE_COLLECT of the same type.
Definition at line 245 of file qofid.c. 00246 { 00247 if (!target || !merge) 00248 { 00249 return FALSE; 00250 } 00251 g_return_val_if_fail (target->e_type == merge->e_type, FALSE); 00252 qof_collection_foreach (merge, collection_merge_cb, target); 00253 return TRUE; 00254 }
|
|
create a new collection of entities of type Definition at line 150 of file qofid.c. 00151 { 00152 QofCollection *col; 00153 col = g_new0 (QofCollection, 1); 00154 col->e_type = CACHE_INSERT (type); 00155 col->hash_of_entities = g_hash_table_new (id_hash, id_compare); 00156 col->data = NULL; 00157 return col; 00158 }
|
|
Retrieve arbitrary object-defined data Definition at line 394 of file qofid.c.
|
|
Return the GUID of this entity Definition at line 105 of file qofid.c. 00106 { 00107 if (!ent) 00108 return guid_null (); 00109 return &ent->guid; 00110 }
|
|
Initialise the memory associated with an entity Definition at line 49 of file qofid.c. 00050 { 00051 g_return_if_fail (NULL != tab); 00052 00053 /* XXX We passed redundant info to this routine ... but I think that's 00054 * OK, it might eliminate programming errors. */ 00055 if (safe_strcmp (tab->e_type, type)) 00056 { 00057 PERR ("attempt to insert \"%s\" into \"%s\"", type, tab->e_type); 00058 return; 00059 } 00060 ent->e_type = CACHE_INSERT (type); 00061 00062 do 00063 { 00064 guid_new (&ent->guid); 00065 00066 if (NULL == qof_collection_lookup_entity (tab, &ent->guid)) 00067 break; 00068 00069 PWARN ("duplicate id created, trying again"); 00070 } 00071 while (1); 00072 00073 ent->collection = tab; 00074 00075 qof_collection_insert_entity (tab, ent); 00076 }
|
|
Release the data associated with this entity. Dont actually free the memory associated with the instance. Definition at line 79 of file qofid.c. 00080 { 00081 if (!ent->collection) 00082 return; 00083 qof_collection_remove_entity (ent); 00084 CACHE_REMOVE (ent->e_type); 00085 ent->e_type = NULL; 00086 }
|