QOF: Class: Getting and setting entity values.

QOF 0.7.5

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Modules | Files | Data Structures | Macros | Typedefs | Functions
Class: Getting and setting entity values.
Query Object Framework

## Modules
| GUID
| Entity
| Instance

## Files
file | qofclass.h
| API for registering paramters on objects.

## Data Structures
struct | _QofParam

## Macros
#define | QOF_MOD_CLASS "qof-class"

## Typedefs
typedef const gchar * | QofType
typedef struct _QofParam | QofParam
typedef gpointer(* | QofAccessFunc) (gpointer object, const QofParam *param)
typedef void(* | QofSetterFunc) (gpointer, gpointer)
typedef gint(* | QofSortFunc) (gconstpointer, gconstpointer)
typedef void(* | QofClassForeachCB) (QofIdTypeConst, gpointer)
typedef void(* | QofParamForeachCB) (QofParam *, gpointer user_data)

## Functions
void | qof_class_register (QofIdTypeConst obj_name, QofSortFunc default_sort_fcn, const QofParam *params)
| registers a new object class with the Qof subsystem. More...
gboolean | qof_class_is_registered (QofIdTypeConst obj_name)
QofType | qof_class_get_parameter_type (QofIdTypeConst obj_name, const gchar *param_name)
const QofParam * | qof_class_get_parameter (QofIdTypeConst obj_name, const gchar *parameter)
QofAccessFunc | qof_class_get_parameter_getter (QofIdTypeConst obj_name, const gchar *parameter)
QofSetterFunc | qof_class_get_parameter_setter (QofIdTypeConst obj_name, const gchar *parameter)
void | qof_class_foreach (QofClassForeachCB, gpointer user_data)
void | qof_class_param_foreach (QofIdTypeConst obj_name, QofParamForeachCB, gpointer user_data)
GList * | qof_class_get_referenceList (QofIdTypeConst type)
| List of the parameters that could be references. More...

## 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_TIME "time"
#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_COLLECT "collection"

## 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

#define QOF_TYPE_COLLECT "collection"

secondary collections are used for one-to-many references between entities and are implemented using QofCollection. These are NOT the same as the main collections in the QofBook.

1. Each QofCollection contains one or many entities - all of a single type.
2. The entity type within the collection can be determined at run time.
3. Easy conversions to GList or whatever in the param_setfcn handler.
4. Each parameter can have its own collection.
5. Each entity can have a different type of collection to its siblings, provided that it is acceptable to the set function.
6. Each object decides which types are acceptable for which parameter in the set functions. This is then part of the API for that object.

QOF_TYPE_COLLECT has two functions, both related to one-to-many links:

- Represent a reference between 2 entities with a list of acceptable types. (one object linked to many types of single entities)
- Represent a reference between one entity and many entities of another type. (one object linked to many entities of a single type.)

If the set function can handle it, it could also be used for true one-to-many links: one object linked to many entities of many types.

n.b. Always subject to each collection holding only one type at runtime. (otherwise use books).

Definition at line 93 of file qofclass.h.

## Typedef Documentation

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 169 of file qofclass.h.

typedef void(* QofClassForeachCB) (QofIdTypeConst, gpointer)

Type definition for the class callback function.

Definition at line 275 of file qofclass.h.

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

Type definition for the paramter callback function.

Definition at line 284 of file qofclass.h.

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 176 of file qofclass.h.

typedef gint(* QofSortFunc) (gconstpointer, gconstpointer)

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

Definition at line 206 of file qofclass.h.

typedef const gchar* QofType

Type of Paramters (String, Date, Numeric, GUID, etc.)

Definition at line 150 of file qofclass.h.

## Function Documentation

void qof_class_foreach | ( | QofClassForeachCB | ,
|  | 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 233 of file qofclass.c.

234 {
235 struct class_iterate qiter;
236
237 if (!cb)
238 return;
239 if (!classTable)
240 return;
241
242 qiter.fcn = cb;
243 qiter.data = user_data;
244
245 g_hash_table_foreach (classTable, class_foreach_cb, &qiter);
246 }

const QofParam* qof_class_get_parameter | ( | QofIdTypeConst | obj_name,
|  | const gchar * | parameter
| ) |  |

Return the registered Parameter Definition for the requested parameter

Definition at line 146 of file qofclass.c.

147 {
148 GHashTable *ht;
149
150 g_return_val_if_fail (obj_name, NULL);
151 g_return_val_if_fail (parameter, NULL);
152 if (!check_init ())
153 return NULL;
154
155 ht = g_hash_table_lookup (classTable, obj_name);
156 if (!ht)
157 {
158 PWARN ("no object of type %s", obj_name);
159 return NULL;
160 }
161
162 return (g_hash_table_lookup (ht, parameter));
163 }
PWARN
#define PWARN(format, args...)
Definition: qoflog.h:191

QofAccessFunc qof_class_get_parameter_getter | ( | QofIdTypeConst | obj_name,
|  | const gchar * | parameter
| ) |  |

Return the object's parameter getter function

Definition at line 166 of file qofclass.c.

168 {
169 const QofParam *prm;
170
171 g_return_val_if_fail (obj_name, NULL);
172 g_return_val_if_fail (parameter, NULL);
173
174 prm = qof_class_get_parameter (obj_name, parameter);
175 if (prm)
176 return prm->param_getfcn;
177
178 return NULL;
179 }
_QofParam
Definition: qofclass.h:195
qof_class_get_parameter
const QofParam * qof_class_get_parameter(QofIdTypeConst obj_name, const gchar *parameter)
Definition: qofclass.c:146

QofSetterFunc qof_class_get_parameter_setter | ( | QofIdTypeConst | obj_name,
|  | const gchar * | parameter
| ) |  |

Return the object's parameter setter function

Definition at line 182 of file qofclass.c.

184 {
185 const QofParam *prm;
186
187 g_return_val_if_fail (obj_name, NULL);
188 g_return_val_if_fail (parameter, NULL);
189
190 prm = qof_class_get_parameter (obj_name, parameter);
191 if (prm)
192 return prm->param_setfcn;
193
194 return NULL;
195 }
_QofParam
Definition: qofclass.h:195
qof_class_get_parameter
const QofParam * qof_class_get_parameter(QofIdTypeConst obj_name, const gchar *parameter)
Definition: qofclass.c:146

QofType qof_class_get_parameter_type | ( | QofIdTypeConst | obj_name,
|  | const gchar * | param_name
| ) |  |

Return the core datatype of the specified object's parameter

Definition at line 198 of file qofclass.c.

200 {
201 const QofParam *prm;
202
203 if (!obj_name || !param_name)
204 return NULL;
205
206 prm = qof_class_get_parameter (obj_name, param_name);
207 if (!prm)
208 return NULL;
209
210 return (prm->param_type);
211 }
_QofParam
Definition: qofclass.h:195
qof_class_get_parameter
const QofParam * qof_class_get_parameter(QofIdTypeConst obj_name, const gchar *parameter)
Definition: qofclass.c:146

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 QofEntityReference

Definition at line 332 of file qofclass.c.

333 {
334 GList *ref_list;
335 struct param_ref_list b;
336
337 ref_list = NULL;
338 b.list = NULL;
339 qof_class_param_foreach (type, find_reference_param_cb, &b);
340 ref_list = g_list_copy (b.list);
341 return ref_list;
342 }
qof_class_param_foreach
void qof_class_param_foreach(QofIdTypeConst obj_name, QofParamForeachCB cb, gpointer user_data)
Definition: qofclass.c:267

gboolean qof_class_is_registered | ( | QofIdTypeConst | obj_name | ) |

An example:

#define MY_OBJ_MEMO "memo" #define MY_OBJ_VALUE "value" #define MY_OBJ_TIME "time" #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_TIME, QOF_TYPE_TIME, myTimeGetter, 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 132 of file qofclass.c.

133 {
134 if (!obj_name)
135 return FALSE;
136 if (!check_init ())
137 return FALSE;
138
139 if (g_hash_table_lookup (classTable, obj_name))
140 return TRUE;
141
142 return FALSE;
143 }

void qof_class_param_foreach | ( | QofIdTypeConst | obj_name,
|  | QofParamForeachCB | ,
|  | 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 267 of file qofclass.c.

269 {
270 struct parm_iterate qiter;
271 GHashTable *param_ht;
272
273 if (!obj_name || !cb)
274 return;
275 if (!classTable)
276 return;
277 param_ht = g_hash_table_lookup (classTable, obj_name);
278 if (!param_ht)
279 return;
280
281 qiter.fcn = cb;
282 qiter.data = user_data;
283
284 g_hash_table_foreach (param_ht, param_foreach_cb, &qiter);
285 }

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

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 with a constant storage size. It may be NULL if there are no parameters to be registered. When creating dynamic QofObjects, ensure the array is long enough for all objects. Registration will stop at the first NULL parameter.

Definition at line 93 of file qofclass.c.

95 {
96 GHashTable *ht;
97 int i;
98
99 if (!obj_name)
100 return;
101 if (!check_init ())
102 return;
103
104 if (default_sort_function)
105 {
106 g_hash_table_insert (sortTable, (gchar *) obj_name,
107 default_sort_function);
108 }
109
110 ht = g_hash_table_lookup (classTable, obj_name);
111
112 /* If it doesn't already exist, create a new table for this object */
113 if (!ht)
114 {
115 ht = g_hash_table_new (g_str_hash, g_str_equal);
116 g_hash_table_insert (classTable, (gchar *) obj_name, ht);
117 }
118
119 /* At least right now, we allow dummy, parameterless objects,
120 * for testing purposes. Although I suppose that should be
121 * an error.. */
122 /* Now insert all the parameters */
123 if (params)
124 {
125 for (i = 0; params[i].param_name; i++)
126 g_hash_table_insert (ht,
127 (char *) params[i].param_name, (gpointer) & (params[i]));
128 }
129 }