Files | |
file | qofbackend-p.h |
private api for data storage backend | |
file | qofobject-p.h |
the Core Object Registration/Lookup Private Interface | |
Modules | |
Object_Private | |
Backend | |
Book | |
Class | |
GLib GObjects | |
Objects | |
Data Structures | |
struct | QofBackendProvider_s |
struct | QofBackend_s |
struct | _QofBook |
struct | _QofParam |
Book_Private | |
#define | qof_book_set_guid(book, guid) qof_entity_set_guid(QOF_ENTITY(book), guid) |
void | qof_book_set_backend (QofBook *book, QofBackend *be) |
gboolean | qof_book_register (void) |
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_COLLECT "collection" |
Backend_Private | |
Pseudo-object defining how the engine can interact with different back-ends (which may be SQL databases, or network interfaces to remote QOF servers. File-io is just one type of backend).
The callbacks will be called at the appropriate times during a book session to allow the backend to store the data as needed. | |
void | qof_backend_register_provider (QofBackendProvider *) |
void | qof_backend_set_error (QofBackend *be, QofBackendError err) |
QofBackendError | qof_backend_get_error (QofBackend *be) |
void | qof_backend_set_message (QofBackend *be, const char *format,...) |
char * | qof_backend_get_message (QofBackend *be) |
void | qof_backend_init (QofBackend *be) |
gchar | qof_book_get_open_marker (QofBook *book) |
gint32 | qof_book_get_version (QofBook *book) |
guint32 | qof_book_get_idata (QofBook *book) |
void | qof_book_set_version (QofBook *book, gint32 version) |
void | qof_book_set_idata (QofBook *book, guint32 idata) |
Allow access to the begin routine for this backend. | |
QOF_BEGIN_EDIT and QOF_COMMIT_EDIT_PART1 and part2 rely on calling QofBackend *be->begin and be->commit. This means the QofBackend struct becomes part of the public API. These function replaces those calls to allow the macros to be used when QOF is built as a library. | |
void | qof_backend_run_begin (QofBackend *be, QofInstance *inst) |
gboolean | qof_backend_begin_exists (QofBackend *be) |
void | qof_backend_run_commit (QofBackend *be, QofInstance *inst) |
gboolean | qof_backend_commit_exists (QofBackend *be) |
Class_Private | |
void | qof_class_init (void) |
void | qof_class_shutdown (void) |
QofSortFunc | qof_class_get_default_sort (QofIdTypeConst obj_name) |
Entity_Private | |
void | qof_entity_set_guid (QofEntity *ent, const GUID *guid) |
void | qof_collection_insert_entity (QofCollection *, QofEntity *) |
void | qof_collection_mark_clean (QofCollection *) |
void | qof_collection_mark_dirty (QofCollection *) |
Objects_Private | |
void | qof_object_book_begin (QofBook *book) |
void | qof_object_book_end (QofBook *book) |
gboolean | qof_object_is_dirty (QofBook *book) |
void | qof_object_mark_clean (QofBook *book) |
gboolean | qof_object_compliance (QofIdTypeConst type_name, gboolean warn) |
check an object can be created and supports iteration | |
Initialize the object registration subsystem | |
void | qof_object_initialize (void) |
void | qof_object_shutdown (void) |
Typedefs | |
typedef const char * | QofType |
typedef _QofParam | QofParam |
typedef gpointer(* | QofAccessFunc )(gpointer object, const QofParam *param) |
typedef void(* | QofSetterFunc )(gpointer, gpointer) |
typedef int(* | 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 char *param_name) |
const QofParam * | qof_class_get_parameter (QofIdTypeConst obj_name, const char *parameter) |
QofAccessFunc | qof_class_get_parameter_getter (QofIdTypeConst obj_name, const char *parameter) |
QofSetterFunc | qof_class_get_parameter_setter (QofIdTypeConst obj_name, const char *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. | |
gboolean | qof_object_register (const QofObject *object) |
const QofObject * | qof_object_lookup (QofIdTypeConst type_name) |
gpointer | qof_object_new_instance (QofIdTypeConst type_name, QofBook *book) |
const char * | qof_object_get_type_label (QofIdTypeConst type_name) |
const char * | qof_object_printable (QofIdTypeConst type_name, gpointer instance) |
void | qof_object_foreach_type (QofForeachTypeCB cb, gpointer user_data) |
void | qof_object_foreach (QofIdTypeConst type_name, QofBook *book, QofEntityForeachCB cb, gpointer user_data) |
gboolean | qof_object_register_backend (QofIdTypeConst type_name, const char *backend_name, gpointer be_data) |
gpointer | qof_object_lookup_backend (QofIdTypeConst type_name, const char *backend_name) |
void | qof_object_foreach_backend (const char *backend_name, QofForeachBackendTypeCB cb, gpointer user_data) |
|
Definition at line 107 of file qofbook-p.h. |
|
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 241 of file qofclass.h. |
|
Type definition for the paramter callback function. Definition at line 249 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 181 of file qofclass.h. |
|
Type of Paramters (String, Date, Numeric, GUID, etc.) Definition at line 126 of file qofclass.h. |
|
The qof_backend_get_error() routine pops an error code off the error stack. Definition at line 57 of file qofbackend.c. 00058 { 00059 QofBackendError err; 00060 if (!be) return ERR_BACKEND_NO_BACKEND; 00061 00062 /* use 'stack-pop' semantics */ 00063 err = be->last_err; 00064 be->last_err = ERR_BACKEND_NO_ERR; 00065 return err; 00066 }
|
|
The qof_backend_get_message() pops the error message string from the Backend. This string should be freed with g_free(). Definition at line 92 of file qofbackend.c. 00093 { 00094 char * msg; 00095 00096 if (!be) return g_strdup("ERR_BACKEND_NO_BACKEND"); 00097 if (!be->error_msg) return NULL; 00098 00099 /* 00100 * Just return the contents of the error_msg and then set it to 00101 * NULL. This is necessary, because the Backends don't seem to 00102 * have a destroy_backend function to take care of freeing stuff 00103 * up. The calling function should free the copy. 00104 * Also, this is consistent with the qof_backend_get_error() popping. 00105 */ 00106 00107 msg = be->error_msg; 00108 be->error_msg = NULL; 00109 return msg; 00110 }
|
|
Let the sytem know about a new provider of backends. This function is typically called by the provider library at library load time. This function allows the backend library to tell the QOF infrastructure that it can handle URL's of a certain type. Note that a single backend library may register more than one provider, if it is capable of handling more than one URL access method. Definition at line 59 of file qofsession.c. 00060 { 00061 provider_list = g_slist_prepend (provider_list, prov); 00062 }
|
|
The qof_backend_set_error() routine pushes an error code onto the error stack. (FIXME: the stack is 1 deep in current implementation). Definition at line 47 of file qofbackend.c. 00048 { 00049 if (!be) return; 00050 00051 /* use stack-push semantics. Only the earliest error counts */ 00052 if (ERR_BACKEND_NO_ERR != be->last_err) return; 00053 be->last_err = err; 00054 }
|
|
The qof_backend_set_message() assigns a string to the backend error message. Definition at line 69 of file qofbackend.c. 00070 { 00071 va_list args; 00072 char * buffer; 00073 00074 if (!be) return; 00075 00076 /* If there's already something here, free it */ 00077 if (be->error_msg) g_free(be->error_msg); 00078 00079 if (!format) { 00080 be->error_msg = NULL; 00081 return; 00082 } 00083 00084 va_start(args, format); 00085 buffer = (char *)g_strdup_vprintf(format, args); 00086 va_end(args); 00087 00088 be->error_msg = buffer; 00089 }
|
|
get the book tag number used for kvp management in sql backends. Definition at line 296 of file qofbook.c. 00297 { 00298 if(!book) { return 0; } 00299 return book->idata; 00300 }
|
|
Allow backends to see if the book is open
Definition at line 284 of file qofbook.c. 00285 { 00286 if(!book) { return 'n'; } 00287 return book->book_open; 00288 }
|
|
get the book version used for tracking multiuser updates in backends.
Definition at line 290 of file qofbook.c. 00291 { 00292 if(!book) { return -1; } 00293 return book->version; 00294 }
|
|
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 217 of file qofclass.c. 00218 { 00219 struct class_iterate iter; 00220 00221 if (!cb) return; 00222 if (!classTable) return; 00223 00224 iter.fcn = cb; 00225 iter.data = user_data; 00226 00227 g_hash_table_foreach (classTable, class_foreach_cb, &iter); 00228 }
|
|
Return the registered Parameter Definition for the requested parameter Definition at line 135 of file qofclass.c. 00137 { 00138 GHashTable *ht; 00139 00140 g_return_val_if_fail (obj_name, NULL); 00141 g_return_val_if_fail (parameter, NULL); 00142 if (!check_init()) return NULL; 00143 00144 ht = g_hash_table_lookup (classTable, obj_name); 00145 if (!ht) 00146 { 00147 PWARN ("no object of type %s", obj_name); 00148 return NULL; 00149 } 00150 00151 return (g_hash_table_lookup (ht, parameter)); 00152 }
|
|
Return the object's parameter getter function Definition at line 155 of file qofclass.c. 00157 { 00158 const QofParam *prm; 00159 00160 g_return_val_if_fail (obj_name, NULL); 00161 g_return_val_if_fail (parameter, NULL); 00162 00163 prm = qof_class_get_parameter (obj_name, parameter); 00164 if (prm) 00165 return prm->param_getfcn; 00166 00167 return NULL; 00168 }
|
|
Return the object's parameter setter function Definition at line 171 of file qofclass.c. 00173 { 00174 const QofParam *prm; 00175 00176 g_return_val_if_fail (obj_name, NULL); 00177 g_return_val_if_fail (parameter, NULL); 00178 00179 prm = qof_class_get_parameter (obj_name, parameter); 00180 if (prm) 00181 return prm->param_setfcn; 00182 00183 return NULL; 00184 }
|
|
Return the core datatype of the specified object's parameter Definition at line 187 of file qofclass.c. 00189 { 00190 const QofParam *prm; 00191 00192 if (!obj_name || !param_name) return NULL; 00193 00194 prm = qof_class_get_parameter (obj_name, param_name); 00195 if (!prm) return NULL; 00196 00197 return (prm->param_type); 00198 }
|
|
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 292 of file qofclass.c. 00293 { 00294 GList *ref_list; 00295 struct param_ref_list b; 00296 00297 ref_list = NULL; 00298 b.list = NULL; 00299 qof_class_param_foreach(type, find_reference_param_cb, &b); 00300 ref_list = g_list_copy(b.list); 00301 return ref_list; 00302 }
|
|
Return true if the the indicated type is registered, else return FALSE. Definition at line 124 of file qofclass.c. 00125 { 00126 if (!obj_name) return FALSE; 00127 if (!check_init()) return FALSE; 00128 00129 if (g_hash_table_lookup (classTable, obj_name)) return TRUE; 00130 00131 return FALSE; 00132 }
|
|
Call the callback once for each parameter on the indicated object class. The 'user_data' is passed back to the callback. Definition at line 247 of file qofclass.c. 00249 { 00250 struct parm_iterate iter; 00251 GHashTable *param_ht; 00252 00253 if (!obj_name || !cb) return; 00254 if (!classTable) return; 00255 param_ht = g_hash_table_lookup (classTable, obj_name); 00256 if (!param_ht) return; 00257 00258 iter.fcn = cb; 00259 iter.data = user_data; 00260 00261 g_hash_table_foreach (param_ht, param_foreach_cb, &iter); 00262 }
|
|
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.c. 00089 { 00090 GHashTable *ht; 00091 int i; 00092 00093 if (!obj_name) return; 00094 if (!check_init()) return; 00095 00096 if (default_sort_function) 00097 { 00098 g_hash_table_insert (sortTable, (char *)obj_name, default_sort_function); 00099 } 00100 00101 ht = g_hash_table_lookup (classTable, obj_name); 00102 00103 /* If it doesn't already exist, create a new table for this object */ 00104 if (!ht) 00105 { 00106 ht = g_hash_table_new (g_str_hash, g_str_equal); 00107 g_hash_table_insert (classTable, (char *)obj_name, ht); 00108 } 00109 00110 /* At least right now, we allow dummy, parameterless objects, 00111 * for testing purposes. Although I suppose that should be 00112 * an error.. */ 00113 /* Now insert all the parameters */ 00114 if (params) 00115 { 00116 for (i = 0; params[i].param_name; i++) 00117 g_hash_table_insert (ht, 00118 (char *)params[i].param_name, 00119 (gpointer)&(params[i])); 00120 } 00121 }
|
|
Take entity, remove it from whatever collection its currently in, and place it in a new collection. To be used only for moving entity from one book to another. Definition at line 190 of file qofid.c. 00191 { 00192 if (!col || !ent) return; 00193 if (guid_equal(&ent->guid, guid_null())) return; 00194 g_return_if_fail (col->e_type == ent->e_type); 00195 qof_collection_remove_entity (ent); 00196 g_hash_table_insert (col->hash_of_entities, &ent->guid, ent); 00197 qof_collection_mark_dirty(col); 00198 ent->collection = col; 00199 }
|
|
reset value of dirty flag Definition at line 334 of file qofid.c. 00335 { 00336 if (col) { col->is_dirty = FALSE; } 00337 }
|
|
Set the ID of the entity, over-riding the previous ID. Very dangerous, use only for file i/o work. Definition at line 89 of file qofid.c. 00090 { 00091 QofCollection *col; 00092 if (guid_equal (guid, &ent->guid)) return; 00093 00094 col = ent->collection; 00095 qof_collection_remove_entity (ent); 00096 ent->guid = *guid; 00097 qof_collection_insert_entity (col, ent); 00098 }
|
|
To be called from within the book Definition at line 57 of file qofobject.c. 00058 { 00059 GList *l; 00060 00061 if (!book) return; 00062 ENTER (" "); 00063 for (l = object_modules; l; l = l->next) { 00064 QofObject *obj = l->data; 00065 if (obj->book_begin) 00066 obj->book_begin (book); 00067 } 00068 00069 /* Remember this book for later */ 00070 book_list = g_list_prepend (book_list, book); 00071 LEAVE (" "); 00072 }
|
|
check an object can be created and supports iteration
Definition at line 141 of file qofobject.c. 00142 { 00143 const QofObject *obj; 00144 00145 obj = qof_object_lookup(type_name); 00146 if((obj->create == NULL)||(obj->foreach == NULL)){ 00147 if(warn) 00148 { 00149 PINFO (" Object type %s is not fully QOF compliant", obj->e_type); 00150 } 00151 return FALSE; 00152 } 00153 return TRUE; 00154 }
|
|
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 158 of file qofobject.c. 00160 { 00161 QofCollection *col; 00162 const QofObject *obj; 00163 00164 if (!book || !type_name) { return; } 00165 PINFO ("type=%s", type_name); 00166 00167 obj = qof_object_lookup (type_name); 00168 if (!obj) 00169 { 00170 PERR ("No object of type %s", type_name); 00171 return; 00172 } 00173 col = qof_book_get_collection (book, obj->e_type); 00174 if (!obj) { return; } 00175 if (obj->foreach) 00176 { 00177 obj->foreach (col, cb, user_data); 00178 } 00179 return; 00180 }
|
|
Invoke the callback 'cb' on every object class definition. The user_data pointer is passed back to the callback. Definition at line 128 of file qofobject.c. 00129 { 00130 GList *l; 00131 00132 if (!cb) return; 00133 00134 for (l = object_modules; l; l = l->next) { 00135 QofObject *obj = l->data; 00136 (cb) (obj, user_data); 00137 } 00138 }
|
|
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 198 of file qofobject.c. 00199 { 00200 const QofObject *obj; 00201 00202 if (!type_name) return NULL; 00203 00204 obj = qof_object_lookup (type_name); 00205 if (!obj) return NULL; 00206 00207 return (obj->type_label); 00208 }
|
|
Lookup an object definition Definition at line 267 of file qofobject.c. 00268 { 00269 GList *iter; 00270 const QofObject *obj; 00271 00272 g_return_val_if_fail (object_is_initialized, NULL); 00273 00274 if (!name) return NULL; 00275 00276 for (iter = object_modules; iter; iter = iter->next) { 00277 obj = iter->data; 00278 if (!safe_strcmp (obj->e_type, name)) 00279 return obj; 00280 } 00281 return NULL; 00282 }
|
|
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 42 of file qofobject.c. 00043 { 00044 const QofObject *obj; 00045 00046 if (!type_name) return NULL; 00047 00048 obj = qof_object_lookup (type_name); 00049 if (!obj) return NULL; 00050 00051 if (obj->create) 00052 return (obj->create (book)); 00053 00054 return NULL; 00055 }
|
|
Definition at line 183 of file qofobject.c. 00184 { 00185 const QofObject *b_obj; 00186 00187 if (!type_name || !obj) return NULL; 00188 00189 b_obj = qof_object_lookup (type_name); 00190 if (!b_obj) return NULL; 00191 00192 if (b_obj->printable) 00193 return (b_obj->printable (obj)); 00194 00195 return NULL; 00196 }
|
|
Register new types of object objects Definition at line 245 of file qofobject.c. 00246 { 00247 g_return_val_if_fail (object_is_initialized, FALSE); 00248 00249 if (!object) return FALSE; 00250 g_return_val_if_fail (object->interface_version == QOF_OBJECT_VERSION, FALSE); 00251 00252 if (g_list_index (object_modules, (gpointer)object) == -1) 00253 object_modules = g_list_prepend (object_modules, (gpointer)object); 00254 else 00255 return FALSE; 00256 00257 /* Now initialize all the known books */ 00258 if (object->book_begin && book_list) { 00259 GList *node; 00260 for (node = book_list; node; node = node->next) 00261 object->book_begin (node->data); 00262 } 00263 00264 return TRUE; 00265 }
|
|
Register and lookup backend-specific data for this particular object Definition at line 284 of file qofobject.c. 00287 { 00288 GHashTable *ht; 00289 g_return_val_if_fail (object_is_initialized, FALSE); 00290 00291 if (!type_name || *type_name == '\0' || 00292 !backend_name || *backend_name == '\0' || 00293 !be_data) 00294 return FALSE; 00295 00296 ht = g_hash_table_lookup (backend_data, backend_name); 00297 00298 /* If it doesn't already exist, create a new table for this backend */ 00299 if (!ht) { 00300 ht = g_hash_table_new (g_str_hash, g_str_equal); 00301 g_hash_table_insert (backend_data, (char *)backend_name, ht); 00302 } 00303 00304 /* Now insert the data */ 00305 g_hash_table_insert (ht, (char *)type_name, be_data); 00306 00307 return TRUE; 00308 }
|