Class

This file defines a class messaging system reminiscent of traditional OO-style setter and getter interfaces to object properties. More...

Files
file	qofclass.h
	API for registering parameters on objects.

Data Structures
struct	QofParam
	This structure is for each queryable parameter in an object. More...

Macros
#define	QOF_MOD_CLASS   "qof.class"

Typedefs
typedef const char *	QofType
	Type of Parameters (String, Date, Numeric, GncGUID, etc.)
typedef gpointer(*	QofAccessFunc) (gpointer object, const QofParam *param)
	The QofAccessFunc defines an arbitrary function pointer for access functions.
typedef void(*	QofSetterFunc) (gpointer, gpointer)
	The QofSetterFunc defines an function pointer for parameter setters.
typedef gint(*	QofCompareFunc) (gpointer a, gpointer b, gint compare_options, QofParam *getter)
typedef int(*	QofSortFunc) (gconstpointer, gconstpointer)
	This function is the default sort function for a particular object type.
typedef void(*	QofClassForeachCB) (QofIdTypeConst, gpointer)
	Type definition for the class callback function.
typedef void(*	QofParamForeachCB) (QofParam *, gpointer user_data)
	Type definition for the parameter callback function.

Functions
void	qof_class_register (QofIdTypeConst obj_name, QofSortFunc default_sort_fcn, const QofParam *params)
	This function registers a new object class with the Qof subsystem.
gboolean	qof_class_is_registered (QofIdTypeConst obj_name)
	An example:
QofType	qof_class_get_parameter_type (QofIdTypeConst obj_name, const char *param_name)
	Return the core datatype of the specified object's parameter.
const QofParam *	qof_class_get_parameter (QofIdTypeConst obj_name, const char *parameter)
	Return the registered Parameter Definition for the requested parameter.
QofAccessFunc	qof_class_get_parameter_getter (QofIdTypeConst obj_name, const char *parameter)
	Return the object's parameter getter function.
QofSetterFunc	qof_class_get_parameter_setter (QofIdTypeConst obj_name, const char *parameter)
	Return the object's parameter setter function.
void	qof_class_foreach (QofClassForeachCB, gpointer user_data)
	Call the callback once for each object class that is registered with the system.
void	qof_class_param_foreach (QofIdTypeConst obj_name, QofParamForeachCB, gpointer user_data)
	Call the callback once for each parameter on the indicated object class.
GList *	qof_class_get_referenceList (QofIdTypeConst type)
	List of the parameters that could be references.

Core types
Core data types for objects that can be used in parameters. Note that QofIdTypes may also be used and will create a single reference between two known objects.
#define	QOF_TYPE_STRING   "string"
#define	QOF_TYPE_DATE   "date"
#define	QOF_TYPE_NUMERIC   "numeric"
#define	QOF_TYPE_DEBCRED   "debcred"
#define	QOF_TYPE_GUID   "guid"
#define	QOF_TYPE_INT32   "gint32"
#define	QOF_TYPE_INT64   "gint64"
#define	QOF_TYPE_DOUBLE   "double"
#define	QOF_TYPE_BOOLEAN   "boolean"
#define	QOF_TYPE_KVP   "kvp"
#define	QOF_TYPE_CHAR   "character"
#define	QOF_TYPE_CHOICE   "choice" /* was moved from (deleted) qofchoice.h */

Detailed Description

This file defines a class messaging system reminiscent of traditional OO-style setter and getter interfaces to object properties.

A C-language object can declare a collection of setters and getters on itself that can then be used to perform run-time (as opposed to compile-time) bindings to the object.

To put it differently, a QOF class is a set of parameter getters and setters that are associated with an object type. Given a pointer to some thing, the setters and getters can be used to get and set values out of that thing. Note that the pointer to "some thing" need not be a pointer to a QOF Entity or Instance (although QOF classes are more interesting when used with Entities/Instances). What "some thing" is defined entirely by the programmer declaring a new QOF Class.

Because a QOF Class associates getters and setters with a type, one can then ask, at run time, what parameters are associated with a given type, even if those parameters were not known at compile time. Thus, a QOF Class is sort-of like a DynAny implementation. QOF classes can be used to provide "object introspection", i.e. asking object to describe itself.

The QOF Query subsystem depends on QOF classes having been declared; the Query uses the getters to get values associated with particular instances.

A QofAccessFunc or QofSetterFunc do not need to be public functions, if you need to add functions to an object with an established API, define the additional QOF routines as static. Only the register routine needs to be public.

Macro Definition Documentation

QOF_MOD_CLASS

#define QOF_MOD_CLASS   "qof.class"

Definition at line 79 of file qofclass.h.

QOF_TYPE_BOOLEAN

#define QOF_TYPE_BOOLEAN   "boolean"

Definition at line 98 of file qofclass.h.

QOF_TYPE_CHAR

#define QOF_TYPE_CHAR   "character"

Definition at line 100 of file qofclass.h.

QOF_TYPE_CHOICE

#define QOF_TYPE_CHOICE   "choice" /* was moved from (deleted) qofchoice.h */

Definition at line 101 of file qofclass.h.

QOF_TYPE_DATE

#define QOF_TYPE_DATE   "date"

Definition at line 91 of file qofclass.h.

QOF_TYPE_DEBCRED

#define QOF_TYPE_DEBCRED   "debcred"

Definition at line 93 of file qofclass.h.

QOF_TYPE_DOUBLE

#define QOF_TYPE_DOUBLE   "double"

Definition at line 97 of file qofclass.h.

QOF_TYPE_GUID

#define QOF_TYPE_GUID   "guid"

Definition at line 94 of file qofclass.h.

QOF_TYPE_INT32

#define QOF_TYPE_INT32   "gint32"

Definition at line 95 of file qofclass.h.

QOF_TYPE_INT64

#define QOF_TYPE_INT64   "gint64"

Definition at line 96 of file qofclass.h.

QOF_TYPE_KVP

#define QOF_TYPE_KVP   "kvp"

Definition at line 99 of file qofclass.h.

QOF_TYPE_NUMERIC

#define QOF_TYPE_NUMERIC   "numeric"

Definition at line 92 of file qofclass.h.

QOF_TYPE_STRING

#define QOF_TYPE_STRING   "string"

Definition at line 90 of file qofclass.h.

Typedef Documentation

QofAccessFunc

typedef gpointer(* QofAccessFunc) (gpointer object, const QofParam *param)

The QofAccessFunc defines an arbitrary function pointer for access functions.

This is needed because C doesn't have templates, so we just cast a lot. Real functions must be of the form:

  param_type getter_func (object_type *self);

or param_type getter_func (object_type *self, QofParam *param);

The additional argument 'param' allows generic getter functions to be implemented, because this argument provides for a way to identify the expected getter_func return type at runtime. It also provides a place for the user to hang additional user-defined data.

Definition at line 123 of file qofclass.h.

QofClassForeachCB

typedef void(* QofClassForeachCB) (QofIdTypeConst, gpointer)

Type definition for the class callback function.

Definition at line 228 of file qofclass.h.

QofCompareFunc

typedef gint(* QofCompareFunc) (gpointer a, gpointer b, gint compare_options, QofParam *getter)

Definition at line 136 of file qofclass.h.

QofParamForeachCB

typedef void(* QofParamForeachCB) (QofParam *, gpointer user_data)

Type definition for the parameter callback function.

Definition at line 236 of file qofclass.h.

QofSetterFunc

typedef void(* QofSetterFunc) (gpointer, gpointer)

The QofSetterFunc defines an function pointer for parameter setters.

Real functions must be of the form:

void setter_func (object_type *self, param_type *param);

Definition at line 130 of file qofclass.h.

QofSortFunc

typedef int(* QofSortFunc) (gconstpointer, gconstpointer)

This function is the default sort function for a particular object type.

Definition at line 168 of file qofclass.h.

QofType

typedef const char* QofType

Type of Parameters (String, Date, Numeric, GncGUID, etc.)

Definition at line 104 of file qofclass.h.

Function Documentation

qof_class_foreach()

void qof_class_foreach	(	QofClassForeachCB	cb,
		gpointer	user_data
	)

Call the callback once for each object class that is registered with the system.

The 'user_data' is passed back to the callback.

Definition at line 219 of file qofclass.cpp.

{
    struct class_iterate iter;
 
    if (!cb) return;
    if (!classTable) return;
 
    iter.fcn = cb;
    iter.data = user_data;
 
    g_hash_table_foreach (classTable, class_foreach_cb, &iter);
}

qof_class_get_parameter()

const QofParam * qof_class_get_parameter	(	QofIdTypeConst	obj_name,
		const char *	parameter
	)

Return the registered Parameter Definition for the requested parameter.

Definition at line 136 of file qofclass.cpp.

{
    GHashTable *ht;
 
    g_return_val_if_fail (obj_name, NULL);
    g_return_val_if_fail (parameter, NULL);
    if (!check_init()) return NULL;
 
    ht = static_cast<GHashTable*>(g_hash_table_lookup (classTable, obj_name));
    if (!ht)
    {
        PWARN ("no object of type %s", obj_name);
        return NULL;
    }
 
    return static_cast<QofParam*>(g_hash_table_lookup (ht, parameter));
}

qof_class_get_parameter_getter()

QofAccessFunc qof_class_get_parameter_getter	(	QofIdTypeConst	obj_name,
		const char *	parameter
	)

Return the object's parameter getter function.

Definition at line 156 of file qofclass.cpp.

{
    const QofParam *prm;
 
    g_return_val_if_fail (obj_name, NULL);
    g_return_val_if_fail (parameter, NULL);
 
    prm = qof_class_get_parameter (obj_name, parameter);
    if (prm)
        return prm->param_getfcn;
 
    return NULL;
}

qof_class_get_parameter_setter()

QofSetterFunc qof_class_get_parameter_setter	(	QofIdTypeConst	obj_name,
		const char *	parameter
	)

Return the object's parameter setter function.

Definition at line 172 of file qofclass.cpp.

{
    const QofParam *prm;
 
    g_return_val_if_fail (obj_name, NULL);
    g_return_val_if_fail (parameter, NULL);
 
    prm = qof_class_get_parameter (obj_name, parameter);
    if (prm)
        return prm->param_setfcn;
 
    return NULL;
}

qof_class_get_parameter_type()

QofType qof_class_get_parameter_type	(	QofIdTypeConst	obj_name,
		const char *	param_name
	)

Return the core datatype of the specified object's parameter.

Definition at line 188 of file qofclass.cpp.

{
    const QofParam *prm;
 
    if (!obj_name || !param_name) return NULL;
 
    prm = qof_class_get_parameter (obj_name, param_name);
    if (!prm) return NULL;
 
    return (prm->param_type);
}

qof_class_get_referenceList()

GList * qof_class_get_referenceList

(

QofIdTypeConst

type

)

List of the parameters that could be references.

Simple check to return a GList of all parameters of this object type that are not known QOF data types. Used for partial QofBook support, see ::QofInstanceReference

Definition at line 334 of file qofclass.cpp.

{
    GList *ref_list;
    struct param_ref_list b;
 
    ref_list = NULL;
    b.list = NULL;
    qof_class_param_foreach(type, find_reference_param_cb, &b);
    ref_list = g_list_copy(b.list);
    return ref_list;
}

qof_class_is_registered()

gboolean qof_class_is_registered

(

QofIdTypeConst

obj_name

)

An example:

#define MY_OBJ_MEMO "memo" #define MY_OBJ_VALUE "value" #define MY_OBJ_DATE "date" #define MY_OBJ_ACCOUNT "account" #define MY_OBJ_TRANS "trans"

static QofParam myParams[] = { { MY_OBJ_MEMO, QOF_TYPE_STRING, myMemoGetter, NULL }, { MY_OBJ_VALUE, QOF_TYPE_NUMERIC, myValueGetter, NULL }, { MY_OBJ_DATE, QOF_TYPE_DATE, myDateGetter, NULL }, { MY_OBJ_ACCOUNT, GNC_ID_ACCOUNT, myAccountGetter, NULL }, { MY_OBJ_TRANS, GNC_ID_TRANS, myTransactionGetter, NULL }, NULL };

qof_class_register ("myObjectName", myObjectCompare, &myParams); Return true if the the indicated type is registered, else return FALSE.

Definition at line 125 of file qofclass.cpp.

{
    if (!obj_name) return FALSE;
    if (!check_init()) return FALSE;
 
    if (g_hash_table_lookup (classTable, obj_name)) return TRUE;
 
    return FALSE;
}

qof_class_param_foreach()

void qof_class_param_foreach	(	QofIdTypeConst	obj_name,
		QofParamForeachCB	cb,
		gpointer	user_data
	)

Call the callback once for each parameter on the indicated object class.

The 'user_data' is passed back to the callback.

Definition at line 250 of file qofclass.cpp.

{
    struct parm_iterate iter;
    GHashTable *param_ht;
 
    if (!obj_name || !cb) return;
    if (!classTable) return;
    param_ht = static_cast<GHashTable*>(g_hash_table_lookup (classTable, obj_name));
    if (!param_ht) return;
 
    iter.fcn = cb;
    iter.data = user_data;
 
    g_hash_table_foreach (param_ht, param_foreach_cb, &iter);
}

qof_class_register()

void qof_class_register	(	QofIdTypeConst	obj_name,
		QofSortFunc	default_sort_fcn,
		const QofParam *	params
	)

This function registers a new object class with the Qof subsystem.

In particular, it registers the set of setters and getters for controlling the object. The getters are typically used by the query subsystem to query type specific data. Note that there is no particular requirement for there to be a setter for every getter or even vice-versa, nor is there any requirement for these to map 'cleanly' or orthogonally to the underlying object. The parameters are really just a set of value setting and getting routines.

The "params" argument must be a NULL-terminated array of QofParam. It may be NULL if there are no parameters to be registered.

Definition at line 86 of file qofclass.cpp.

{
    GHashTable *ht;
    int i;
 
    if (!obj_name) return;
    if (!check_init()) return;
 
    if (default_sort_function)
    {
        g_hash_table_insert (sortTable, (char *)obj_name,
                 reinterpret_cast<void*>(default_sort_function));
    }
 
    ht = static_cast<GHashTable*>(g_hash_table_lookup (classTable, obj_name));
 
    /* If it doesn't already exist, create a new table for this object */
    if (!ht)
    {
        ht = g_hash_table_new (g_str_hash, g_str_equal);
        g_hash_table_insert (classTable, (char *)obj_name, ht);
    }
 
    /* At least right now, we allow dummy, parameterless objects,
     * for testing purposes.  Although I suppose that should be
     * an error..  */
    /* Now insert all the parameters */
    if (params)
    {
        for (i = 0; params[i].param_name; i++)
            g_hash_table_insert (ht,
                                 (char *)params[i].param_name,
                                 (gpointer)&(params[i]));
    }
}