GnuCash  4.8a-132-gcdaeb421d+
Files | Macros | Typedefs

This file defines an API that adds types to the GncGUID's. More...

Files

file  qofid.h
 QOF entity type identification system.
 

Macros

#define QOF_ID_NONE   NULL
 
#define QOF_ID_NULL   "null"
 
#define QOF_ID_BOOK   "Book"
 
#define QOF_ID_SESSION   "Session"
 
#define QSTRCMP   g_strcmp0
 
#define QOF_CHECK_TYPE(obj, type)
 return TRUE if object is of the given type More...
 
#define QOF_CHECK_CAST(obj, e_type, c_type)
 cast object to the indicated type, print error message if its bad More...
 

Typedefs

typedef const gchar * QofIdType
 QofIdType declaration.
 
typedef const gchar * QofIdTypeConst
 QofIdTypeConst declaration.
 

Collections of Entities

QofCollection declaration

Parameters
e_typeQofIdType
is_dirtygboolean
hash_of_entitiesGHashTable
datagpointer, place where object class can hang arbitrary data
typedef void(* QofInstanceForeachCB) (QofInstance *, gpointer user_data)
 Callback type for qof_collection_foreach.
 
QofCollection * qof_collection_new (QofIdType type)
 create a new collection of entities of type
 
guint qof_collection_count (const QofCollection *col)
 return the number of entities in the collection. More...
 
void qof_collection_destroy (QofCollection *col)
 destroy the collection More...
 
QofIdType qof_collection_get_type (const QofCollection *)
 return the type that the collection stores
 
QofInstance * qof_collection_lookup_entity (const QofCollection *, const GncGUID *)
 Find the entity going only from its guid.
 
void qof_collection_foreach (const QofCollection *, QofInstanceForeachCB, gpointer user_data)
 Call the callback for each entity in the collection. More...
 
gpointer qof_collection_get_data (const QofCollection *col)
 Store and retrieve arbitrary object-defined data. More...
 
void qof_collection_set_data (QofCollection *col, gpointer user_data)
 
gboolean qof_collection_is_dirty (const QofCollection *col)
 Return value of 'dirty' flag on collection.
 

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, QofInstance *ent)
 Add an entity to a QOF_TYPE_COLLECT. More...
 
void qof_collection_remove_entity (QofInstance *ent)
 
gint qof_collection_compare (QofCollection *target, QofCollection *merge)
 Compare two secondary collections. More...
 
QofCollection * qof_collection_from_glist (QofIdType type, const GList *glist)
 Create a secondary collection from a GList. More...
 

Detailed Description

This file defines an API that adds types to the GncGUID's.

GncGUID's with types can be used to identify and reference typed entities.

The idea here is that a GncGUID 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 one 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.

GncGUID 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 GncGUID 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 QofInstance at %s:%d", __FILE__, __LINE__); \
(obj); \
}))
#define G_LOG_DOMAIN
Functions providing the SX List as a plugin page.

cast object to the indicated type, print error message if its bad

Definition at line 107 of file qofid.h.

◆ QOF_CHECK_TYPE

#define QOF_CHECK_TYPE (   obj,
  type 
)
Value:
(((obj) != NULL) && \
(0 == QSTRCMP((type),(((QofInstance *)(obj))->e_type))))

return TRUE if object is of the given type

Definition at line 102 of file qofid.h.

Function Documentation

◆ qof_collection_add_entity()

gboolean qof_collection_add_entity ( QofCollection *  coll,
QofInstance *  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_instance_insert_entity or ::qof_instance_remove_entity.

Definition at line 112 of file qofid.cpp.

113 {
114  QofInstance *e;
115  const GncGUID *guid;
116 
117  e = NULL;
118  if (!coll || !ent)
119  {
120  return FALSE;
121  }
122  guid = qof_instance_get_guid(ent);
123  if (guid_equal(guid, guid_null()))
124  {
125  return FALSE;
126  }
127  g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
128  e = qof_collection_lookup_entity(coll, guid);
129  if ( e != NULL )
130  {
131  return FALSE;
132  }
133  g_hash_table_insert (coll->hash_of_entities, (gpointer)guid, ent);
134  return TRUE;
135 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:215
gboolean guid_equal(const GncGUID *guid_1, const GncGUID *guid_2)
Given two GUIDs, return TRUE if they are non-NULL and equal.
Definition: guid.cpp:204
const GncGUID * guid_null(void)
Returns a GncGUID which is guaranteed to never reference any entity.
Definition: guid.cpp:131
The type used to store guids in C.
Definition: guid.h:75

◆ qof_collection_compare()

gint qof_collection_compare ( QofCollection *  target,
QofCollection *  merge 
)

Compare two secondary collections.

Performs a deep comparison of the collections. Each QofInstance in each collection is looked up in the other collection, via the GncGUID.

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 GncGUID 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 177 of file qofid.cpp.

178 {
179  gint value;
180 
181  value = 0;
182  if (!target && !merge)
183  {
184  return 0;
185  }
186  if (target == merge)
187  {
188  return 0;
189  }
190  if (!target && merge)
191  {
192  return -1;
193  }
194  if (target && !merge)
195  {
196  return 1;
197  }
198  if (target->e_type != merge->e_type)
199  {
200  return -1;
201  }
202  qof_collection_set_data(target, &value);
203  qof_collection_foreach(merge, collection_compare_cb, target);
204  value = *(gint*)qof_collection_get_data(target);
205  if (value == 0)
206  {
207  qof_collection_set_data(merge, &value);
208  qof_collection_foreach(target, collection_compare_cb, merge);
209  value = *(gint*)qof_collection_get_data(merge);
210  }
211  return value;
212 }
void qof_collection_foreach(const QofCollection *col, QofInstanceForeachCB cb_func, gpointer user_data)
Call the callback for each entity in the collection.
Definition: qofid.cpp:323
gpointer qof_collection_get_data(const QofCollection *col)
Store and retrieve arbitrary object-defined data.
Definition: qofid.cpp:291

◆ qof_collection_count()

guint qof_collection_count ( const QofCollection *  col)

return the number of entities in the collection.

Definition at line 246 of file qofid.cpp.

247 {
248  guint c;
249 
250  c = g_hash_table_size(col->hash_of_entities);
251  return c;
252 }

◆ qof_collection_destroy()

void qof_collection_destroy ( QofCollection *  col)

destroy the collection

XXX there should be a destroy notifier for this

Definition at line 62 of file qofid.cpp.

63 {
64  CACHE_REMOVE (col->e_type);
65  g_hash_table_destroy(col->hash_of_entities);
66  col->e_type = NULL;
67  col->hash_of_entities = NULL;
68  col->data = NULL;
69  g_free (col);
70 }

◆ qof_collection_foreach()

void qof_collection_foreach ( const QofCollection *  ,
QofInstanceForeachCB  ,
gpointer  user_data 
)

Call the callback for each entity in the collection.

Definition at line 323 of file qofid.cpp.

325 {
326  struct _qofid_iterate iter;
327  GList *entries;
328 
329  g_return_if_fail (col);
330  g_return_if_fail (cb_func);
331 
332  iter.fcn = cb_func;
333  iter.data = user_data;
334 
335  PINFO("Hash Table size of %s before is %d", col->e_type, g_hash_table_size(col->hash_of_entities));
336 
337  entries = g_hash_table_get_values (col->hash_of_entities);
338  g_list_foreach (entries, foreach_cb, &iter);
339  g_list_free (entries);
340 
341  PINFO("Hash Table size of %s after is %d", col->e_type, g_hash_table_size(col->hash_of_entities));
342 }
#define PINFO(format, args...)
Print an informational note.
Definition: qoflog.h:256

◆ qof_collection_from_glist()

QofCollection* qof_collection_from_glist ( QofIdType  type,
const 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 226 of file qofid.cpp.

227 {
228  QofCollection *coll;
229  QofInstance *ent;
230  const GList *list;
231 
232  coll = qof_collection_new(type);
233  for (list = glist; list != NULL; list = list->next)
234  {
235  ent = QOF_INSTANCE(list->data);
236  if (FALSE == qof_collection_add_entity(coll, ent))
237  {
239  return NULL;
240  }
241  }
242  return coll;
243 }
void qof_collection_destroy(QofCollection *col)
destroy the collection
Definition: qofid.cpp:62
gboolean qof_collection_add_entity(QofCollection *coll, QofInstance *ent)
Add an entity to a QOF_TYPE_COLLECT.
Definition: qofid.cpp:112
QofCollection * qof_collection_new(QofIdType type)
create a new collection of entities of type
Definition: qofid.cpp:51

◆ qof_collection_get_data()

gpointer qof_collection_get_data ( const QofCollection *  col)

Store and retrieve 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 291 of file qofid.cpp.

292 {
293  return col ? col->data : NULL;
294 }