Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Entities
[Entity: Types, Identity and Instance Framework]


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. An id with type QOF_ID_NONE does not refer to any entity, although that may change (???). 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 (??? Huh?). 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.


Files

file  qofid.h
 QOF entity type identification system.


Data Structures

struct  QofEntity_s

Collections of Entities

typedef void(* QofEntityForeachCB )(QofEntity *, gpointer user_data)
QofCollection * qof_collection_new (QofIdType type)
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 Entity Initialization & Shutdown

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

Defines

#define QOF_ID_NONE   NULL
#define QOF_ID_NULL   "null"
#define QOF_ID_BOOK   "Book"
#define QOF_ID_FREQSPEC   "FreqSpec"
#define QOF_ID_SESSION   "Session"
#define QOF_ENTITY(object)   ((QofEntity *)(object))
#define QSTRCMP(da, db)
#define QOF_CHECK_TYPE(obj, type)   (0 == QSTRCMP((type),(((QofEntity *)(obj))->e_type)))
#define QOF_CHECK_CAST(obj, e_type, c_type)

Typedefs

typedef const char * QofIdType
typedef const char * QofIdTypeConst
typedef QofEntity_s QofEntity
typedef QofCollection_s QofCollection

Functions

const GUIDqof_entity_get_guid (QofEntity *)


Define 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);                                                   \
  }))
cast object to the indicated type, print error message if its bad

#define QOF_CHECK_TYPE obj,
type   )     (0 == QSTRCMP((type),(((QofEntity *)(obj))->e_type)))
 

return TRUE if object is of the given type

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

simple,cheesy cast but holds water for now

#define QSTRCMP da,
db   ) 
 

Value:

({                \
  int 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


Typedef Documentation

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

Callback type for qof_entity_foreach


Function Documentation

void qof_collection_destroy QofCollection *  col  ) 
 

void qof_collection_foreach QofCollection *  ,
QofEntityForeachCB  ,
gpointer  user_data
 

Call the callback for each entity in the collection.

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.

QofIdType qof_collection_get_type QofCollection *   ) 
 

return the type that the collection stores

gboolean qof_collection_is_dirty QofCollection *  col  ) 
 

Return value of 'dirty' flag on collection

QofEntity* qof_collection_lookup_entity QofCollection *  ,
const GUID
 

Find the entity going only from its guid

const GUID* qof_entity_get_guid QofEntity *   ) 
 

Return the GUID of this entity

void qof_entity_init QofEntity *  ,
QofIdType  ,
QofCollection * 
 

Initialise the memory associated with an entity

void qof_entity_release QofEntity *   ) 
 

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


Generated on Sun May 23 15:41:48 2004 for QOF by doxygen 1.3.6-20040222