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.
Files | |
file | qofclass.h |
API for registering paramters on objects. | |
Data Structures | |
struct | _QofParam |
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" |
Defines | |
#define | QOF_MOD_CLASS "qof-class" |
Typedefs | |
typedef const gchar * | QofType |
typedef _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) |
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. |
|
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.
QOF_TYPE_COLLECT has two functions, both related to one-to-many links:
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 96 of file qofclass.h. |
|
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 145 of file qofclass.h. |
|
Type definition for the class callback function. Definition at line 247 of file qofclass.h. |
|
Type definition for the paramter callback function. Definition at line 256 of file qofclass.h. |
|
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 152 of file qofclass.h. |
|
This function is the default sort function for a particular object type Definition at line 182 of file qofclass.h. |
|
Type of Paramters (String, Date, Numeric, GUID, etc.) Definition at line 126 of file qofclass.h. |
|
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 230 of file qofclass.c. 00231 { 00232 struct class_iterate qiter; 00233 00234 if (!cb) 00235 return; 00236 if (!classTable) 00237 return; 00238 00239 qiter.fcn = cb; 00240 qiter.data = user_data; 00241 00242 g_hash_table_foreach (classTable, class_foreach_cb, &qiter); 00243 }
|
|
Return the registered Parameter Definition for the requested parameter Definition at line 145 of file qofclass.c. 00146 { 00147 GHashTable *ht; 00148 00149 g_return_val_if_fail (obj_name, NULL); 00150 g_return_val_if_fail (parameter, NULL); 00151 if (!check_init ()) 00152 return NULL; 00153 00154 ht = g_hash_table_lookup (classTable, obj_name); 00155 if (!ht) 00156 { 00157 PWARN ("no object of type %s", obj_name); 00158 return NULL; 00159 } 00160 00161 return (g_hash_table_lookup (ht, parameter)); 00162 }
|
|
Return the object's parameter getter function Definition at line 165 of file qofclass.c. 00167 { 00168 const QofParam *prm; 00169 00170 g_return_val_if_fail (obj_name, NULL); 00171 g_return_val_if_fail (parameter, NULL); 00172 00173 prm = qof_class_get_parameter (obj_name, parameter); 00174 if (prm) 00175 return prm->param_getfcn; 00176 00177 return NULL; 00178 }
|
|
Return the object's parameter setter function Definition at line 181 of file qofclass.c. 00183 { 00184 const QofParam *prm; 00185 00186 g_return_val_if_fail (obj_name, NULL); 00187 g_return_val_if_fail (parameter, NULL); 00188 00189 prm = qof_class_get_parameter (obj_name, parameter); 00190 if (prm) 00191 return prm->param_setfcn; 00192 00193 return NULL; 00194 }
|
|
Return the core datatype of the specified object's parameter Definition at line 197 of file qofclass.c. 00199 { 00200 const QofParam *prm; 00201 00202 if (!obj_name || !param_name) 00203 return NULL; 00204 00205 prm = qof_class_get_parameter (obj_name, param_name); 00206 if (!prm) 00207 return NULL; 00208 00209 return (prm->param_type); 00210 }
|
|
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 328 of file qofclass.c. 00329 { 00330 GList *ref_list; 00331 struct param_ref_list b; 00332 00333 ref_list = NULL; 00334 b.list = NULL; 00335 qof_class_param_foreach (type, find_reference_param_cb, &b); 00336 ref_list = g_list_copy (b.list); 00337 return ref_list; 00338 }
|
|
Return true if the the indicated type is registered, else return FALSE. Definition at line 131 of file qofclass.c. 00132 { 00133 if (!obj_name) 00134 return FALSE; 00135 if (!check_init ()) 00136 return FALSE; 00137 00138 if (g_hash_table_lookup (classTable, obj_name)) 00139 return TRUE; 00140 00141 return FALSE; 00142 }
|
|
Call the callback once for each parameter on the indicated object class. The 'user_data' is passed back to the callback. Definition at line 263 of file qofclass.c. 00265 { 00266 struct parm_iterate qiter; 00267 GHashTable *param_ht; 00268 00269 if (!obj_name || !cb) 00270 return; 00271 if (!classTable) 00272 return; 00273 param_ht = g_hash_table_lookup (classTable, obj_name); 00274 if (!param_ht) 00275 return; 00276 00277 qiter.fcn = cb; 00278 qiter.data = user_data; 00279 00280 g_hash_table_foreach (param_ht, param_foreach_cb, &qiter); 00281 }
|
|
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 92 of file qofclass.c. 00094 { 00095 GHashTable *ht; 00096 int i; 00097 00098 if (!obj_name) 00099 return; 00100 if (!check_init ()) 00101 return; 00102 00103 if (default_sort_function) 00104 { 00105 g_hash_table_insert (sortTable, (gchar *) obj_name, 00106 default_sort_function); 00107 } 00108 00109 ht = g_hash_table_lookup (classTable, obj_name); 00110 00111 /* If it doesn't already exist, create a new table for this object */ 00112 if (!ht) 00113 { 00114 ht = g_hash_table_new (g_str_hash, g_str_equal); 00115 g_hash_table_insert (classTable, (gchar *) obj_name, ht); 00116 } 00117 00118 /* At least right now, we allow dummy, parameterless objects, 00119 * for testing purposes. Although I suppose that should be 00120 * an error.. */ 00121 /* Now insert all the parameters */ 00122 if (params) 00123 { 00124 for (i = 0; params[i].param_name; i++) 00125 g_hash_table_insert (ht, 00126 (char *) params[i].param_name, (gpointer) & (params[i])); 00127 } 00128 }
|