Entities

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
#define	QOF_CHECK_CAST(obj, e_type, c_type)
	cast object to the indicated type, print error message if its bad

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

Collections of Entities
QofCollection declaration Parameters e_type QofIdType is_dirty gboolean hash_of_entities GHashTable data gpointer, 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.
void	qof_collection_destroy (QofCollection *col)
	destroy the collection
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_sorted (const QofCollection *col, QofInstanceForeachCB cb_func, gpointer user_data, GCompareFunc sort_fn)
	Call the callback for each entity in the collection.
void	qof_collection_foreach (const QofCollection *, QofInstanceForeachCB, gpointer user_data)
gpointer	qof_collection_get_data (const QofCollection *col)
	Store and retrieve arbitrary object-defined data.
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.
void	qof_collection_remove_entity (QofInstance *ent)
gint	qof_collection_compare (QofCollection *target, QofCollection *merge)
	Compare two secondary collections.

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 and 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);                                                   \
  }))

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

Definition at line 107 of file qofid.h.

                   :                                          \
  (c_type *) ({                                               \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL,               \
       "Error: Bad QofInstance at %s:%d", __FILE__, __LINE__);  \
     (obj);                                                   \
  }))

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.

QOF_ID_BOOK

#define QOF_ID_BOOK   "Book"

Definition at line 96 of file qofid.h.

QOF_ID_NONE

#define QOF_ID_NONE   NULL

Definition at line 93 of file qofid.h.

QOF_ID_NULL

#define QOF_ID_NULL   "null"

Definition at line 94 of file qofid.h.

QOF_ID_SESSION

#define QOF_ID_SESSION   "Session"

Definition at line 97 of file qofid.h.

QSTRCMP

#define QSTRCMP   g_strcmp0

Definition at line 99 of file qofid.h.

Typedef Documentation

QofIdType

typedef const gchar* QofIdType

QofIdType declaration.

Definition at line 80 of file qofid.h.

QofIdTypeConst

typedef const gchar* QofIdTypeConst

QofIdTypeConst declaration.

Definition at line 82 of file qofid.h.

QofInstanceForeachCB

typedef void(* QofInstanceForeachCB) (QofInstance *, gpointer user_data)

Callback type for qof_collection_foreach.

Definition at line 146 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 109 of file qofid.cpp.

{
    QofInstance *e;
    const GncGUID *guid;
 
    e = NULL;
    if (!coll || !ent)
    {
        return FALSE;
    }
    guid = qof_instance_get_guid(ent);
    if (guid_equal(guid, guid_null()))
    {
        return FALSE;
    }
    g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
    e = qof_collection_lookup_entity(coll, guid);
    if ( e != NULL )
    {
        return FALSE;
    }
    g_hash_table_insert (coll->hash_of_entities, (gpointer)guid, ent);
    return TRUE;
}

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

{
    gint value;
 
    value = 0;
    if (!target && !merge)
    {
        return 0;
    }
    if (target == merge)
    {
        return 0;
    }
    if (!target && merge)
    {
        return -1;
    }
    if (target && !merge)
    {
        return 1;
    }
    if (target->e_type != merge->e_type)
    {
        return -1;
    }
    qof_collection_set_data(target, &value);
    qof_collection_foreach(merge, collection_compare_cb, target);
    value = *(gint*)qof_collection_get_data(target);
    if (value == 0)
    {
        qof_collection_set_data(merge, &value);
        qof_collection_foreach(target, collection_compare_cb, merge);
        value = *(gint*)qof_collection_get_data(merge);
    }
    return value;
}

qof_collection_count()

guint qof_collection_count

(

const QofCollection *

col

)

return the number of entities in the collection.

Definition at line 221 of file qofid.cpp.

{
    guint c;
 
    c = g_hash_table_size(col->hash_of_entities);
    return c;
}

qof_collection_destroy()

void qof_collection_destroy

(

QofCollection *

col

)

destroy the collection

Definition at line 64 of file qofid.cpp.

{
    delete col;
}

qof_collection_foreach()

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

Definition at line 303 of file qofid.cpp.

{
    qof_collection_foreach_sorted (col, cb_func, user_data, nullptr);
}

qof_collection_foreach_sorted()

void qof_collection_foreach_sorted	(	const QofCollection *	col,
		QofInstanceForeachCB	cb_func,
		gpointer	user_data,
		GCompareFunc	sort_fn
	)

Call the callback for each entity in the collection.

Definition at line 283 of file qofid.cpp.

{
    GList *entries;
 
    g_return_if_fail (col);
    g_return_if_fail (cb_func);
 
    PINFO("Hash Table size of %s before is %d", col->e_type, g_hash_table_size(col->hash_of_entities));
 
    entries = g_hash_table_get_values (col->hash_of_entities);
    if (sort_fn)
        entries = g_list_sort (entries, sort_fn);
    g_list_foreach (entries, (GFunc)cb_func, user_data);
    g_list_free (entries);
 
    PINFO("Hash Table size of %s after is %d", col->e_type, g_hash_table_size(col->hash_of_entities));
}

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

{
    return col ? col->data : NULL;
}

qof_collection_get_type()

QofIdType qof_collection_get_type

(

const QofCollection *

col

)

return the type that the collection stores

Definition at line 73 of file qofid.cpp.

{
    return col->e_type;
}

qof_collection_is_dirty()

gboolean qof_collection_is_dirty

(

const QofCollection *

col

)

Return value of 'dirty' flag on collection.

Definition at line 232 of file qofid.cpp.

{
    return col ? col->is_dirty : FALSE;
}

qof_collection_lookup_entity()

QofInstance * qof_collection_lookup_entity	(	const QofCollection *	col,
		const GncGUID *	guid
	)

Find the entity going only from its guid.

Definition at line 209 of file qofid.cpp.

{
    QofInstance *ent;
    g_return_val_if_fail (col, NULL);
    if (guid == NULL) return NULL;
    ent = static_cast<QofInstance*>(g_hash_table_lookup (col->hash_of_entities,
                             guid));
    if (ent != NULL && qof_instance_get_destroying(ent)) return NULL;   
    return ent;
}

qof_collection_new()

QofCollection * qof_collection_new

(

QofIdType

type

)

create a new collection of entities of type

Definition at line 58 of file qofid.cpp.

{
    return new QofCollection (type);
}

qof_collection_remove_entity()

void qof_collection_remove_entity

(

QofInstance *

ent

)

Definition at line 81 of file qofid.cpp.

{
    QofCollection *col;
    const GncGUID *guid;
 
    if (!ent) return;
    col = qof_instance_get_collection(ent);
    if (!col) return;
    guid = qof_instance_get_guid(ent);
    g_hash_table_remove (col->hash_of_entities, guid);
    qof_instance_set_collection(ent, NULL);
}

qof_collection_set_data()

void qof_collection_set_data	(	QofCollection *	col,
		gpointer	user_data
	)

Definition at line 272 of file qofid.cpp.

{
    if (col)
    {
        col->data = user_data;
    }
}