Data Structures | |
struct | _QofParam |
Modules | |
GUID | |
Entity | |
Instance | |
Files | |
file | qofclass.h |
API for registering paramters on objects. | |
Defines | |
#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. | |
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. | |
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" |
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. |
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.
#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.
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 121 of file qofclass.h.
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 144 of file qofclass.h.
typedef void(* QofClassForeachCB)(QofIdTypeConst, gpointer) |
Type definition for the class callback function.
Definition at line 251 of file qofclass.h.
typedef void(* QofParamForeachCB)(QofParam *, gpointer user_data) |
Type definition for the paramter callback function.
Definition at line 260 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 151 of file qofclass.h.
typedef gint(* QofSortFunc)(gconstpointer, gconstpointer) |
This function is the default sort function for a particular object type
Definition at line 181 of file qofclass.h.
typedef const gchar* QofType |
Type of Paramters (String, Date, Numeric, GUID, etc.)
Definition at line 125 of file qofclass.h.
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 234 of file qofclass.c.
00235 { 00236 struct class_iterate qiter; 00237 00238 if (!cb) 00239 return; 00240 if (!classTable) 00241 return; 00242 00243 qiter.fcn = cb; 00244 qiter.data = user_data; 00245 00246 g_hash_table_foreach (classTable, class_foreach_cb, &qiter); 00247 }
const QofParam* qof_class_get_parameter | ( | QofIdTypeConst | obj_name, | |
const gchar * | parameter | |||
) |
Return the registered Parameter Definition for the requested parameter
Definition at line 147 of file qofclass.c.
00148 { 00149 GHashTable *ht; 00150 00151 g_return_val_if_fail (obj_name, NULL); 00152 g_return_val_if_fail (parameter, NULL); 00153 if (!check_init ()) 00154 return NULL; 00155 00156 ht = g_hash_table_lookup (classTable, obj_name); 00157 if (!ht) 00158 { 00159 PWARN ("no object of type %s", obj_name); 00160 return NULL; 00161 } 00162 00163 return (g_hash_table_lookup (ht, parameter)); 00164 }
QofAccessFunc qof_class_get_parameter_getter | ( | QofIdTypeConst | obj_name, | |
const gchar * | parameter | |||
) |
Return the object's parameter getter function
Definition at line 167 of file qofclass.c.
00169 { 00170 const QofParam *prm; 00171 00172 g_return_val_if_fail (obj_name, NULL); 00173 g_return_val_if_fail (parameter, NULL); 00174 00175 prm = qof_class_get_parameter (obj_name, parameter); 00176 if (prm) 00177 return prm->param_getfcn; 00178 00179 return NULL; 00180 }
QofSetterFunc qof_class_get_parameter_setter | ( | QofIdTypeConst | obj_name, | |
const gchar * | parameter | |||
) |
Return the object's parameter setter function
Definition at line 183 of file qofclass.c.
00185 { 00186 const QofParam *prm; 00187 00188 g_return_val_if_fail (obj_name, NULL); 00189 g_return_val_if_fail (parameter, NULL); 00190 00191 prm = qof_class_get_parameter (obj_name, parameter); 00192 if (prm) 00193 return prm->param_setfcn; 00194 00195 return NULL; 00196 }
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 199 of file qofclass.c.
00201 { 00202 const QofParam *prm; 00203 00204 if (!obj_name || !param_name) 00205 return NULL; 00206 00207 prm = qof_class_get_parameter (obj_name, param_name); 00208 if (!prm) 00209 return NULL; 00210 00211 return (prm->param_type); 00212 }
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 329 of file qofclass.c.
00330 { 00331 GList *ref_list; 00332 struct param_ref_list b; 00333 00334 ref_list = NULL; 00335 b.list = NULL; 00336 qof_class_param_foreach (type, find_reference_param_cb, &b); 00337 ref_list = g_list_copy (b.list); 00338 return ref_list; 00339 }
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);
Definition at line 133 of file qofclass.c.
00134 { 00135 if (!obj_name) 00136 return FALSE; 00137 if (!check_init ()) 00138 return FALSE; 00139 00140 if (g_hash_table_lookup (classTable, obj_name)) 00141 return TRUE; 00142 00143 return FALSE; 00144 }
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 268 of file qofclass.c.
00270 { 00271 struct parm_iterate qiter; 00272 GHashTable *param_ht; 00273 00274 if (!obj_name || !cb) 00275 return; 00276 if (!classTable) 00277 return; 00278 param_ht = g_hash_table_lookup (classTable, obj_name); 00279 if (!param_ht) 00280 return; 00281 00282 qiter.fcn = cb; 00283 qiter.data = user_data; 00284 00285 g_hash_table_foreach (param_ht, param_foreach_cb, &qiter); 00286 }
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 94 of file qofclass.c.
00096 { 00097 GHashTable *ht; 00098 int i; 00099 00100 if (!obj_name) 00101 return; 00102 if (!check_init ()) 00103 return; 00104 00105 if (default_sort_function) 00106 { 00107 g_hash_table_insert (sortTable, (gchar *) obj_name, 00108 default_sort_function); 00109 } 00110 00111 ht = g_hash_table_lookup (classTable, obj_name); 00112 00113 /* If it doesn't already exist, create a new table for this object */ 00114 if (!ht) 00115 { 00116 ht = g_hash_table_new (g_str_hash, g_str_equal); 00117 g_hash_table_insert (classTable, (gchar *) obj_name, ht); 00118 } 00119 00120 /* At least right now, we allow dummy, parameterless objects, 00121 * for testing purposes. Although I suppose that should be 00122 * an error.. */ 00123 /* Now insert all the parameters */ 00124 if (params) 00125 { 00126 for (i = 0; params[i].param_name; i++) 00127 g_hash_table_insert (ht, 00128 (char *) params[i].param_name, (gpointer) & (params[i])); 00129 } 00130 }