Backends: Permanent storage for QOF entities.
[Query Object Framework]


Data Structures

struct  QofBackendOption_s

Modules

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

Files

file  qofbackend.h
 API for data storage Backend.

Defines

#define QOF_MOD_BACKEND   "qof-backend"

Typedefs

typedef gint32 QofErrorId
 The ID of this error.
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).
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.
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.

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.
KvpFrameqof_backend_get_config (QofBackend *be)
 Get the available configuration options.

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)

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.

00184 {
00185     g_return_val_if_fail (be, NULL);
00186     be->config_count = 0;
00187     return be->backend_configuration;
00188 }

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:
be The QofBackend to be configured.
Returns:
A new KvpFrame containing the available options or NULL on failure.

Definition at line 376 of file qofbackend.c.

00377 {
00378     if (!be)
00379         return NULL;
00380     if (!be->get_config)
00381         return NULL;
00382     return (be->get_config) (be);
00383 }

void qof_backend_load_config ( QofBackend be,
KvpFrame config 
)

Load configuration options specific to this backend.

Parameters:
be The backend to configure.
config A 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.

00367 {
00368     if (!be || !config)
00369         return;
00370     if (!be->load_config)
00371         return;
00372     (be->load_config) (be, config);
00373 }

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.

00351 {
00352     struct config_iterate helper;
00353 
00354     if (!config || !cb)
00355         return;
00356     ENTER (" ");
00357     helper.fcn = cb;
00358     helper.count = 1;
00359     helper.data = data;
00360     helper.recursive = config;
00361     kvp_frame_for_each_slot (config, config_foreach_cb, &helper);
00362     LEAVE (" ");
00363 }

void qof_backend_prepare_frame ( QofBackend be  ) 

Initialise the backend_configuration

Definition at line 89 of file qofbackend.c.

00090 {
00091     g_return_if_fail (be);
00092     if (!kvp_frame_is_empty (be->backend_configuration))
00093     {
00094         kvp_frame_delete (be->backend_configuration);
00095         be->backend_configuration = kvp_frame_new ();
00096     }
00097     be->config_count = 0;
00098 }

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.

00103 {
00104     KvpValue *value;
00105     gchar *temp;
00106     gint count;
00107 
00108     g_return_if_fail (be || option);
00109     count = be->config_count;
00110     count++;
00111     value = NULL;
00112     switch (option->type)
00113     {
00114         case KVP_TYPE_GINT64:
00115         {
00116             value = kvp_value_new_gint64 (*(gint64 *) option->value);
00117             break;
00118         }
00119         case KVP_TYPE_DOUBLE:
00120         {
00121             value = kvp_value_new_double (*(gdouble *) option->value);
00122             break;
00123         }
00124         case KVP_TYPE_NUMERIC:
00125         {
00126             value = kvp_value_new_numeric (*(QofNumeric *) option->value);
00127             break;
00128         }
00129         case KVP_TYPE_STRING:
00130         {
00131             value = kvp_value_new_string ((const gchar *) option->value);
00132             break;
00133         }
00134         case KVP_TYPE_BOOLEAN:
00135         {
00136         break;
00137         }
00138         case KVP_TYPE_GUID:
00139         {
00140             break;
00141         }                       /* unsupported */
00142         case KVP_TYPE_TIME :
00143         {
00144             value = kvp_value_new_time ((QofTime*) option->value);
00145             break;
00146         }
00147         case KVP_TYPE_BINARY:
00148         {
00149             break;
00150         }                       /* unsupported */
00151         case KVP_TYPE_GLIST:
00152         {
00153             break;
00154         }                       /* unsupported */
00155         case KVP_TYPE_FRAME:
00156         {
00157             break;
00158         }                       /* unsupported */
00159     }
00160     if (value)
00161     {
00162         temp = g_strdup_printf ("/%s", option->option_name);
00163         kvp_frame_set_value (be->backend_configuration, temp, value);
00164         g_free (temp);
00165         temp =
00166             g_strdup_printf ("/%s/%s", QOF_CONFIG_DESC,
00167             option->option_name);
00168         kvp_frame_set_string (be->backend_configuration, temp,
00169             option->description);
00170         g_free (temp);
00171         temp =
00172             g_strdup_printf ("/%s/%s", QOF_CONFIG_TIP,
00173             option->option_name);
00174         kvp_frame_set_string (be->backend_configuration, temp,
00175             option->tooltip);
00176         g_free (temp);
00177         /* only increment the counter if successful */
00178         be->config_count = count;
00179     }
00180 }

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.

00171 {
00172     if (!book)
00173         return;
00174     ENTER ("book=%p be=%p", book, be);
00175     book->backend = be;
00176     LEAVE (" ");
00177 }

gboolean qof_load_backend_library ( const gchar *  directory,
const gchar *  filename,
const gchar *  init_fcn 
)

Load a QOF-compatible backend shared library.

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

Definition at line 397 of file qofbackend.c.

00399 {
00400     gchar *fullpath;
00401     typedef void (*backend_init) (void);
00402     GModule *backend;
00403     backend_init gmod_init;
00404     gpointer g;
00405 
00406     g_return_val_if_fail (g_module_supported (), FALSE);
00407     fullpath = g_module_build_path (directory, filename);
00408     backend = g_module_open (fullpath, G_MODULE_BIND_LAZY);
00409     if (!backend)
00410     {
00411         PERR (" No backend found. %s", g_module_error ());
00412         return FALSE;
00413     }
00414     g = &gmod_init;
00415     if (!g_module_symbol (backend, init_fcn, g))
00416     {
00417         PERR (" Backend did not initialise. %s", g_module_error ());
00418         return FALSE;
00419     }
00420     g_module_make_resident (backend);
00421     gmod_init ();
00422     g_free (fullpath);
00423     return TRUE;
00424 }


Generated on Sat Aug 15 15:46:32 2009 for QOF by  doxygen 1.5.9