Objects

QOF Objects provide the means for associating a storage backend to a set of QOF Entities. More...

Files
file	qofobject.h
	the Core Object Registration/Lookup Interface

Data Structures
struct	QofObject
	This is the QofObject Class descriptor. More...

Macros
#define	QOF_OBJECT_VERSION   3
	Defines the version of the core object object registration interface.
#define	QOF_MOD_OBJECT   "qof.object"

Typedefs
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)
	Register new types of object objects.
const QofObject *	qof_object_lookup (QofIdTypeConst type_name)
	Lookup an object definition.
gpointer	qof_object_new_instance (QofIdTypeConst type_name, QofBook *book)
	Create an instance of the indicated type, returning a pointer to that instance.
const char *	qof_object_get_type_label (QofIdTypeConst type_name)
	Get the printable label for a type.
const char *	qof_object_printable (QofIdTypeConst type_name, gpointer instance)
void	qof_object_foreach_type (QofForeachTypeCB cb, gpointer user_data)
	Invoke the callback 'cb' on every object class definition.
void	qof_object_foreach (QofIdTypeConst type_name, QofBook *book, QofInstanceForeachCB cb, gpointer user_data)
	Invoke the callback 'cb' on every instance ov a particular object type.
void	qof_object_foreach_sorted (QofIdTypeConst type_name, QofBook *book, QofInstanceForeachCB cb, gpointer user_data)
	Invoke callback 'cb' on each instance in guid orted order.

Initialize the object registration subsystem
void	qof_object_initialize (void)
void	qof_object_shutdown (void)

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.

Macro Definition Documentation

QOF_MOD_OBJECT

#define QOF_MOD_OBJECT   "qof.object"

Definition at line 65 of file qofobject.h.

QOF_OBJECT_VERSION

#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 63 of file qofobject.h.

Typedef Documentation

QofForeachBackendTypeCB

typedef void(* QofForeachBackendTypeCB) (QofIdTypeConst type, gpointer backend_data, gpointer user_data)

Definition at line 70 of file qofobject.h.

QofForeachCB

typedef void(* QofForeachCB) (gpointer obj, gpointer user_data)

Definition at line 68 of file qofobject.h.

QofForeachTypeCB

typedef void(* QofForeachTypeCB) (QofObject *type, gpointer user_data)

Definition at line 69 of file qofobject.h.

Function Documentation

qof_object_foreach()

void qof_object_foreach	(	QofIdTypeConst	type_name,
		QofBook *	book,
		QofInstanceForeachCB	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 185 of file qofobject.cpp.

{
    QofCollection *col;
    const QofObject *obj;
 
    if (!book || !type_name)
    {
        return;
    }
    PINFO ("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);
    if (!col)
    {
        return;
    }
    if (obj->foreach)
    {
        obj->foreach (col, cb, user_data);
    }
    return;
}

qof_object_foreach_sorted()

void qof_object_foreach_sorted	(	QofIdTypeConst	type_name,
		QofBook *	book,
		QofInstanceForeachCB	cb,
		gpointer	user_data
	)

Invoke callback 'cb' on each instance in guid orted order.

Definition at line 223 of file qofobject.cpp.

{
    GList *list = nullptr;
    GList *iter;
 
    qof_object_foreach(type_name, book, do_prepend, &list);
 
    list = g_list_sort(list, qof_instance_guid_compare);
 
    for (iter = list; iter; iter = iter->next)
    {
        cb(static_cast<QofInstance*>(iter->data), user_data);
    }
 
    g_list_free(list);
 
    // FIXME: Apparently this is a memory leak, as this g_list_free doesn't
    // free all of the allocated memory of g_list_append in do_append(). Why?!?
    // Does g_list_sort have special side-effects on the memory of the list?
    // Subsequently, I've changed the g_list_append into g_list_prepend, but
    // solely for performance reasons. To my surprise, this also makes the
    // dubious memory leak go away. But again why?!?
}

qof_object_foreach_type()

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 153 of file qofobject.cpp.

{
    GList *l;
 
    if (!cb) return;
 
    for (l = object_modules; l; l = l->next)
    {
        QofObject *obj = static_cast<QofObject*>(l->data);
        (cb) (obj, user_data);
    }
}

qof_object_get_type_label()

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 263 of file qofobject.cpp.

{
    const QofObject *obj;
 
    if (!type_name) return nullptr;
 
    obj = qof_object_lookup (type_name);
    if (!obj) return nullptr;
 
    return (obj->type_label);
}

qof_object_initialize()

void qof_object_initialize

(

void

)

Definition at line 277 of file qofobject.cpp.

{
    if (object_is_initialized) return;
    object_is_initialized = TRUE;
}

qof_object_lookup()

const QofObject * qof_object_lookup

(

QofIdTypeConst

type_name

)

Lookup an object definition.

Definition at line 322 of file qofobject.cpp.

{
    GList *iter;
    const QofObject *obj;
 
    g_return_val_if_fail (object_is_initialized, nullptr);
 
    if (!name) return nullptr;
 
    for (iter = object_modules; iter; iter = iter->next)
    {
        obj = static_cast<QofObject*>(iter->data);
        if (!g_strcmp0 (obj->e_type, name))
            return obj;
    }
    return nullptr;
}

qof_object_new_instance()

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 65 of file qofobject.cpp.

{
    const QofObject *obj;
 
    if (!type_name) return nullptr;
 
    obj = qof_object_lookup (type_name);
    if (!obj) return nullptr;
 
    if (obj->create)
        return (obj->create (book));
 
    return nullptr;
}

qof_object_printable()

const char * qof_object_printable	(	QofIdTypeConst	type_name,
		gpointer	instance
	)

Returns

a Human-readable string name for an instance

Definition at line 248 of file qofobject.cpp.

{
    const QofObject *b_obj;
 
    if (!type_name || !obj) return nullptr;
 
    b_obj = qof_object_lookup (type_name);
    if (!b_obj) return nullptr;
 
    if (b_obj->printable)
        return (b_obj->printable (obj));
 
    return nullptr;
}

qof_object_register()

gboolean qof_object_register

(

const QofObject *

object

)

Register new types of object objects.

Definition at line 299 of file qofobject.cpp.

{
    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 (static_cast<QofBook*>(node->data));
    }
 
    return TRUE;
}

qof_object_shutdown()

void qof_object_shutdown

(

void

)

Definition at line 283 of file qofobject.cpp.

{
    g_return_if_fail (object_is_initialized == TRUE);
 
    g_list_free (object_modules);
    object_modules = nullptr;
    g_list_free (book_list);
    book_list = nullptr;
    object_is_initialized = FALSE;
}