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.

  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.


Files

file  qofid.h
 QOF entity type identification system.

Data Structures

struct  QofEntity_s

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


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

Definition at line 118 of file qofid.h.

#define QOF_CHECK_TYPE obj,
type   ) 
 

Value:

(((obj) != NULL) && \
  (0 == QSTRCMP((type),(((QofEntity *)(obj))->e_type))))
return TRUE if object is of the given type

Definition at line 113 of file qofid.h.

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

simple,cheesy cast but holds water for now

Definition at line 93 of file qofid.h.

#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 96 of file qofid.h.


Typedef Documentation

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 137 of file qofid.h.

typedef struct QofEntity_s QofEntity
 

QofEntity declaration

Definition at line 128 of file qofid.h.

typedef const gchar* QofIdType
 

QofIdType declaration

Definition at line 80 of file qofid.h.

typedef const gchar* QofIdTypeConst
 

QofIdTypeConst declaration

Definition at line 82 of file qofid.h.

typedef const gchar* QofLogModule
 

QofLogModule declaration

Definition at line 84 of file qofid.h.


Generated on Fri May 12 18:00:36 2006 for QOF by  doxygen 1.4.4