Detailed Description
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, although that may change (???). 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 (??? Huh?). 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.
|
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) |
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 *) |
Defines |
#define | QOF_ID_NONE NULL |
#define | QOF_ID_NULL "null" |
#define | QOF_ID_BOOK "Book" |
#define | QOF_ID_FREQSPEC "FreqSpec" |
#define | QOF_ID_SESSION "Session" |
#define | QOF_ENTITY(object) ((QofEntity *)(object)) |
#define | QSTRCMP(da, db) |
#define | QOF_CHECK_TYPE(obj, type) (0 == QSTRCMP((type),(((QofEntity *)(obj))->e_type))) |
#define | QOF_CHECK_CAST(obj, e_type, c_type) |
Typedefs |
typedef const char * | QofIdType |
typedef const char * | QofIdTypeConst |
typedef QofEntity_s | QofEntity |
typedef QofCollection_s | QofCollection |
Functions |
const GUID * | qof_entity_get_guid (QofEntity *) |
Define Documentation
#define QOF_CHECK_CAST |
( |
obj, |
|
|
e_type, |
|
|
c_type |
|
) |
|
|
|
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); \
}))
cast object to the indicated type, print error message if its bad |
#define QOF_CHECK_TYPE |
( |
obj, |
|
|
type |
|
) |
(0 == QSTRCMP((type),(((QofEntity *)(obj))->e_type)))
|
|
|
return TRUE if object is of the given type |
#define QOF_ENTITY |
( |
object |
|
) |
((QofEntity *)(object))
|
|
|
simple,cheesy cast but holds water for now |
#define QSTRCMP |
( |
da, |
|
|
db |
|
) |
|
|
|
Value: ({ \
int 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 |
Typedef Documentation
|
Callback type for qof_entity_foreach |
Function Documentation
void qof_collection_destroy |
( |
QofCollection * |
col |
) |
|
|
|
Call the callback for each entity in the collection. |
gpointer qof_collection_get_data |
( |
QofCollection * |
col |
) |
|
|
|
Store and retreive 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. |
QofIdType qof_collection_get_type |
( |
QofCollection * |
|
) |
|
|
|
return the type that the collection stores |
gboolean qof_collection_is_dirty |
( |
QofCollection * |
col |
) |
|
|
|
Return value of 'dirty' flag on collection |
QofEntity* qof_collection_lookup_entity |
( |
QofCollection * |
, |
|
|
const GUID * |
|
|
) |
|
|
|
Find the entity going only from its guid |
const GUID* qof_entity_get_guid |
( |
QofEntity * |
|
) |
|
|
|
Return the GUID of this entity |
void qof_entity_init |
( |
QofEntity * |
, |
|
|
QofIdType |
, |
|
|
QofCollection * |
|
|
) |
|
|
|
Initialise the memory associated with an entity |
void qof_entity_release |
( |
QofEntity * |
|
) |
|
|
|
Release the data associated with this entity. Dont actually free the memory associated with the instance. |
Generated on Sun May 23 15:41:48 2004 for QOF by
1.3.6-20040222