Objects
[Object: Dynamic Object Class Framework]


Detailed Description

QOF Objects provide the means for associating a storage backend to a set of QOF Entities. While an entity can be though of as an identified instance of some thing, the QOF Object provides for a way to associate instances with a storage backend. Storage might be file or SQL storage.

QOF Objects are also used by the query system ....

To work with your own QOF Objects, you can use the QOF Generator to create sample objects and a mini-application with the SQL-type query interface. http://qof-gen.sourceforge.net/

XXX todo, we should split out the storage aspects of this thing from the 'foreach' that query depends on. These are kinda unrelated concepts.


Files

file  qofobject.h
 the Core Object Registration/Lookup Interface

Data Structures

struct  _QofObject

Initialize the object registration subsystem

void qof_object_initialize (void)
void qof_object_shutdown (void)

Defines

#define QOF_OBJECT_VERSION   3
#define QOF_MOD_OBJECT   "qof-object"

Typedefs

typedef _QofObject QofObject
typedef void(*) QofForeachCB (gpointer obj, gpointer user_data)
typedef void(*) QofForeachTypeCB (QofObject *type, gpointer user_data)
typedef void(*) QofForeachBackendTypeCB (QofIdTypeConst type, gpointer backend_data, gpointer user_data)

Functions

gboolean qof_object_register (const QofObject *object)
const QofObjectqof_object_lookup (QofIdTypeConst type_name)
gpointer qof_object_new_instance (QofIdTypeConst type_name, QofBook *book)
const gchar * qof_object_get_type_label (QofIdTypeConst type_name)
const gchar * qof_object_printable (QofIdTypeConst type_name, gpointer instance)
void qof_object_foreach_type (QofForeachTypeCB cb, gpointer user_data)
void qof_object_foreach (QofIdTypeConst type_name, QofBook *book, QofEntityForeachCB cb, gpointer user_data)
gboolean qof_object_register_backend (QofIdTypeConst type_name, const gchar *backend_name, gpointer be_data)
gpointer qof_object_lookup_backend (QofIdTypeConst type_name, const gchar *backend_name)
void qof_object_foreach_backend (const char *backend_name, QofForeachBackendTypeCB cb, gpointer user_data)


Define Documentation

#define QOF_OBJECT_VERSION   3

Defines the version of the core object object registration interface. Only object modules compiled against this version of the interface will load properly

Definition at line 59 of file qofobject.h.


Function Documentation

void qof_object_foreach ( QofIdTypeConst  type_name,
QofBook book,
QofEntityForeachCB  cb,
gpointer  user_data 
)

Invoke the callback 'cb' on every instance ov a particular object type. It is presumed that the 'book' stores or somehow identifies a colllection of instances; thus the callback will be invoked only for those instances stored in the book.

Definition at line 174 of file qofobject.c.

00176 {
00177     QofCollection *col;
00178     const QofObject *obj;
00179 
00180     if (!book || !type_name)
00181     {
00182         return;
00183     }
00184     PINFO ("type=%s", type_name);
00185 
00186     obj = qof_object_lookup (type_name);
00187     if (!obj)
00188     {
00189         PERR ("No object of type %s", type_name);
00190         return;
00191     }
00192     col = qof_book_get_collection (book, obj->e_type);
00193     if (!obj)
00194     {
00195         return;
00196     }
00197     if (obj->foreach)
00198     {
00199         obj->foreach (col, cb, user_data);
00200     }
00201     return;
00202 }

void qof_object_foreach_type ( QofForeachTypeCB  cb,
gpointer  user_data 
)

Invoke the callback 'cb' on every object class definition. The user_data pointer is passed back to the callback.

Definition at line 140 of file qofobject.c.

00141 {
00142     GList *l;
00143 
00144     if (!cb)
00145         return;
00146 
00147     for (l = object_modules; l; l = l->next)
00148     {
00149         QofObject *obj = l->data;
00150         (cb) (obj, user_data);
00151     }
00152 }

const gchar* qof_object_get_type_label ( QofIdTypeConst  type_name  ) 

Get the printable label for a type. This label is *not* translated; you must use _() on it if you want a translated version.

Definition at line 223 of file qofobject.c.

00224 {
00225     const QofObject *obj;
00226 
00227     if (!type_name)
00228         return NULL;
00229 
00230     obj = qof_object_lookup (type_name);
00231     if (!obj)
00232         return NULL;
00233 
00234     return (obj->type_label);
00235 }

const QofObject* qof_object_lookup ( QofIdTypeConst  type_name  ) 

Lookup an object definition

Definition at line 304 of file qofobject.c.

00305 {
00306     GList *qiter;
00307     const QofObject *obj;
00308 
00309     g_return_val_if_fail (object_is_initialized, NULL);
00310 
00311     if (!name)
00312         return NULL;
00313 
00314     for (qiter = object_modules; qiter; qiter = qiter->next)
00315     {
00316         obj = qiter->data;
00317         if (!safe_strcmp (obj->e_type, name))
00318             return obj;
00319     }
00320     return NULL;
00321 }

gpointer qof_object_new_instance ( QofIdTypeConst  type_name,
QofBook book 
)

Create an instance of the indicated type, returning a pointer to that instance. This routine just calls the (*new) callback on the object definition.

Definition at line 42 of file qofobject.c.

00043 {
00044     const QofObject *obj;
00045 
00046     if (!type_name)
00047         return NULL;
00048 
00049     obj = qof_object_lookup (type_name);
00050     if (!obj)
00051         return NULL;
00052 
00053     if (obj->create)
00054         return (obj->create (book));
00055 
00056     return NULL;
00057 }

const gchar* qof_object_printable ( QofIdTypeConst  type_name,
gpointer  instance 
)

Returns:
a Human-readable string name for an instance

Definition at line 205 of file qofobject.c.

00206 {
00207     const QofObject *b_obj;
00208 
00209     if (!type_name || !obj)
00210         return NULL;
00211 
00212     b_obj = qof_object_lookup (type_name);
00213     if (!b_obj)
00214         return NULL;
00215 
00216     if (b_obj->printable)
00217         return (b_obj->printable (obj));
00218 
00219     return NULL;
00220 }

gboolean qof_object_register ( const QofObject object  ) 

Register new types of object objects

Definition at line 277 of file qofobject.c.

00278 {
00279     g_return_val_if_fail (object_is_initialized, FALSE);
00280 
00281     if (!object)
00282         return FALSE;
00283     g_return_val_if_fail (object->interface_version == QOF_OBJECT_VERSION,
00284         FALSE);
00285 
00286     if (g_list_index (object_modules, (gpointer) object) == -1)
00287         object_modules =
00288             g_list_prepend (object_modules, (gpointer) object);
00289     else
00290         return FALSE;
00291 
00292     /* Now initialize all the known books */
00293     if (object->book_begin && book_list)
00294     {
00295         GList *node;
00296         for (node = book_list; node; node = node->next)
00297             object->book_begin (node->data);
00298     }
00299 
00300     return TRUE;
00301 }

gboolean qof_object_register_backend ( QofIdTypeConst  type_name,
const gchar *  backend_name,
gpointer  be_data 
)

Register and lookup backend-specific data for this particular object

Definition at line 324 of file qofobject.c.

00326 {
00327     GHashTable *ht;
00328     g_return_val_if_fail (object_is_initialized, FALSE);
00329 
00330     if (!type_name || *type_name == '\0' ||
00331         !backend_name || *backend_name == '\0' || !be_data)
00332         return FALSE;
00333 
00334     ht = g_hash_table_lookup (backend_data, backend_name);
00335 
00336     /* If it doesn't already exist, create a new table for this backend */
00337     if (!ht)
00338     {
00339         ht = g_hash_table_new (g_str_hash, g_str_equal);
00340         g_hash_table_insert (backend_data, (gchar *) backend_name, ht);
00341     }
00342 
00343     /* Now insert the data */
00344     g_hash_table_insert (ht, (gchar *) type_name, be_data);
00345 
00346     return TRUE;
00347 }


Generated on Fri Sep 1 15:09:04 2006 for QOF by  doxygen 1.4.7