QOF  0.8.7
Files | Data Structures | Macros | Typedefs | Functions

Files

file  qofid.h
 QOF entity type identification system.
 

Data Structures

struct  QofEntity_s
 

Macros

#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 struct QofEntity_s QofEntity
 
typedef struct QofCollection_s QofCollection
 

Functions

const GUIDqof_entity_get_guid (QofEntity *)
 

QOF Entity Initialization & Shutdown

void qof_entity_init (QofEntity *, QofIdType, QofCollection *)
 
void qof_entity_release (QofEntity *)
 

Collections of Entities

typedef void(* QofEntityForeachCB) (QofEntity *, gpointer user_data)
 
QofCollectionqof_collection_new (QofIdType type)
 
guint qof_collection_count (QofCollection *col)
 
void qof_collection_destroy (QofCollection *col)
 
QofIdType qof_collection_get_type (QofCollection *)
 
QofEntityqof_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_TYPE_COLLECT: Linking one entity to many of one type

Note
These are NOT the same as the main collections in the book.

QOF_TYPE_COLLECT is a secondary collection, used to select entities of one object type as references of another entity.

See also
QOF_TYPE_CHOICE.
gboolean qof_collection_add_entity (QofCollection *coll, QofEntity *ent)
 Add an entity to a QOF_TYPE_COLLECT. More...
 
gboolean qof_collection_merge (QofCollection *target, QofCollection *merge)
 Merge two QOF_TYPE_COLLECT of the same type. More...
 
gint qof_collection_compare (QofCollection *target, QofCollection *merge)
 Compare two secondary collections. More...
 
QofCollectionqof_collection_from_glist (QofIdType type, GList *glist)
 Create a secondary collection from a GList. More...
 

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.

  1. An id with type QOF_ID_NONE does not refer to any entity.
  2. 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.

Macro Definition 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); \
}))
#define QOF_CHECK_TYPE(obj, type)
Definition: qofid.h:114

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:
(((obj) != NULL) && \
(0 == QSTRCMP((type),(((QofEntity *)(obj))->e_type))))
#define QSTRCMP(da, db)
Definition: qofid.h:97

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; /* block assumes value of last statment */ \
})

Inline string comparision; compiler will optimize away most of this

Definition at line 97 of file qofid.h.

Typedef Documentation

typedef struct QofCollection_s QofCollection

QofCollection declaration

Parameters
e_typeQofIdType
is_dirtygboolean
hash_of_entitiesGHashTable
datagpointer, place where object class can hang arbitrary data

Definition at line 138 of file qofid.h.

typedef struct QofEntity_s QofEntity

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.

typedef const gchar* QofIdType

QofIdType declaration

Definition at line 81 of file qofid.h.

typedef const gchar* QofIdTypeConst

QofIdTypeConst declaration

Definition at line 83 of file qofid.h.

typedef const gchar* QofLogModule

QofLogModule declaration

Definition at line 85 of file qofid.h.

Function Documentation

gboolean qof_collection_add_entity ( QofCollection coll,
QofEntity ent 
)

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.

183 {
184  QofEntity *e;
185 
186  e = NULL;
187  if (!coll || !ent)
188  {
189  return FALSE;
190  }
191  if (guid_equal (&ent->guid, guid_null ()))
192  {
193  return FALSE;
194  }
195  g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
196  e = qof_collection_lookup_entity (coll, &ent->guid);
197  if (e != NULL)
198  {
199  return FALSE;
200  }
201  g_hash_table_insert (coll->hash_of_entities, &ent->guid, ent);
202  qof_collection_mark_dirty (coll);
203  return TRUE;
204 }
gboolean guid_equal(const GUID *guid_1, const GUID *guid_2)
Definition: guid.c:620
const GUID * guid_null(void)
Definition: guid.c:79
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
Definition: qofid.c:292
gint qof_collection_compare ( QofCollection target,
QofCollection merge 
)

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.

265 {
266  gint value;
267 
268  value = 0;
269  if (!target && !merge)
270  return 0;
271  if (target == merge)
272  return 0;
273  if (!target && merge)
274  return -1;
275  if (target && !merge)
276  return 1;
277  if (target->e_type != merge->e_type)
278  return -1;
279  qof_collection_set_data (target, &value);
280  qof_collection_foreach (merge, collection_compare_cb, target);
281  value = *(gint *) qof_collection_get_data (target);
282  if (value == 0)
283  {
284  qof_collection_set_data (merge, &value);
285  qof_collection_foreach (target, collection_compare_cb, merge);
286  value = *(gint *) qof_collection_get_data (merge);
287  }
288  return value;
289 }
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
Definition: qofid.c:392
void qof_collection_set_data(QofCollection *col, gpointer user_data)
Definition: qofid.c:365
gpointer qof_collection_get_data(QofCollection *col)
Definition: qofid.c:359
guint qof_collection_count ( QofCollection col)

return the number of entities in the collection.

Definition at line 322 of file qofid.c.

323 {
324  guint c;
325 
326  c = g_hash_table_size (col->hash_of_entities);
327  return c;
328 }
void qof_collection_destroy ( QofCollection col)

destroy the collection

XXX there should be a destroy notifier for this

Definition at line 132 of file qofid.c.

133 {
134  CACHE_REMOVE (col->e_type);
135  g_hash_table_destroy (col->hash_of_entities);
136  col->e_type = NULL;
137  col->hash_of_entities = NULL;
138  col->data = NULL;
139  g_free (col);
140 }
void qof_collection_foreach ( QofCollection ,
QofEntityForeachCB  ,
gpointer  user_data 
)

Call the callback for each entity in the collection.

Definition at line 392 of file qofid.c.

394 {
395  struct _iterate qiter;
396 
397  g_return_if_fail (col);
398  g_return_if_fail (cb_func);
399 
400  qiter.fcn = cb_func;
401  qiter.data = user_data;
402 
403  g_hash_table_foreach (col->hash_of_entities, foreach_cb, &qiter);
404 }
QofCollection* qof_collection_from_glist ( QofIdType  type,
GList *  glist 
)

Create a secondary collection from a GList.

Parameters
typeThe QofIdType of the QofCollection and of all entities in the GList.
glistGList 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.

304 {
305  QofCollection *coll;
306  QofEntity *ent;
307  GList *list;
308 
309  coll = qof_collection_new (type);
310  for (list = glist; list != NULL; list = list->next)
311  {
312  ent = (QofEntity *) list->data;
313  if (FALSE == qof_collection_add_entity (coll, ent))
314  {
315  return NULL;
316  }
317  }
318  return coll;
319 }
gboolean qof_collection_add_entity(QofCollection *coll, QofEntity *ent)
Add an entity to a QOF_TYPE_COLLECT.
Definition: qofid.c:182
struct QofCollection_s QofCollection
Definition: qofid.h:138
QofCollection * qof_collection_new(QofIdType type)
Definition: qofid.c:121
gpointer qof_collection_get_data ( QofCollection col)

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.

360 {
361  return col ? col->data : NULL;
362 }
QofIdType qof_collection_get_type ( QofCollection )

return the type that the collection stores

Definition at line 146 of file qofid.c.

147 {
148  return col->e_type;
149 }
gboolean qof_collection_is_dirty ( QofCollection col)

Return value of 'dirty' flag on collection

Definition at line 333 of file qofid.c.

334 {
335  return col ? col->is_dirty : FALSE;
336 }
QofEntity* qof_collection_lookup_entity ( QofCollection ,
const GUID  
)

Find the entity going only from its guid

Definition at line 292 of file qofid.c.

293 {
294  QofEntity *ent;
295  g_return_val_if_fail (col, NULL);
296  if (guid == NULL)
297  return NULL;
298  ent = g_hash_table_lookup (col->hash_of_entities, guid);
299  return ent;
300 }
gboolean qof_collection_merge ( QofCollection target,
QofCollection merge 
)

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.

217 {
218  if (!target || !merge)
219  {
220  return FALSE;
221  }
222  g_return_val_if_fail (target->e_type == merge->e_type, FALSE);
223  qof_collection_foreach (merge, collection_merge_cb, target);
224  return TRUE;
225 }
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
Definition: qofid.c:392
QofCollection* qof_collection_new ( QofIdType  type)

create a new collection of entities of type

Definition at line 121 of file qofid.c.

122 {
123  QofCollection *col;
124  col = g_new0 (QofCollection, 1);
125  col->e_type = CACHE_INSERT (type);
126  col->hash_of_entities = g_hash_table_new (guid_hash_to_guint, id_compare);
127  col->data = NULL;
128  return col;
129 }
struct QofCollection_s QofCollection
Definition: qofid.h:138
guint guid_hash_to_guint(gconstpointer ptr)
Definition: guid.c:645
void qof_collection_set_data ( QofCollection col,
gpointer  user_data 
)

Retrieve arbitrary object-defined data

Definition at line 365 of file qofid.c.

366 {
367  if (col)
368  {
369  col->data = user_data;
370  }
371 }
const GUID* qof_entity_get_guid ( QofEntity )

Return the GUID of this entity

Definition at line 105 of file qofid.c.

106 {
107  if (!ent)
108  return guid_null ();
109  return &ent->guid;
110 }
const GUID * guid_null(void)
Definition: guid.c:79
void qof_entity_init ( QofEntity ,
QofIdType  ,
QofCollection  
)

Initialise the memory associated with an entity

Definition at line 49 of file qofid.c.

50 {
51  g_return_if_fail (NULL != tab);
52 
53  /* XXX We passed redundant info to this routine ... but I think that's
54  * OK, it might eliminate programming errors. */
55  if (safe_strcmp (tab->e_type, type))
56  {
57  PERR ("attempt to insert \"%s\" into \"%s\"", type, tab->e_type);
58  return;
59  }
60  ent->e_type = CACHE_INSERT (type);
61 
62  do
63  {
64  guid_new (&ent->guid);
65 
66  if (NULL == qof_collection_lookup_entity (tab, &ent->guid))
67  break;
68 
69  PWARN ("duplicate id created, trying again");
70  }
71  while (1);
72 
73  ent->collection = tab;
74 
76 }
#define PERR(format, args...)
Definition: qoflog.h:183
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
Definition: qofid.c:292
void guid_new(GUID *guid)
Definition: guid.c:444
#define PWARN(format, args...)
Definition: qoflog.h:191
gint safe_strcmp(const gchar *da, const gchar *db)
Definition: qofutil.c:75
void qof_collection_insert_entity(QofCollection *col, QofEntity *ent)
Definition: qofid.c:168
void qof_entity_release ( QofEntity )

Release the data associated with this entity. Dont actually free the memory associated with the instance.

Definition at line 79 of file qofid.c.

80 {
81  if (!ent->collection)
82  return;
83  qof_collection_remove_entity (ent);
84  CACHE_REMOVE (ent->e_type);
85  ent->e_type = NULL;
86 }