QOF: Backends: Permanent storage for QOF entities.

QOF 0.7.5

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

## Modules
| Session: Backend connections.
| QOF Serialisation Format
| qof-backend-gda outline
| QOF-backend-SQLite support

## Files
file | qofbackend.h
| API for data storage Backend.
file | qof-backend-qsf.h
| QSF API - Backend, maps, objects and configuration.
file | qof-sqlite.h
| Public interface of qof-backend-sqlite.

## 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...
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. More...
void | qsf_provider_init (void)
| Describe this backend to the application. More...
void | qof_sqlite_provider_init (void)
| Initialises the SQLite backend. 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)
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. More...
KvpFrame * | qof_backend_get_config (QofBackend *be)
| Get the available configuration options. More...

## Supported backend configurations
#define | QSF_COMPRESS "compression_level"
| compression level More...
#define | QSF_MAP_FILES "selected_map_files"
| selected QSF maps More...
#define | QSF_ENCODING "encoding_string"
| Encoding string. More...
#define | QSF_DATE_CONVERT "convert_date_to_time"
| Convert QOF_TYPE_DATE to QOF_TYPE_TIME. 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.

## Macro Definition Documentation

## ◆ QSF_COMPRESS

#define QSF_COMPRESS "compression_level"

compression level

Type: gint64 (KVP_TYPE_GINT64)

Pass a pointer to an integer value between 0 and 9.

Definition at line 177 of file qof-backend-qsf.h.

## ◆ QSF_DATE_CONVERT

#define QSF_DATE_CONVERT "convert_date_to_time"

Convert QOF_TYPE_DATE to QOF_TYPE_TIME.

QOF_TYPE_DATE is deprecated and some files will need conversion. Applications can set this option so that if a QOF_TYPE_DATE field (<date>) is encountered, a QOF_TYPE_TIME field (<time>) will be passed to the application and written out when the file is saved.

Applications that support the new QOF time format need to enable this option to prevent data loss when loading older files. It is safe to leave the option enabled, whether or not the file contains any date fields.

Applications that still use date must not set this option until time values are supported.

Although this could be passed to the user to specify, most applications should set this option at start-up and without user intervention.

Type: gint64 (KVP_TYPE_GINT64)

Pass a pointer to a non-zero integer value to enable.

Zero by default. Ignored if QOF was built with deprecated code disabled.

Definition at line 228 of file qof-backend-qsf.h.

## ◆ QSF_ENCODING

#define QSF_ENCODING "encoding_string"

Encoding string.

Defaults of UTF-8.

Definition at line 199 of file qof-backend-qsf.h.

## ◆ QSF_MAP_FILES

#define QSF_MAP_FILES "selected_map_files"

selected QSF maps

Type: GList* (KVP_TYPE_GLIST) of const char* (QOF_TYPE_STRING) values.

Defaults to the pre-installed QSF map(s) but may be overridden by the application to pass full path(s) of user selected QSF map file(s).

If you override the list, it is advisable to only specify the single map file for this QSF object to reduce the amount of error checking required within the backend. Simply reset the QofBackendOption before another file is to be opened. It is up to the application to decide how to offer multiple map selections to the user.

Definition at line 194 of file qof-backend-qsf.h.

## Typedef Documentation

## ◆ QofBackend

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.

## ◆ QofBackendOption

typedef struct QofBackendOption_s QofBackendOption

A single Backend Configuration Option.

## ◆ QofBackendOptionCB

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

Backend configuration option foreach callback prototype.

Definition at line 134 of file qofbackend.h.

## ◆ QofBackendProvider

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.

## ◆ QofErrorId

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

## ◆ qof_backend_complete_frame()

KvpFrame* qof_backend_complete_frame | ( | QofBackend * | be | ) |

Complete the backend_configuration and return the frame.

Definition at line 200 of file qofbackend.c.

201 {
202 g_return_val_if_fail (be, NULL);
203 be->config_count = 0;
204 return be->backend_configuration;
205 }

## ◆ qof_backend_get_config()

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.

411 {
412 if (!be)
413 return NULL;
414 if (!be->get_config)
415 return NULL;
416 return (be->get_config) (be);
417 }

## ◆ qof_backend_load_config()

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.

401 {
402 if (!be || !config)
403 return;
404 if (!be->load_config)
405 return;
406 (be->load_config) (be, config);
407 }

## ◆ qof_backend_option_foreach()

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.

385 {
386 struct config_iterate helper;
387
388 if (!config || !cb)
389 return;
390 ENTER (" ");
391 helper.fcn = cb;
392 helper.count = 1;
393 helper.data = data;
394 helper.recursive = config;
395 kvp_frame_for_each_slot (config, config_foreach_cb, &helper);
396 LEAVE (" ");
397 }
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
kvp_frame_for_each_slot
void kvp_frame_for_each_slot(KvpFrame *f, KvpValueForeachCB proc, gpointer data)
Definition: kvpframe.c:1650
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qof_backend_prepare_frame()

void qof_backend_prepare_frame | ( | QofBackend * | be | ) |

Initialise the backend_configuration

Definition at line 99 of file qofbackend.c.

100 {
101 g_return_if_fail (be);
102 if (!kvp_frame_is_empty (be->backend_configuration))
103 {
104 kvp_frame_delete (be->backend_configuration);
105 be->backend_configuration = kvp_frame_new ();
106 }
107 be->config_count = 0;
108 }
kvp_frame_is_empty
gboolean kvp_frame_is_empty(KvpFrame *frame)
Definition: kvpframe.c:137
kvp_frame_delete
void kvp_frame_delete(KvpFrame *frame)
Definition: kvpframe.c:118
kvp_frame_new
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:100

## ◆ qof_backend_prepare_option()

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.

113 {
114 KvpValue *value;
115 gchar *temp;
116 gint count;
117
118 g_return_if_fail (be || option);
119 count = be->config_count;
120 count++;
121 value = NULL;
122 switch (option->type)
123 {
124 case KVP_TYPE_GINT64:
125 {
126 value = kvp_value_new_gint64 (*(gint64 *) option->value);
127 break;
128 }
129 case KVP_TYPE_DOUBLE:
130 {
131 value = kvp_value_new_double (*(gdouble *) option->value);
132 break;
133 }
134 case KVP_TYPE_NUMERIC:
135 {
136 value = kvp_value_new_numeric (*(QofNumeric *) option->value);
137 break;
138 }
139 case KVP_TYPE_STRING:
140 {
141 value = kvp_value_new_string ((const gchar *) option->value);
142 break;
143 }
144 case KVP_TYPE_BOOLEAN:
145 {
146 break;
147 }
148 case KVP_TYPE_GUID:
149 {
150 break;
151 } /* unsupported */
152 case KVP_TYPE_TIME :
153 {
154 value = kvp_value_new_time ((QofTime*) option->value);
155 break;
156 }
157 #ifndef QOF_DISABLE_DEPRECATED
158 case KVP_TYPE_TIMESPEC:
159 {
160 value = kvp_value_new_timespec (*(Timespec *) option->value);
161 break;
162 }
163 #endif
164 case KVP_TYPE_BINARY:
165 {
166 break;
167 } /* unsupported */
168 case KVP_TYPE_GLIST:
169 {
170 break;
171 } /* unsupported */
172 case KVP_TYPE_FRAME:
173 {
174 break;
175 } /* unsupported */
176 }
177 if (value)
178 {
179 temp = g_strdup_printf ("/%s", option->option_name);
180 kvp_frame_set_value (be->backend_configuration, temp, value);
181 g_free (temp);
182 temp =
183 g_strdup_printf ("/%s/%s", QOF_CONFIG_DESC,
184 option->option_name);
185 kvp_frame_set_string (be->backend_configuration, temp,
186 option->description);
187 g_free (temp);
188 temp =
189 g_strdup_printf ("/%s/%s", QOF_CONFIG_TIP,
190 option->option_name);
191 kvp_frame_set_string (be->backend_configuration, temp,
192 option->tooltip);
193 g_free (temp);
194 /* only increment the counter if successful */
195 be->config_count = count;
196 }
197 }
KVP_TYPE_TIMESPEC
Definition: kvpframe.h:121
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
QofBackendOption_s::description
const gchar * description
Definition: qofbackend.h:119
timespec64
Definition: qoftime.h:97
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
kvp_frame_set_value
KvpFrame * kvp_frame_set_value(KvpFrame *frame, const gchar *key_path, const KvpValue *value)
Copy the KvpValue into the frame.
Definition: kvpframe.c:499
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_new_timespec
KvpValue * kvp_value_new_timespec(Timespec timespec)
Definition: deprecated.c:1482
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
_QofNumeric
Definition: qofnumeric.h:52
QofBackendOption_s::option_name
const gchar * option_name
Definition: qofbackend.h:118
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140
QofBackendOption_s::tooltip
const gchar * tooltip
Definition: qofbackend.h:120
KVP_TYPE_BINARY
Definition: kvpframe.h:130
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100
QofBackendOption_s::type
KvpValueType type
Definition: qofbackend.h:116
kvp_frame_set_string
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:442
KVP_TYPE_TIME
64bit time/date handling.
Definition: kvpframe.h:128
QofBackendOption_s::value
gpointer value
Definition: qofbackend.h:121

## ◆ qof_book_set_backend()

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 }
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
_QofBook::backend
QofBackend * backend
Definition: qofbook-p.h:87
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qof_load_backend_library()

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.

433 {
434 gchar *fullpath;
435 typedef void (*backend_init) (void);
436 GModule *backend;
437 backend_init gmod_init;
438 gpointer g;
439
440 g_return_val_if_fail (g_module_supported (), FALSE);
441 fullpath = g_module_build_path (directory, filename);
442 backend = g_module_open (fullpath, G_MODULE_BIND_LAZY);
443 if (!backend)
444 {
445 PERR (" No backend found. %s", g_module_error ());
446 return FALSE;
447 }
448 g = &gmod_init;
449 if (!g_module_symbol (backend, init_fcn, g))
450 {
451 PERR (" Backend did not initialise. %s", g_module_error ());
452 return FALSE;
453 }
454 g_module_make_resident (backend);
455 gmod_init ();
456 g_free (fullpath);
457 return TRUE;
458 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183

## ◆ qof_sqlite_provider_init()

void qof_sqlite_provider_init | ( | void |  | ) |

Initialises the SQLite backend.

Sets QOF SQLite Backend Version 0.3, access method = sqlite:

The ID in all SQLite tables created by QOF is the GUID of the entity, expressed as a hexadecimal string.

The version number only changes if:

1. QOF_OBJECT_VERSION changes
2. The QofBackendProvider struct is modified in QOF to support new members and SQLite can support the new function, or
3. The QofBackendOption settings are modified.

Initialises the backend and provides access to the functions that will load and save the data. Initialises default values for the QofBackendOption KvpFrame.

Instance KvpFrames are retrieved and stored as a separate table in the same SQLite file "sqlite_kvp". The primary key is an internal, sequential, identifier that does not need to be exposed. Each KvpValue is one record in the kvp table - frames are just a type of value. Records include fields for the path, type and value of the KvpValue as well as the GUID of the entity that holds the value.

Table name: sqlite_kvp Table values: internal_id, guid_as_string, path, type, value

At present, qof_sqlite has no QofBackendOption options and therefore no strings that are translatable.

Definition at line 1497 of file qof-sqlite.c.

1498 {
1499 QofBackendProvider *prov;
1500
1501 ENTER (" ");
1502 bindtextdomain (PACKAGE, LOCALE_DIR);
1503 prov = g_new0 (QofBackendProvider, 1);
1504 prov->provider_name = "QOF SQLite Backend Version 0.3";
1505 prov->access_method = ACCESS_METHOD;
1506 prov->partial_book_supported = TRUE;
1507 prov->backend_new = qsql_backend_new;
1508 prov->check_data_type = qsql_determine_file_type;
1509 prov->provider_free = qsql_provider_free;
1510 qof_backend_register_provider (prov);
1511 LEAVE (" ");
1512 }
qof_backend_register_provider
void qof_backend_register_provider(QofBackendProvider *)
Definition: qofsession.c:59
QofBackendProvider_s
Definition: qofbackend-p.h:238
QofBackendProvider_s::partial_book_supported
gboolean partial_book_supported
Partial QofBook handler.
Definition: qofbackend-p.h:254
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
QofBackendProvider_s::provider_free
void(* provider_free)(QofBackendProvider *)
Definition: qofbackend-p.h:280
QofBackendProvider_s::backend_new
QofBackend *(* backend_new)(void)
Definition: qofbackend-p.h:260
QofBackendProvider_s::access_method
const gchar * access_method
Definition: qofbackend-p.h:247
QofBackendProvider_s::check_data_type
gboolean(* check_data_type)(const gchar *)
Distinguish two providers with same access method.
Definition: qofbackend-p.h:277
qsql_backend_new
static QofBackend * qsql_backend_new(void)
Starts the backend and creates the context.
Definition: qof-sqlite.c:1446
QofBackendProvider_s::provider_name
const gchar * provider_name
Definition: qofbackend-p.h:241
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qsf_provider_init()

void qsf_provider_init | ( | void |  | ) |

Describe this backend to the application.

Sets QSF Backend Version 0.2, access method = file:

The version number only changes if:

1. The map schema is modified, or
2. The object schema is modified, or
3. The QofBackendProvider struct is modified in QOF to support new members and QSF can support the new function, or
4. The QofBackendOption settings are modified.

v0.2 introduces the QSF_MAP_FILES QofBackendOption.

Initialises the backend and provides access to the functions that will load and save the data. Initialises default values for the QofBackendOption KvpFrame.

Calls gettext because QofBackendOption strings are translatable.

Definition at line 1682 of file qsf-backend.c.

1683 {
1684 QofBackendProvider *prov;
1685
1686 bindtextdomain (PACKAGE, LOCALE_DIR);
1687 prov = g_new0 (QofBackendProvider, 1);
1688 prov->provider_name = "QSF Backend Version 0.4";
1689 prov->access_method = "file";
1690 prov->partial_book_supported = TRUE;
1691 prov->backend_new = qsf_backend_new;
1692 prov->check_data_type = qsf_determine_file_type;
1693 prov->provider_free = qsf_provider_free;
1694 qof_backend_register_provider (prov);
1695 }
qof_backend_register_provider
void qof_backend_register_provider(QofBackendProvider *)
Definition: qofsession.c:59
QofBackendProvider_s
Definition: qofbackend-p.h:238
QofBackendProvider_s::partial_book_supported
gboolean partial_book_supported
Partial QofBook handler.
Definition: qofbackend-p.h:254
QofBackendProvider_s::provider_free
void(* provider_free)(QofBackendProvider *)
Definition: qofbackend-p.h:280
QofBackendProvider_s::backend_new
QofBackend *(* backend_new)(void)
Definition: qofbackend-p.h:260
QofBackendProvider_s::access_method
const gchar * access_method
Definition: qofbackend-p.h:247
QofBackendProvider_s::check_data_type
gboolean(* check_data_type)(const gchar *)
Distinguish two providers with same access method.
Definition: qofbackend-p.h:277
QofBackendProvider_s::provider_name
const gchar * provider_name
Definition: qofbackend-p.h:241