QOF: Entity

QOF 0.7.5

Files | Data Structures | Macros | Typedefs | Functions
Entity
Query Object Framework » Class: Getting and setting entity values.

## 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 GUID * | qof_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)
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_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...
QofCollection * | qof_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

## ◆ QOF_CHECK_CAST

#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

Definition at line 119 of file qofid.h.

## ◆ QOF_CHECK_TYPE

#define QOF_CHECK_TYPE | ( |  | obj,
|  |  | type
| ) |  |

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

## ◆ QOF_ENTITY

#define QOF_ENTITY | ( |  | object | ) | ((QofEntity *)(object))

simple,cheesy cast but holds water for now

Definition at line 94 of file qofid.h.

## ◆ QSTRCMP

#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

## ◆ QofCollection

typedef struct QofCollection_s QofCollection

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

typedef struct QofEntity_s QofEntity

QofEntity declaration

Definition at line 129 of file qofid.h.

## ◆ QofEntityForeachCB

typedef void(* QofEntityForeachCB) (QofEntity *, gpointer user_data)

Callback type for qof_entity_foreach

Definition at line 187 of file qofid.h.

## ◆ QofIdType

typedef const gchar* QofIdType

QofIdType declaration

Definition at line 81 of file qofid.h.

## ◆ QofIdTypeConst

typedef const gchar* QofIdTypeConst

QofIdTypeConst declaration

Definition at line 83 of file qofid.h.

## ◆ QofLogModule

typedef const gchar* QofLogModule

QofLogModule declaration

Definition at line 85 of file qofid.h.

## Function Documentation

## ◆ qof_collection_add_entity()

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 211 of file qofid.c.

212 {
213 QofEntity *e;
214
215 e = NULL;
216 if (!coll || !ent)
217 {
218 return FALSE;
219 }
220 if (guid_equal (&ent->guid, guid_null ()))
221 {
222 return FALSE;
223 }
224 g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
225 e = qof_collection_lookup_entity (coll, &ent->guid);
226 if (e != NULL)
227 {
228 return FALSE;
229 }
230 g_hash_table_insert (coll->hash_of_entities, &ent->guid, ent);
231 qof_collection_mark_dirty (coll);
232 return TRUE;
233 }
guid_equal
gboolean guid_equal(const GUID *guid_1, const GUID *guid_2)
Definition: guid.c:652
guid_null
const GUID * guid_null(void)
Definition: guid.c:119
QofEntity_s
Definition: qofid.h:147
qof_collection_lookup_entity
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
Definition: qofid.c:321

## ◆ qof_collection_compare()

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 293 of file qofid.c.

294 {
295 gint value;
296
297 value = 0;
298 if (!target && !merge)
299 return 0;
300 if (target == merge)
301 return 0;
302 if (!target && merge)
303 return -1;
304 if (target && !merge)
305 return 1;
306 if (target->e_type != merge->e_type)
307 return -1;
308 qof_collection_set_data (target, &value);
309 qof_collection_foreach (merge, collection_compare_cb, target);
310 value = *(gint *) qof_collection_get_data (target);
311 if (value == 0)
312 {
313 qof_collection_set_data (merge, &value);
314 qof_collection_foreach (target, collection_compare_cb, merge);
315 value = *(gint *) qof_collection_get_data (merge);
316 }
317 return value;
318 }
qof_collection_foreach
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
Definition: qofid.c:421
qof_collection_set_data
void qof_collection_set_data(QofCollection *col, gpointer user_data)
Definition: qofid.c:394
qof_collection_get_data
gpointer qof_collection_get_data(QofCollection *col)
Definition: qofid.c:388

## ◆ qof_collection_count()

guint qof_collection_count | ( | QofCollection * | col | ) |

return the number of entities in the collection.

Definition at line 351 of file qofid.c.

352 {
353 guint c;
354
355 c = g_hash_table_size (col->hash_of_entities);
356 return c;
357 }

## ◆ qof_collection_destroy()

void qof_collection_destroy | ( | QofCollection * | col | ) |

destroy the collection

XXX there should be a destroy notifier for this

Definition at line 161 of file qofid.c.

162 {
163 CACHE_REMOVE (col->e_type);
164 g_hash_table_destroy (col->hash_of_entities);
165 col->e_type = NULL;
166 col->hash_of_entities = NULL;
167 col->data = NULL;
168 g_free (col);
169 }

## ◆ qof_collection_foreach()

void qof_collection_foreach | ( | QofCollection * | ,
|  | QofEntityForeachCB | ,
|  | gpointer | user_data
| ) |  |

Call the callback for each entity in the collection.

Definition at line 421 of file qofid.c.

423 {
424 struct _iterate qiter;
425
426 g_return_if_fail (col);
427 g_return_if_fail (cb_func);
428
429 qiter.fcn = cb_func;
430 qiter.data = user_data;
431
432 g_hash_table_foreach (col->hash_of_entities, foreach_cb, &qiter);
433 }

## ◆ qof_collection_from_glist()

QofCollection* qof_collection_from_glist | ( | QofIdType | type,
|  | GList * | glist
| ) |  |

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 332 of file qofid.c.

333 {
334 QofCollection *coll;
335 QofEntity *ent;
336 GList *list;
337
338 coll = qof_collection_new (type);
339 for (list = glist; list != NULL; list = list->next)
340 {
341 ent = (QofEntity *) list->data;
342 if (FALSE == qof_collection_add_entity (coll, ent))
343 {
344 return NULL;
345 }
346 }
347 return coll;
348 }
qof_collection_add_entity
gboolean qof_collection_add_entity(QofCollection *coll, QofEntity *ent)
Add an entity to a QOF_TYPE_COLLECT.
Definition: qofid.c:211
QofEntity_s
Definition: qofid.h:147
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138
qof_collection_new
QofCollection * qof_collection_new(QofIdType type)
Definition: qofid.c:150

## ◆ qof_collection_get_data()

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 388 of file qofid.c.

389 {
390 return col ? col->data : NULL;
391 }

## ◆ qof_collection_get_type()

QofIdType qof_collection_get_type | ( | QofCollection * |  | ) |

return the type that the collection stores

Definition at line 175 of file qofid.c.

176 {
177 return col->e_type;
178 }

## ◆ qof_collection_is_dirty()

gboolean qof_collection_is_dirty | ( | QofCollection * | col | ) |

Return value of 'dirty' flag on collection

Definition at line 362 of file qofid.c.

363 {
364 return col ? col->is_dirty : FALSE;
365 }

## ◆ qof_collection_lookup_entity()

QofEntity* qof_collection_lookup_entity | ( | QofCollection * | ,
|  | const GUID * |
| ) |  |

Find the entity going only from its guid

Definition at line 321 of file qofid.c.

322 {
323 QofEntity *ent;
324 g_return_val_if_fail (col, NULL);
325 if (guid == NULL)
326 return NULL;
327 ent = g_hash_table_lookup (col->hash_of_entities, guid);
328 return ent;
329 }
QofEntity_s
Definition: qofid.h:147

## ◆ qof_collection_merge()

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 245 of file qofid.c.

246 {
247 if (!target || !merge)
248 {
249 return FALSE;
250 }
251 g_return_val_if_fail (target->e_type == merge->e_type, FALSE);
252 qof_collection_foreach (merge, collection_merge_cb, target);
253 return TRUE;
254 }
qof_collection_foreach
void qof_collection_foreach(QofCollection *col, QofEntityForeachCB cb_func, gpointer user_data)
Definition: qofid.c:421

## ◆ qof_collection_new()

QofCollection* qof_collection_new | ( | QofIdType | type | ) |

create a new collection of entities of type

Definition at line 150 of file qofid.c.

151 {
152 QofCollection *col;
153 col = g_new0 (QofCollection, 1);
154 col->e_type = CACHE_INSERT (type);
155 col->hash_of_entities = g_hash_table_new (id_hash, id_compare);
156 col->data = NULL;
157 return col;
158 }
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138

## ◆ qof_collection_set_data()

void qof_collection_set_data | ( | QofCollection * | col,
|  | gpointer | user_data
| ) |  |

Retrieve arbitrary object-defined data

Definition at line 394 of file qofid.c.

395 {
396 if (col)
397 {
398 col->data = user_data;
399 }
400 }

## ◆ qof_entity_get_guid()

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 }
guid_null
const GUID * guid_null(void)
Definition: guid.c:119

## ◆ qof_entity_init()

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
75 qof_collection_insert_entity (tab, ent);
76 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
qof_collection_lookup_entity
QofEntity * qof_collection_lookup_entity(QofCollection *col, const GUID *guid)
Definition: qofid.c:321
guid_new
void guid_new(GUID *guid)
Definition: guid.c:487
PWARN
#define PWARN(format, args...)
Definition: qoflog.h:191
safe_strcmp
gint safe_strcmp(const gchar *da, const gchar *db)
Definition: qofutil.c:72
qof_collection_insert_entity
void qof_collection_insert_entity(QofCollection *col, QofEntity *ent)
Definition: qofid.c:197

## ◆ qof_entity_release()

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 }