QOF  0.8.7
Modules | Files | Data Structures | Macros | Typedefs | Functions
Backends: Permanent storage for QOF entities.

Modules

 Session: Backend connections.
 
 QOF Serialisation Format
 
 QOF GDA backend outline
 
 QOF-backend-SQLite support
 

Files

file  qofbackend.h
 API for data storage Backend.
 

Data Structures

struct  QofBackendOption_s
 

Macros

#define QOF_MOD_BACKEND   "qof-backend"
 

Typedefs

typedef gint32 QofErrorId
 The ID of this error. More...
 
typedef struct QofBackendProvider_s QofBackendProvider
 
typedef struct QofBackend_s QofBackend
 Pseudo-object providing an interface between the framework and a persistant data store (e.g. a server, a database, or a file). More...
 
typedef void(* QofBePercentageFunc) (const gchar *message, double percent)
 DOCUMENT ME!
 

Functions

gboolean qof_load_backend_library (const gchar *directory, const gchar *filename, const gchar *init_fcn)
 Load a QOF-compatible backend shared library. More...
 
QofBackendqof_book_get_backend (QofBook *book)
 Retrieve the backend used by this book.
 
void qof_book_set_backend (QofBook *book, QofBackend *)
 Set the backend used by this book. More...
 

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)
 

Backend Configuration using KVP

The backend uses qof_backend_get_config to pass back a KvpFrame of QofBackendOption that includes the translated strings that serve as description and tooltip for that option.

qof_backend_prepare_frame, qof_backend_prepare_option and qof_backend_complete_frame are intended to be used by the backend itself to create the options.

qof_backend_get_config, qof_backend_option_foreach and qof_backend_load_config are intended for either the backend or the frontend to retrieve the option data from the frame or set new data.

Backends are loaded using QofBackendProvider via the function specified in prov->backend_new. Before backend_new returns, you should ensure that your backend is fully configured and ready for use.

typedef struct QofBackendOption_s QofBackendOption
 
typedef void(* QofBackendOptionCB) (QofBackendOption *, gpointer data)
 
void qof_backend_prepare_frame (QofBackend *be)
 
void qof_backend_prepare_option (QofBackend *be, QofBackendOption *option)
 
KvpFrameqof_backend_complete_frame (QofBackend *be)
 
void qof_backend_option_foreach (KvpFrame *config, QofBackendOptionCB cb, gpointer data)
 
void qof_backend_load_config (QofBackend *be, KvpFrame *config)
 Load configuration options specific to this backend. More...
 
KvpFrameqof_backend_get_config (QofBackend *be)
 Get the available configuration options. More...
 

Detailed Description

The QOF Backend is a pseudo-object providing an interface between the engine and a persistant data store (e.g. a server, a database, or a file). Backends are not meant to be used directly by an application; instead the Session should be used to make a connection with some particular backend. There are no backend functions that are 'public' to users of the engine. The backend can, however, report errors to the GUI & other front-end users. This file defines these errors.

Backends are used to save and restore Entities in a Book.

Typedef Documentation

typedef struct QofBackend_s QofBackend

Pseudo-object providing an interface between the framework and a persistant data store (e.g. a server, a database, or a file).

There are no backend functions that are 'public' to users of the framework. The backend can, however, report errors to the GUI & other front-end users.

Definition at line 69 of file qofbackend.h.

A single Backend Configuration Option.

typedef void(* QofBackendOptionCB) (QofBackendOption *, gpointer data)

Backend configuration option foreach callback prototype.

Definition at line 134 of file qofbackend.h.

A structure that declares backend services that can be gotten. The Provider specifies a URL access method, and specifies the function to create a backend that can handle that URL access function.

Definition at line 60 of file qofbackend.h.

typedef gint32 QofErrorId

The ID of this error.

0 == QOF_SUCCESS (equivalent to ERR_BACKEND_NO_ERR )

Definition at line 54 of file qofbackend.h.

Function Documentation

KvpFrame* qof_backend_complete_frame ( QofBackend be)

Complete the backend_configuration and return the frame.

Definition at line 183 of file qofbackend.c.

184 {
185  g_return_val_if_fail (be, NULL);
186  be->config_count = 0;
187  return be->backend_configuration;
188 }
KvpFrame* qof_backend_get_config ( QofBackend be)

Get the available configuration options.

To retrieve the options from the returned KvpFrame, the caller needs to parse the XML file that documents the option names and data types. The XML file itself is part of the backend and is installed in a directory determined by the backend. Therefore, loading a new backend requires two paths: the path to the .la file and the path to the xml. Both paths are available by including a generated header file, e.g. gncla-dir.h defines GNC_LIB_DIR for the location of the .la file and GNC_XML_DIR for the xml.

Parameters
beThe QofBackend to be configured.
Returns
A new KvpFrame containing the available options or NULL on failure.

Definition at line 376 of file qofbackend.c.

377 {
378  if (!be)
379  return NULL;
380  if (!be->get_config)
381  return NULL;
382  return (be->get_config) (be);
383 }
void qof_backend_load_config ( QofBackend be,
KvpFrame config 
)

Load configuration options specific to this backend.

Parameters
beThe backend to configure.
configA KvpFrame of QofBackendOptions that this backend will recognise. Each backend needs to document their own config types and acceptable values.

Definition at line 366 of file qofbackend.c.

367 {
368  if (!be || !config)
369  return;
370  if (!be->load_config)
371  return;
372  (be->load_config) (be, config);
373 }
void qof_backend_option_foreach ( KvpFrame config,
QofBackendOptionCB  cb,
gpointer  data 
)

Iterate over the frame and process each option.

Definition at line 349 of file qofbackend.c.

351 {
352  struct config_iterate helper;
353 
354  if (!config || !cb)
355  return;
356  ENTER (" ");
357  helper.fcn = cb;
358  helper.count = 1;
359  helper.data = data;
360  helper.recursive = config;
361  kvp_frame_for_each_slot (config, config_foreach_cb, &helper);
362  LEAVE (" ");
363 }
#define LEAVE(format, args...)
Definition: qoflog.h:227
void kvp_frame_for_each_slot(KvpFrame *f, KvpValueForeachCB proc, gpointer data)
Definition: kvpframe.c:1642
#define ENTER(format, args...)
Definition: qoflog.h:217
void qof_backend_prepare_frame ( QofBackend be)

Initialise the backend_configuration

Definition at line 89 of file qofbackend.c.

90 {
91  g_return_if_fail (be);
92  if (!kvp_frame_is_empty (be->backend_configuration))
93  {
94  kvp_frame_delete (be->backend_configuration);
95  be->backend_configuration = kvp_frame_new ();
96  }
97  be->config_count = 0;
98 }
gboolean kvp_frame_is_empty(KvpFrame *frame)
Definition: kvpframe.c:134
void kvp_frame_delete(KvpFrame *frame)
Definition: kvpframe.c:115
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:97
void qof_backend_prepare_option ( QofBackend be,
QofBackendOption option 
)

Add an option to the backend_configuration. Repeat for more.

Definition at line 101 of file qofbackend.c.

103 {
104  KvpValue *value;
105  gchar *temp;
106  gint count;
107 
108  g_return_if_fail (be || option);
109  count = be->config_count;
110  count++;
111  value = NULL;
112  switch (option->type)
113  {
114  case KVP_TYPE_GINT64:
115  {
116  value = kvp_value_new_gint64 (*(gint64 *) option->value);
117  break;
118  }
119  case KVP_TYPE_DOUBLE:
120  {
121  value = kvp_value_new_double (*(gdouble *) option->value);
122  break;
123  }
124  case KVP_TYPE_NUMERIC:
125  {
126  value = kvp_value_new_numeric (*(QofNumeric *) option->value);
127  break;
128  }
129  case KVP_TYPE_STRING:
130  {
131  value = kvp_value_new_string ((const gchar *) option->value);
132  break;
133  }
134  case KVP_TYPE_BOOLEAN:
135  {
136  break;
137  }
138  case KVP_TYPE_GUID:
139  {
140  break;
141  } /* unsupported */
142  case KVP_TYPE_TIME :
143  {
144  value = kvp_value_new_time ((QofTime*) option->value);
145  break;
146  }
147  case KVP_TYPE_BINARY:
148  {
149  break;
150  } /* unsupported */
151  case KVP_TYPE_GLIST:
152  {
153  break;
154  } /* unsupported */
155  case KVP_TYPE_FRAME:
156  {
157  break;
158  } /* unsupported */
159  }
160  if (value)
161  {
162  temp = g_strdup_printf ("/%s", option->option_name);
163  kvp_frame_set_value (be->backend_configuration, temp, value);
164  g_free (temp);
165  temp =
166  g_strdup_printf ("/%s/%s", QOF_CONFIG_DESC,
167  option->option_name);
168  kvp_frame_set_string (be->backend_configuration, temp,
169  option->description);
170  g_free (temp);
171  temp =
172  g_strdup_printf ("/%s/%s", QOF_CONFIG_TIP,
173  option->option_name);
174  kvp_frame_set_string (be->backend_configuration, temp,
175  option->tooltip);
176  g_free (temp);
177  /* only increment the counter if successful */
178  be->config_count = count;
179  }
180 }
Unique identifier.
Definition: kvpframe.h:118
const gchar * description
Definition: qofbackend.h:119
KvpFrame * kvp_frame_set_value(KvpFrame *frame, const gchar *key_path, const KvpValue *value)
Copy the KvpValue into the frame.
Definition: kvpframe.c:496
128bit denominator/numerator maths.
Definition: kvpframe.h:106
struct _KvpValue KvpValue
Definition: kvpframe.h:78
64bit integer
Definition: kvpframe.h:94
const gchar * option_name
Definition: qofbackend.h:118
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:112
Simple boolean type.
Definition: kvpframe.h:136
const gchar * tooltip
Definition: qofbackend.h:120
standard C string
Definition: kvpframe.h:112
standard C double type
Definition: kvpframe.h:100
KvpValueType type
Definition: qofbackend.h:116
void kvp_frame_set_string(KvpFrame *frame, const gchar *path, const gchar *str)
Store a copy of the string at the indicated path.
Definition: kvpframe.c:439
64bit time/date handling.
Definition: kvpframe.h:124
void qof_book_set_backend ( QofBook book,
QofBackend  
)

Set the backend used by this book.

Should only be used within a backend itself.

Definition at line 170 of file qofbook.c.

171 {
172  if (!book)
173  return;
174  ENTER ("book=%p be=%p", book, be);
175  book->backend = be;
176  LEAVE (" ");
177 }
#define LEAVE(format, args...)
Definition: qoflog.h:227
QofBackend * backend
Definition: qofbook-p.h:87
#define ENTER(format, args...)
Definition: qoflog.h:217
gboolean qof_load_backend_library ( const gchar *  directory,
const gchar *  filename,
const gchar *  init_fcn 
)

Load a QOF-compatible backend shared library.

Parameters
directoryCan be NULL if filename is a complete path.
filenameName of the .la file that describes the shared library. This provides platform independence, courtesy of libtool.
init_fcnThe QofBackendProvider init function.
Returns
FALSE in case or error, otherwise TRUE.

Definition at line 397 of file qofbackend.c.

399 {
400  gchar *fullpath;
401  typedef void (*backend_init) (void);
402  GModule *backend;
403  backend_init gmod_init;
404  gpointer g;
405 
406  g_return_val_if_fail (g_module_supported (), FALSE);
407  fullpath = g_module_build_path (directory, filename);
408  backend = g_module_open (fullpath, G_MODULE_BIND_LAZY);
409  if (!backend)
410  {
411  PERR (" No backend found. %s", g_module_error ());
412  return FALSE;
413  }
414  g = &gmod_init;
415  if (!g_module_symbol (backend, init_fcn, g))
416  {
417  PERR (" Backend did not initialise. %s", g_module_error ());
418  return FALSE;
419  }
420  g_module_make_resident (backend);
421  gmod_init ();
422  g_free (fullpath);
423  return TRUE;
424 }
#define PERR(format, args...)
Definition: qoflog.h:183