qofid.h File Reference


Detailed Description

QOF entity type identification system.

Author:
Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu>

Copyright (C) 2003 Linas Vepstas <linas@linas.org>

Definition in file qofid.h.

#include <string.h>
#include "guid.h"

Go to the source code of this file.

Data Structures

struct  QofEntity_s

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 Entity Initialization & Shutdown

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

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.
gboolean qof_collection_merge (QofCollection *target, QofCollection *merge)
 Merge two QOF_TYPE_COLLECT of the same type.
gint qof_collection_compare (QofCollection *target, QofCollection *merge)
 Compare two secondary collections.
QofCollectionqof_collection_from_glist (QofIdType type, GList *glist)
 Create a secondary collection from a GList.

Defines

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

Functions

const GUIDqof_entity_get_guid (QofEntity *)


Typedef Documentation

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

Callback type for qof_entity_foreach

Definition at line 185 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 202 of file qofid.c.

00203 {
00204         QofEntity *e;
00205 
00206         e = NULL;
00207         if (!coll || !ent) { return FALSE; }
00208         if (guid_equal(&ent->guid, guid_null())) { return FALSE; }
00209         g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
00210         e = qof_collection_lookup_entity(coll, &ent->guid);
00211         if ( e != NULL ) { return FALSE; }
00212         g_hash_table_insert (coll->hash_of_entities, &ent->guid, ent);
00213         qof_collection_mark_dirty(coll);
00214         return TRUE;
00215 }

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

00267 {
00268         gint value;
00269 
00270         value = 0;
00271         if (!target && !merge) { return 0; }
00272         if (target == merge) { return 0; }
00273         if (!target && merge) { return -1; }
00274         if (target && !merge) { return 1; }
00275         if(target->e_type != merge->e_type) { return -1; }
00276         qof_collection_set_data(target, &value);
00277         qof_collection_foreach(merge, collection_compare_cb, target);
00278         value = *(gint*)qof_collection_get_data(target);
00279         if(value == 0) {
00280                 qof_collection_set_data(merge, &value);
00281                 qof_collection_foreach(target, collection_compare_cb, merge);
00282                 value = *(gint*)qof_collection_get_data(merge);
00283         }
00284         return value;
00285 }

guint qof_collection_count QofCollection col  ) 
 

return the number of entities in the collection.

Definition at line 317 of file qofid.c.

00318 {
00319         guint c;
00320 
00321         c = g_hash_table_size(col->hash_of_entities);
00322         return c;
00323 }

void qof_collection_destroy QofCollection col  ) 
 

XXX there should be a destroy notifier for this

Definition at line 156 of file qofid.c.

00157 {
00158   CACHE_REMOVE (col->e_type);
00159   g_hash_table_destroy(col->hash_of_entities);
00160   col->e_type = NULL;
00161   col->hash_of_entities = NULL;
00162   col->data = NULL;   
00163   g_free (col);
00164 }

void qof_collection_foreach QofCollection ,
QofEntityForeachCB  ,
gpointer  user_data
 

Call the callback for each entity in the collection.

Definition at line 375 of file qofid.c.

00377 {
00378   struct _iterate iter;
00379 
00380   g_return_if_fail (col);
00381   g_return_if_fail (cb_func);
00382 
00383   iter.fcn = cb_func;
00384   iter.data = user_data;
00385 
00386   g_hash_table_foreach (col->hash_of_entities, foreach_cb, &iter);
00387 }

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

00299 {
00300         QofCollection *coll;
00301         QofEntity *ent;
00302         GList *list;
00303 
00304         coll = qof_collection_new(type);
00305         for(list = glist; list != NULL; list = list->next)
00306         {
00307                 ent = (QofEntity*)list->data;
00308                 if(FALSE == qof_collection_add_entity(coll, ent))
00309                 {
00310                         return NULL;
00311                 }
00312         }
00313         return coll;
00314 }

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.

Definition at line 348 of file qofid.c.

00349 {
00350    return col ? col->data : NULL;
00351 }

QofIdType qof_collection_get_type QofCollection  ) 
 

return the type that the collection stores

Definition at line 170 of file qofid.c.

00171 {
00172   return col->e_type;
00173 }

gboolean qof_collection_is_dirty QofCollection col  ) 
 

Return value of 'dirty' flag on collection

Definition at line 328 of file qofid.c.

00329 {
00330    return col ? col->is_dirty : FALSE;
00331 }

QofEntity* qof_collection_lookup_entity QofCollection ,
const GUID
 

Find the entity going only from its guid

Definition at line 288 of file qofid.c.

00289 {
00290   QofEntity *ent;
00291   g_return_val_if_fail (col, NULL);
00292   if (guid == NULL) return NULL;
00293   ent = g_hash_table_lookup (col->hash_of_entities, guid);
00294   return ent;
00295 }

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

00228 {
00229         if(!target || !merge) { return FALSE; }
00230         g_return_val_if_fail (target->e_type == merge->e_type, FALSE);
00231         qof_collection_foreach(merge, collection_merge_cb, target);
00232         return TRUE;
00233 }

QofCollection* qof_collection_new QofIdType  type  ) 
 

create a new collection of entities of type

Definition at line 145 of file qofid.c.

00146 {
00147   QofCollection *col;
00148   col = g_new0(QofCollection, 1);
00149   col->e_type = CACHE_INSERT (type);
00150   col->hash_of_entities = g_hash_table_new (id_hash, id_compare);
00151   col->data = NULL;
00152   return col;
00153 }


Generated on Fri May 12 17:57:21 2006 for QOF by  doxygen 1.4.4