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 QofObject *	qof_object_lookup (QofIdTypeConst type_name)
gpointer	qof_object_new_instance (QofIdTypeConst type_name, QofBook *book)
const char *	qof_object_get_type_label (QofIdTypeConst type_name)
const char *	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 char *backend_name, gpointer be_data)
gpointer	qof_object_lookup_backend (QofIdTypeConst type_name, const char *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 144 of file qofobject.c. { QofCollection *col; const QofObject *obj; if (!book || !type_name) return; ENTER ("type=%s", type_name); obj = qof_object_lookup (type_name); if (!obj) { PERR ("No object of type %s", type_name); return; } col = qof_book_get_collection (book, obj->e_type); PINFO ("lookup obj=%p for type=%s", obj, type_name); if (!obj) return; PINFO ("type=%s foreach=%p", type_name, obj->foreach); if (obj->foreach) { obj->foreach (col, cb, user_data); } LEAVE ("type=%s", type_name); return; }

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 131 of file qofobject.c. { GList *l; if (!cb) return; for (l = object_modules; l; l = l->next) { QofObject *obj = l->data; (cb) (obj, user_data); } }

const char* 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 189 of file qofobject.c. { const QofObject *obj; if (!type_name) return NULL; obj = qof_object_lookup (type_name); if (!obj) return NULL; return (obj->type_label); }

const QofObject* qof_object_lookup (  QofIdTypeConst  type_name  )

Lookup an object definition Definition at line 258 of file qofobject.c. { GList *iter; const QofObject *obj; g_return_val_if_fail (object_is_initialized, NULL); if (!name) return NULL; for (iter = object_modules; iter; iter = iter->next) { obj = iter->data; if (!safe_strcmp (obj->e_type, name)) return obj; } return NULL; }

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 45 of file qofobject.c. { const QofObject *obj; if (!type_name) return NULL; obj = qof_object_lookup (type_name); if (!obj) return NULL; if (obj->create) return (obj->create (book)); return NULL; }

const char* qof_object_printable (  QofIdTypeConst  type_name, gpointer  instance )

Returns: a Human-readable string name for an instance Definition at line 174 of file qofobject.c. { const QofObject *b_obj; if (!type_name || !obj) return NULL; b_obj = qof_object_lookup (type_name); if (!b_obj) return NULL; if (b_obj->printable) return (b_obj->printable (obj)); return NULL; }

gboolean qof_object_register (  const QofObject *  object  )

Register new types of object objects Definition at line 236 of file qofobject.c. { g_return_val_if_fail (object_is_initialized, FALSE); if (!object) return FALSE; g_return_val_if_fail (object->interface_version == QOF_OBJECT_VERSION, FALSE); if (g_list_index (object_modules, (gpointer)object) == -1) object_modules = g_list_prepend (object_modules, (gpointer)object); else return FALSE; /* Now initialize all the known books */ if (object->book_begin && book_list) { GList *node; for (node = book_list; node; node = node->next) object->book_begin (node->data); } return TRUE; }

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

Register and lookup backend-specific data for this particular object Definition at line 275 of file qofobject.c. { GHashTable *ht; g_return_val_if_fail (object_is_initialized, FALSE); if (!type_name || *type_name == '\0' || !backend_name || *backend_name == '\0' || !be_data) return FALSE; ht = g_hash_table_lookup (backend_data, backend_name); /* If it doesn't already exist, create a new table for this backend */ if (!ht) { ht = g_hash_table_new (g_str_hash, g_str_equal); g_hash_table_insert (backend_data, (char *)backend_name, ht); } /* Now insert the data */ g_hash_table_insert (ht, (char *)type_name, be_data); return TRUE; }

---