|
file | qofid.h |
| QOF entity type identification system.
|
|
This file defines an API that adds types to the GUID's. GUID's with types can be used to identify and reference typed entities.
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.
- An id with type QOF_ID_NONE does not refer to any entity.
- An id with type QOF_ID_NULL does not refer to any entity, and will never refer to any entity. =# An identifier with any other type may refer to an actual entity, but that is not guaranteed as that entity does not have to exist within the current book. (See PARTIAL_QOFBOOK). Also, creating a new entity from a data source involves creating a temporary GUID and then setting the value from the data source. If an id does refer to an entity, the type of the entity will match the type of the identifier.
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.
#define QOF_CHECK_CAST |
( |
|
obj, |
|
|
|
e_type, |
|
|
|
c_type |
|
) |
| |
Value: (c_type *) (obj) : \
(c_type *) ({ \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \
"Error: Bad QofEntity at %s:%d", __FILE__, __LINE__); \
(obj); \
}))
#define QOF_CHECK_TYPE(obj, type)
cast object to the indicated type, print error message if its bad
Definition at line 119 of file qofid.h.
#define QOF_CHECK_TYPE |
( |
|
obj, |
|
|
|
type |
|
) |
| |
Value:return TRUE if object is of the given type
Definition at line 114 of file qofid.h.
#define QOF_ENTITY |
( |
|
object | ) |
((QofEntity *)(object)) |
simple,cheesy cast but holds water for now
Definition at line 94 of file qofid.h.
#define QSTRCMP |
( |
|
da, |
|
|
|
db |
|
) |
| |
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; \
})
Inline string comparision; compiler will optimize away most of this
Definition at line 97 of file qofid.h.
QofCollection declaration
- Parameters
-
e_type | QofIdType |
is_dirty | gboolean |
hash_of_entities | GHashTable |
data | gpointer, place where object class can hang arbitrary data |
Definition at line 138 of file qofid.h.
QofEntity declaration
Definition at line 129 of file qofid.h.
typedef void(* QofEntityForeachCB) (QofEntity *, gpointer user_data) |
Callback type for qof_entity_foreach
Definition at line 187 of file qofid.h.
QofIdType declaration
Definition at line 81 of file qofid.h.
QofIdTypeConst declaration
Definition at line 83 of file qofid.h.
QofLogModule declaration
Definition at line 85 of file qofid.h.
Add an entity to a QOF_TYPE_COLLECT.
- Note
- These are NOT the same as the main collections in the book.
Entities can be freely added and merged across these secondary collections, they will not be removed from the original collection as they would by using ::qof_entity_insert_entity or ::qof_entity_remove_entity.
Definition at line 182 of file qofid.c.
195 g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
201 g_hash_table_insert (coll->hash_of_entities, &ent->guid, ent);
202 qof_collection_mark_dirty (coll);
gboolean guid_equal(const GUID *guid_1, const GUID *guid_2)
const GUID * guid_null(void)
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
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.
- Returns
- 0 if the collections are identical or both are NULL otherwise -1 if target is NULL or either collection contains an entity with an invalid GUID or if the types of the two collections do not match, or +1 if merge is NULL or if any entity exists in one collection but not in the other.
Definition at line 264 of file qofid.c.
269 if (!target && !merge)
273 if (!target && merge)
275 if (target && !merge)
277 if (target->e_type != merge->e_type)
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
void qof_collection_set_data(QofCollection *col, gpointer user_data)
gpointer qof_collection_get_data(QofCollection *col)
return the number of entities in the collection.
Definition at line 322 of file qofid.c.
326 c = g_hash_table_size (col->hash_of_entities);
destroy the collection
XXX there should be a destroy notifier for this
Definition at line 132 of file qofid.c.
134 CACHE_REMOVE (col->e_type);
135 g_hash_table_destroy (col->hash_of_entities);
137 col->hash_of_entities = NULL;
Call the callback for each entity in the collection.
Definition at line 392 of file qofid.c.
395 struct _iterate qiter;
397 g_return_if_fail (col);
398 g_return_if_fail (cb_func);
401 qiter.data = user_data;
403 g_hash_table_foreach (col->hash_of_entities, foreach_cb, &qiter);
Create a secondary collection from a GList.
- Parameters
-
type | The QofIdType of the QofCollection and of all entities in the GList. |
glist | GList of entities of the same QofIdType. |
- Returns
- NULL if any of the entities fail to match the QofCollection type, else a pointer to the collection on success.
Definition at line 303 of file qofid.c.
310 for (list = glist; list != NULL; list = list->next)
gboolean qof_collection_add_entity(QofCollection *coll, QofEntity *ent)
Add an entity to a QOF_TYPE_COLLECT.
struct QofCollection_s QofCollection
QofCollection * qof_collection_new(QofIdType type)
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 359 of file qofid.c.
361 return col ? col->data : NULL;
return the type that the collection stores
Definition at line 146 of file qofid.c.
Return value of 'dirty' flag on collection
Definition at line 333 of file qofid.c.
335 return col ? col->is_dirty : FALSE;
Find the entity going only from its guid
Definition at line 292 of file qofid.c.
295 g_return_val_if_fail (col, NULL);
298 ent = g_hash_table_lookup (col->hash_of_entities, guid);
Merge two QOF_TYPE_COLLECT of the same type.
- Note
- NOT the same as the main collections in the book.
QOF_TYPE_COLLECT uses a secondary collection, independent of those in the book. Entities will not be removed from the original collection as when using ::qof_entity_insert_entity or ::qof_entity_remove_entity.
Definition at line 216 of file qofid.c.
218 if (!target || !merge)
222 g_return_val_if_fail (target->e_type == merge->e_type, FALSE);
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
create a new collection of entities of type
Definition at line 121 of file qofid.c.
125 col->e_type = CACHE_INSERT (type);
struct QofCollection_s QofCollection
guint guid_hash_to_guint(gconstpointer ptr)
void qof_collection_set_data |
( |
QofCollection * |
col, |
|
|
gpointer |
user_data |
|
) |
| |
Retrieve arbitrary object-defined data
Definition at line 365 of file qofid.c.
369 col->data = user_data;
Return the GUID of this entity
Definition at line 105 of file qofid.c.
const GUID * guid_null(void)
Initialise the memory associated with an entity
Definition at line 49 of file qofid.c.
51 g_return_if_fail (NULL != tab);
57 PERR (
"attempt to insert \"%s\" into \"%s\"", type, tab->e_type);
60 ent->e_type = CACHE_INSERT (type);
69 PWARN (
"duplicate id created, trying again");
73 ent->collection = tab;
#define PERR(format, args...)
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
void guid_new(GUID *guid)
#define PWARN(format, args...)
gint safe_strcmp(const gchar *da, const gchar *db)
void qof_collection_insert_entity(QofCollection *col, QofEntity *ent)
Release the data associated with this entity. Dont actually free the memory associated with the instance.
Definition at line 79 of file qofid.c.
83 qof_collection_remove_entity (ent);
84 CACHE_REMOVE (ent->e_type);