QOF: Object: Describing data structure.

QOF 0.7.5

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

Modules | Files | Data Structures | Macros | Typedefs | Functions
Object: Describing data structure.
Query Object Framework

## Modules
| Object_Private
| GLib GObjects

## Files
file | qofobject.h
| the Core Object Description Interface

## Data Structures
struct | _QofObject

## Macros
#define | QOF_OBJECT_VERSION 3
#define | QOF_MOD_OBJECT "qof-object"

## Typedefs
typedef struct _QofObject | QofObject
typedef void(* | QofForeachCB) (gpointer obj, gpointer user_data)
typedef void(* | QofForeachTypeCB) (QofObject *type, gpointer user_data)
typedef void(* | QofForeachBackendTypeCB) (QofIdTypeConst type, gpointer backend_data, gpointer user_data)

## Functions
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 gchar * | qof_object_get_type_label (QofIdTypeConst type_name)
const gchar * | 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 gchar *backend_name, gpointer be_data)
gpointer | qof_object_lookup_backend (QofIdTypeConst type_name, const gchar *backend_name)
void | qof_object_foreach_backend (const char *backend_name, QofForeachBackendTypeCB cb, gpointer user_data)

## Initialize the object registration subsystem
void | qof_object_initialize (void)
void | qof_object_shutdown (void)

## Detailed Description

QOF Objects provide the means for describing a QofEntity to allow a storage backend to load and write a QofBook. While an entity can be thought of as an identified instance of some thing, the QOF Object describes how that entity can be created, how to find other entities of the same type, whether the object can be cached in the backend and how to compare entities of the same type.

- QofObject describes how to relate one entity to another.
- QofClass describes how to get and set data within the entity.

To work with your own QOF Objects, you can use the QOF Generator to create sample objects and a mini-application with the SQL-type query interface. http://qof-gen.sourceforge.net/

## Macro Definition Documentation

#define QOF_OBJECT_VERSION 3

Defines the version of the core object object registration interface. Only object modules compiled against this version of the interface will load properly

Definition at line 57 of file qofobject.h.

## Function Documentation

void qof_object_foreach | ( | QofIdTypeConst | type_name,
|  | QofBook * | book,
|  | QofEntityForeachCB | cb,
|  | gpointer | user_data
| ) |  |

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 174 of file qofobject.c.

176 {
177 QofCollection *col;
178 const QofObject *obj;
179
180 if (!book || !type_name)
181 {
182 return;
183 }
184 PINFO ("type=%s", type_name);
185
186 obj = qof_object_lookup (type_name);
187 if (!obj)
188 {
189 PERR ("No object of type %s", type_name);
190 return;
191 }
192 col = qof_book_get_collection (book, obj->e_type);
193 if (!obj)
194 {
195 return;
196 }
197 if (obj->foreach)
198 {
199 obj->foreach (col, cb, user_data);
200 }
201 return;
202 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
PINFO
#define PINFO(format, args...)
Definition: qoflog.h:199
qof_book_get_collection
QofCollection * qof_book_get_collection(QofBook *book, QofIdType entity_type)
Definition: qofbook.c:220
qof_object_lookup
const QofObject * qof_object_lookup(QofIdTypeConst name)
Definition: qofobject.c:305
QofCollection
struct QofCollection_s QofCollection
Definition: qofid.h:138
_QofObject
Definition: qofobject.h:70
_QofObject::foreach
void(* foreach)(QofCollection *, QofEntityForeachCB, gpointer)
Definition: qofobject.h:105

void qof_object_foreach_type | ( | QofForeachTypeCB | cb,
|  | gpointer | user_data
| ) |  |

Invoke the callback 'cb' on every object class definition. The user_data pointer is passed back to the callback.

Definition at line 140 of file qofobject.c.

141 {
142 GList *l;
143
144 if (!cb)
145 return;
146
147 for (l = object_modules; l; l = l->next)
148 {
149 QofObject *obj = l->data;
150 (cb) (obj, user_data);
151 }
152 }
_QofObject
Definition: qofobject.h:70

const gchar* qof_object_get_type_label | ( | QofIdTypeConst | type_name | ) |

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 223 of file qofobject.c.

224 {
225 const QofObject *obj;
226
227 if (!type_name)
228 return NULL;
229
230 obj = qof_object_lookup (type_name);
231 if (!obj)
232 return NULL;
233
234 return (obj->type_label);
235 }
qof_object_lookup
const QofObject * qof_object_lookup(QofIdTypeConst name)
Definition: qofobject.c:305
_QofObject
Definition: qofobject.h:70

const QofObject* qof_object_lookup | ( | QofIdTypeConst | type_name | ) |

Lookup an object definition

Definition at line 305 of file qofobject.c.

306 {
307 GList *qiter;
308 const QofObject *obj;
309
310 g_return_val_if_fail (object_is_initialized, NULL);
311
312 if (!name)
313 return NULL;
314
315 for (qiter = object_modules; qiter; qiter = qiter->next)
316 {
317 obj = qiter->data;
318 if (!safe_strcmp (obj->e_type, name))
319 return obj;
320 }
321 return NULL;
322 }
_QofObject
Definition: qofobject.h:70
safe_strcmp
gint safe_strcmp(const gchar *da, const gchar *db)
Definition: qofutil.c:72

gpointer qof_object_new_instance | ( | QofIdTypeConst | type_name,
|  | QofBook * | book
| ) |  |

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.

43 {
44 const QofObject *obj;
45
46 if (!type_name)
47 return NULL;
48
49 obj = qof_object_lookup (type_name);
50 if (!obj)
51 return NULL;
52
53 if (obj->create)
54 return (obj->create (book));
55
56 return NULL;
57 }
qof_object_lookup
const QofObject * qof_object_lookup(QofIdTypeConst name)
Definition: qofobject.c:305
_QofObject::create
gpointer(* create)(QofBook *)
Definition: qofobject.h:80
_QofObject
Definition: qofobject.h:70

const gchar* qof_object_printable | ( | QofIdTypeConst | type_name,
|  | gpointer | instance
| ) |  |

Returns
  a Human-readable string name for an instance

Definition at line 205 of file qofobject.c.

206 {
207 const QofObject *b_obj;
208
209 if (!type_name || !obj)
210 return NULL;
211
212 b_obj = qof_object_lookup (type_name);
213 if (!b_obj)
214 return NULL;
215
216 if (b_obj->printable)
217 return (b_obj->printable (obj));
218
219 return NULL;
220 }
qof_object_lookup
const QofObject * qof_object_lookup(QofIdTypeConst name)
Definition: qofobject.c:305
_QofObject
Definition: qofobject.h:70
_QofObject::printable
const gchar *(* printable)(gpointer instance)
Definition: qofobject.h:109

gboolean qof_object_register | ( | const QofObject * | object | ) |

Register new types of object objects

Definition at line 278 of file qofobject.c.

279 {
280 g_return_val_if_fail (object_is_initialized, FALSE);
281
282 if (!object)
283 return FALSE;
284 g_return_val_if_fail (object->interface_version == QOF_OBJECT_VERSION,
285 FALSE);
286
287 if (g_list_index (object_modules, (gpointer) object) == -1)
288 object_modules =
289 g_list_prepend (object_modules, (gpointer) object);
290 else
291 return FALSE;
292
293 /* Now initialize all the known books */
294 if (object->book_begin && book_list)
295 {
296 GList *node;
297 for (node = book_list; node; node = node->next)
298 object->book_begin (node->data);
299 }
300
301 return TRUE;
302 }
QOF_OBJECT_VERSION
#define QOF_OBJECT_VERSION
Definition: qofobject.h:57

gboolean qof_object_register_backend | ( | QofIdTypeConst | type_name,
|  | const gchar * | backend_name,
|  | gpointer | be_data
| ) |  |

Register and lookup backend-specific data for this particular object

Definition at line 325 of file qofobject.c.

327 {
328 GHashTable *ht;
329 g_return_val_if_fail (object_is_initialized, FALSE);
330
331 if (!type_name || *type_name == '\0' ||
332 !backend_name || *backend_name == '\0' || !be_data)
333 return FALSE;
334
335 ht = g_hash_table_lookup (backend_data, backend_name);
336
337 /* If it doesn't already exist, create a new table for this backend */
338 if (!ht)
339 {
340 ht = g_hash_table_new (g_str_hash, g_str_equal);
341 g_hash_table_insert (backend_data, (gchar *) backend_name, ht);
342 }
343
344 /* Now insert the data */
345 g_hash_table_insert (ht, (gchar *) type_name, be_data);
346
347 return TRUE;
348 }