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

---

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.

Files
file	qofbackend.h
	API for data storage Backend.
Modules
	Session: Backend connections.
	QOF Serialisation Format
	qof-backend-gda outline
	QOF-backend-SQLite support
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. 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)
KvpFrame *	qof_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.
KvpFrame *	qof_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 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.
QofBackend *	qof_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.

---

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.

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

Backend configuration option foreach callback prototype.

Definition at line 134 of file qofbackend.h.

typedef struct QofBackendProvider_s QofBackendProvider

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

{
    g_return_val_if_fail (be, NULL);
    be->config_count = 0;
    return be->backend_configuration;
}

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

{
    if (!be)
        return NULL;
    if (!be->get_config)
        return NULL;
    return (be->get_config) (be);
}

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

{
    if (!be || !config)
        return;
    if (!be->load_config)
        return;
    (be->load_config) (be, config);
}

void qof_backend_option_foreach	(	KvpFrame *	config,
		QofBackendOptionCB	cb,
		gpointer	data
	)

Iterate over the frame and process each option.

Definition at line 383 of file qofbackend.c.

{
    struct config_iterate helper;

    if (!config || !cb)
        return;
    ENTER (" ");
    helper.fcn = cb;
    helper.count = 1;
    helper.data = data;
    helper.recursive = config;
    kvp_frame_for_each_slot (config, config_foreach_cb, &helper);
    LEAVE (" ");
}

void qof_backend_prepare_frame

(

QofBackend *

be

)

Initialise the backend_configuration

Definition at line 99 of file qofbackend.c.

{
    g_return_if_fail (be);
    if (!kvp_frame_is_empty (be->backend_configuration))
    {
        kvp_frame_delete (be->backend_configuration);
        be->backend_configuration = kvp_frame_new ();
    }
    be->config_count = 0;
}

void qof_backend_prepare_option	(	QofBackend *	be,
		QofBackendOption *	option
	)

Add an option to the backend_configuration. Repeat for more.

Definition at line 111 of file qofbackend.c.

{
    KvpValue *value;
    gchar *temp;
    gint count;

    g_return_if_fail (be || option);
    count = be->config_count;
    count++;
    value = NULL;
    switch (option->type)
    {
        case KVP_TYPE_GINT64:
        {
            value = kvp_value_new_gint64 (*(gint64 *) option->value);
            break;
        }
        case KVP_TYPE_DOUBLE:
        {
            value = kvp_value_new_double (*(gdouble *) option->value);
            break;
        }
        case KVP_TYPE_NUMERIC:
        {
            value = kvp_value_new_numeric (*(QofNumeric *) option->value);
            break;
        }
        case KVP_TYPE_STRING:
        {
            value = kvp_value_new_string ((const gchar *) option->value);
            break;
        }
        case KVP_TYPE_BOOLEAN:
        {
        break;
        }
        case KVP_TYPE_GUID:
        {
            break;
        }                       /* unsupported */
        case KVP_TYPE_TIME :
        {
            value = kvp_value_new_time ((QofTime*) option->value);
            break;
        }
#ifndef QOF_DISABLE_DEPRECATED
        case KVP_TYPE_TIMESPEC:
        {
            value = kvp_value_new_timespec (*(Timespec *) option->value);
            break;
        }
#endif
        case KVP_TYPE_BINARY:
        {
            break;
        }                       /* unsupported */
        case KVP_TYPE_GLIST:
        {
            break;
        }                       /* unsupported */
        case KVP_TYPE_FRAME:
        {
            break;
        }                       /* unsupported */
    }
    if (value)
    {
        temp = g_strdup_printf ("/%s", option->option_name);
        kvp_frame_set_value (be->backend_configuration, temp, value);
        g_free (temp);
        temp =
            g_strdup_printf ("/%s/%s", QOF_CONFIG_DESC,
            option->option_name);
        kvp_frame_set_string (be->backend_configuration, temp,
            option->description);
        g_free (temp);
        temp =
            g_strdup_printf ("/%s/%s", QOF_CONFIG_TIP,
            option->option_name);
        kvp_frame_set_string (be->backend_configuration, temp,
            option->tooltip);
        g_free (temp);
        /* only increment the counter if successful */
        be->config_count = count;
    }
}

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.

{
    if (!book)
        return;
    ENTER ("book=%p be=%p", book, be);
    book->backend = be;
    LEAVE (" ");
}

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

{
    gchar *fullpath;
    typedef void (*backend_init) (void);
    GModule *backend;
    backend_init gmod_init;
    gpointer g;

    g_return_val_if_fail (g_module_supported (), FALSE);
    fullpath = g_module_build_path (directory, filename);
    backend = g_module_open (fullpath, G_MODULE_BIND_LAZY);
    if (!backend)
    {
        PERR (" No backend found. %s", g_module_error ());
        return FALSE;
    }
    g = &gmod_init;
    if (!g_module_symbol (backend, init_fcn, g))
    {
        PERR (" Backend did not initialise. %s", g_module_error ());
        return FALSE;
    }
    g_module_make_resident (backend);
    gmod_init ();
    g_free (fullpath);
    return TRUE;
}

---