qofbackend.h File Reference


Detailed Description

API for data storage Backend.

Author:
Copyright (C) 2000-2001 Linas Vepstas <linas@linas.org>

Copyright 2004-2005 Neil Williams <linux@codehelp.co.uk>

Definition in file qofbackend.h.

#include "qofinstance.h"

Go to the source code of this file.

Data Structures

struct  QofBackendOption_s

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. i.e. backends need to run gettext in the init function.

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 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)

Defines

#define QOF_MOD_BACKEND   "qof-backend"

Typedefs

typedef QofBackendProvider_s QofBackendProvider
typedef QofBackend_s QofBackend
 Pseudo-object providing an interface between the engine and a persistant data store (e.g. a server, a database, or a file).
typedef void(* QofBePercentageFunc )(const char *message, double percent)
 DOCUMENT ME!

Enumerations

enum  QofBackendError {
  ERR_BACKEND_NO_ERR = 0, ERR_BACKEND_NO_HANDLER, ERR_BACKEND_NO_BACKEND, ERR_BACKEND_BAD_URL,
  ERR_BACKEND_NO_SUCH_DB, ERR_BACKEND_CANT_CONNECT, ERR_BACKEND_CONN_LOST, ERR_BACKEND_LOCKED,
  ERR_BACKEND_READONLY, ERR_BACKEND_TOO_NEW, ERR_BACKEND_DATA_CORRUPT, ERR_BACKEND_SERVER_ERR,
  ERR_BACKEND_ALLOC, ERR_BACKEND_PERM, ERR_BACKEND_MODIFIED, ERR_BACKEND_MOD_DESTROY,
  ERR_BACKEND_MISC, ERR_QSF_INVALID_OBJ, ERR_QSF_INVALID_MAP, ERR_QSF_BAD_OBJ_GUID,
  ERR_QSF_BAD_QOF_VERSION, ERR_QSF_BAD_MAP, ERR_QSF_NO_MAP, ERR_QSF_WRONG_MAP,
  ERR_QSF_MAP_NOT_OBJ, ERR_QSF_OVERFLOW, ERR_QSF_OPEN_NOT_MERGE, ERR_FILEIO_FILE_BAD_READ = 1000,
  ERR_FILEIO_FILE_EMPTY, ERR_FILEIO_FILE_LOCKERR, ERR_FILEIO_FILE_NOT_FOUND, ERR_FILEIO_FILE_TOO_OLD,
  ERR_FILEIO_UNKNOWN_FILE_TYPE, ERR_FILEIO_PARSE_ERROR, ERR_FILEIO_BACKUP_ERROR, ERR_FILEIO_WRITE_ERROR,
  ERR_FILEIO_READ_ERROR, ERR_FILEIO_NO_ENCODING, ERR_NETIO_SHORT_READ = 2000, ERR_NETIO_WRONG_CONTENT_TYPE,
  ERR_NETIO_NOT_GNCXML, ERR_SQL_MISSING_DATA = 3000, ERR_SQL_DB_TOO_OLD, ERR_SQL_DB_BUSY,
  ERR_RPC_HOST_UNK = 4000, ERR_RPC_CANT_BIND, ERR_RPC_CANT_ACCEPT, ERR_RPC_NO_CONNECTION,
  ERR_RPC_BAD_VERSION, ERR_RPC_FAILED, ERR_RPC_NOT_ADDED
}
 The errors that can be reported to the GUI & other front-end users. More...

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 *)


Typedef Documentation

typedef struct QofBackendOption_s QofBackendOption
 

A single Backend Configuration Option.

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

Backend configuration option foreach callback prototype.

Definition at line 219 of file qofbackend.h.


Function Documentation

KvpFrame* qof_backend_complete_frame QofBackend be  ) 
 

Complete the backend_configuration and return the frame.

Definition at line 235 of file qofbackend.c.

00236 {
00237         g_return_val_if_fail(be, NULL);
00238         be->config_count = 0;
00239         return be->backend_configuration;
00240 }

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 372 of file qofbackend.c.

00373 {
00374         if(!be) { return NULL; }
00375         if(!be->get_config) { return NULL; }
00376         return (be->get_config) (be);
00377 }

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 364 of file qofbackend.c.

00365 {
00366         if(!be || !config) { return; }
00367         if(!be->load_config) { return; }
00368         (be->load_config) (be, config);
00369 }

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.

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

void qof_backend_prepare_frame QofBackend be  ) 
 

Initialise the backend_configuration

Definition at line 173 of file qofbackend.c.

00174 {
00175         g_return_if_fail(be);
00176         if(!kvp_frame_is_empty(be->backend_configuration)) {
00177                 kvp_frame_delete(be->backend_configuration);
00178                 be->backend_configuration = kvp_frame_new();
00179         }
00180         be->config_count = 0;
00181 }

void qof_backend_prepare_option QofBackend be,
QofBackendOption option
 

Add an option to the backend_configuration. Repeat for more.

Definition at line 183 of file qofbackend.c.

00184 {
00185         KvpValue *value;
00186         gchar *temp;
00187         gint count;
00188 
00189         g_return_if_fail(be || option);
00190         count = be->config_count;
00191         count++;
00192         value = NULL;
00193         switch (option->type)
00194         {
00195                 case KVP_TYPE_GINT64   : {
00196                         value = kvp_value_new_gint64(*(gint64*)option->value);
00197                         break; 
00198                 }
00199                 case KVP_TYPE_DOUBLE   : { 
00200                         value = kvp_value_new_double(*(double*)option->value);
00201                         break; 
00202                 }
00203                 case KVP_TYPE_NUMERIC  : {
00204                         value = kvp_value_new_numeric(*(gnc_numeric*)option->value);
00205                         break; 
00206                 }
00207                 case KVP_TYPE_STRING   : {
00208                         value = kvp_value_new_string((const char*)option->value);
00209                         break;
00210                 }
00211                 case KVP_TYPE_GUID     : { break; } /* unsupported */
00212                 case KVP_TYPE_TIMESPEC : {
00213                         value = kvp_value_new_timespec(*(Timespec*)option->value);
00214                         break;
00215                 }
00216                 case KVP_TYPE_BINARY   : { break; } /* unsupported */
00217                 case KVP_TYPE_GLIST    : { break; } /* unsupported */
00218                 case KVP_TYPE_FRAME    : { break; } /* unsupported */
00219         }
00220         if(value) {
00221                 temp = g_strdup_printf("/%s", option->option_name);
00222                 kvp_frame_set_value(be->backend_configuration, temp, value);
00223                 g_free(temp);
00224                 temp = g_strdup_printf("/%s/%s", QOF_CONFIG_DESC, option->option_name);
00225                 kvp_frame_set_string(be->backend_configuration, temp, option->description);
00226                 g_free(temp);
00227                 temp = g_strdup_printf("/%s/%s", QOF_CONFIG_TIP, option->option_name);
00228                 kvp_frame_set_string(be->backend_configuration, temp, option->tooltip);
00229                 g_free(temp);
00230                 /* only increment the counter if successful */
00231                 be->config_count = count;
00232         }
00233 }

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.


Generated on Fri May 12 17:57:21 2006 for QOF by  doxygen 1.4.4