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-SQLite outline | |
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 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 QofBackendProvider_s | QofBackendProvider |
typedef 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! | |
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. | |
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 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 177 of file qofbackend.h.
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 242 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 168 of file qofbackend.h.
enum QofBackendError |
The errors that can be reported to the GUI & other front-end users.
ERR_BACKEND_NO_HANDLER | no backend handler found for this access method (ENOSYS) |
ERR_BACKEND_NO_BACKEND | Backend * pointer was unexpectedly null |
ERR_BACKEND_BAD_URL | Can't parse url |
ERR_BACKEND_NO_SUCH_DB | the named database doesn't exist |
ERR_BACKEND_CANT_CONNECT | bad dbname/login/passwd or network failure |
ERR_BACKEND_CONN_LOST | Lost connection to server |
ERR_BACKEND_LOCKED | in use by another user (ETXTBSY) |
ERR_BACKEND_READONLY | cannot write to file/directory |
ERR_BACKEND_TOO_NEW | file/db version newer than what we can read |
ERR_BACKEND_DATA_CORRUPT | data in db is corrupt |
ERR_BACKEND_SERVER_ERR | error in response from server |
ERR_BACKEND_ALLOC | internal memory allocation failure |
ERR_BACKEND_PERM | user login successful, but no permissions to access the desired object |
ERR_BACKEND_MODIFIED | commit of object update failed because another user has modified the object |
ERR_BACKEND_MOD_DESTROY | commit of object update failed because another user has deleted the object |
ERR_BACKEND_MISC | undetermined error |
ERR_QSF_INVALID_OBJ | The QSF object failed to validate against the QSF object schema |
ERR_QSF_INVALID_MAP | The QSF map failed to validate against the QSF map schema |
ERR_QSF_BAD_OBJ_GUID | The QSF object contains one or more invalid GUIDs. |
ERR_QSF_BAD_QOF_VERSION | QSF map or object doesn't match the current QOF_OBJECT_VERSION. |
ERR_QSF_BAD_MAP |
The selected map validates but is unusable. This is usually because not all the required parameters for the defined objects have calculations described in the map. |
ERR_QSF_NO_MAP |
The QSF object file was loaded without a map. The QSF Object file requires a map but it was not provided. |
ERR_QSF_WRONG_MAP |
The selected map validates but is for different objects. The list of objects defined in this map does not include all the objects described in the current QSF object file. |
ERR_QSF_MAP_NOT_OBJ | Selected file is a QSF map and cannot be opened as a QSF object |
ERR_QSF_OVERFLOW |
EOVERFLOW - generated by strtol or strtoll. When converting XML strings into numbers, an overflow has been detected. The XML file contains invalid data in a field that is meant to hold a signed long integer or signed long long integer. |
ERR_FILEIO_FILE_BAD_READ |
QSF files cannot be opened alone. The data must be merged. This error is more of a warning that can be ignored by any routine that uses qof_book_merge on the new session. read failed or file prematurely truncated |
ERR_FILEIO_FILE_EMPTY | file exists, is readable, but is empty |
ERR_FILEIO_FILE_LOCKERR | mangled locks (unspecified error) |
ERR_FILEIO_FILE_NOT_FOUND | not found / no such file |
ERR_FILEIO_FILE_TOO_OLD | file version so old we can't read it |
ERR_FILEIO_UNKNOWN_FILE_TYPE | didn't recognize the file type |
ERR_FILEIO_PARSE_ERROR | couldn't parse the data in the file |
ERR_FILEIO_BACKUP_ERROR | couldn't make a backup of the file |
ERR_FILEIO_WRITE_ERROR | couldn't write to the file |
ERR_FILEIO_READ_ERROR | Could not open the file for reading. |
ERR_FILEIO_NO_ENCODING | file does not specify encoding |
ERR_NETIO_SHORT_READ | not enough bytes received |
ERR_NETIO_WRONG_CONTENT_TYPE | wrong kind of server, wrong data served |
ERR_NETIO_NOT_GNCXML |
|
ERR_SQL_MISSING_DATA | database doesn't contain expected data |
ERR_SQL_DB_TOO_OLD | database is old and needs upgrading |
ERR_SQL_DB_BUSY | database is busy, cannot upgrade version |
ERR_RPC_HOST_UNK | Host unknown |
ERR_RPC_CANT_BIND | can't bind to address |
ERR_RPC_CANT_ACCEPT | can't accept connection |
ERR_RPC_NO_CONNECTION | no connection to server |
ERR_RPC_BAD_VERSION | RPC Version Mismatch |
ERR_RPC_FAILED | Operation failed |
ERR_RPC_NOT_ADDED | object not added |
Definition at line 51 of file qofbackend.h.
00052 { 00053 ERR_BACKEND_NO_ERR = 0, 00054 ERR_BACKEND_NO_HANDLER, 00056 ERR_BACKEND_NO_BACKEND, 00058 ERR_BACKEND_BAD_URL, 00059 ERR_BACKEND_NO_SUCH_DB, 00060 ERR_BACKEND_CANT_CONNECT, 00062 ERR_BACKEND_CONN_LOST, 00063 ERR_BACKEND_LOCKED, 00064 ERR_BACKEND_READONLY, 00065 ERR_BACKEND_TOO_NEW, 00067 ERR_BACKEND_DATA_CORRUPT, 00068 ERR_BACKEND_SERVER_ERR, 00069 ERR_BACKEND_ALLOC, 00070 ERR_BACKEND_PERM, 00072 ERR_BACKEND_MODIFIED, 00074 ERR_BACKEND_MOD_DESTROY, 00076 ERR_BACKEND_MISC, 00078 /* QSF add-ons */ 00079 ERR_QSF_INVALID_OBJ, 00081 ERR_QSF_INVALID_MAP, 00083 ERR_QSF_BAD_OBJ_GUID, 00085 ERR_QSF_BAD_QOF_VERSION, 00087 ERR_QSF_BAD_MAP, 00093 ERR_QSF_NO_MAP, 00098 ERR_QSF_WRONG_MAP, 00104 ERR_QSF_MAP_NOT_OBJ, 00106 ERR_QSF_OVERFLOW, 00114 ERR_QSF_OPEN_NOT_MERGE, 00119 /* fileio errors */ 00120 ERR_FILEIO_FILE_BAD_READ = 1000, 00122 ERR_FILEIO_FILE_EMPTY, 00124 ERR_FILEIO_FILE_LOCKERR, 00125 ERR_FILEIO_FILE_NOT_FOUND, 00126 ERR_FILEIO_FILE_TOO_OLD, 00128 ERR_FILEIO_UNKNOWN_FILE_TYPE, 00130 ERR_FILEIO_PARSE_ERROR, 00132 ERR_FILEIO_BACKUP_ERROR, 00134 ERR_FILEIO_WRITE_ERROR, 00135 ERR_FILEIO_READ_ERROR, 00137 ERR_FILEIO_NO_ENCODING, 00139 /* network errors */ 00140 ERR_NETIO_SHORT_READ = 2000, 00141 ERR_NETIO_WRONG_CONTENT_TYPE, 00143 ERR_NETIO_NOT_GNCXML, 00146 /* database errors */ 00147 ERR_SQL_MISSING_DATA = 3000, 00149 ERR_SQL_DB_TOO_OLD, 00151 ERR_SQL_DB_BUSY, 00154 /* RPC errors */ 00155 ERR_RPC_HOST_UNK = 4000, 00156 ERR_RPC_CANT_BIND, 00157 ERR_RPC_CANT_ACCEPT, 00158 ERR_RPC_NO_CONNECTION, 00159 ERR_RPC_BAD_VERSION, 00160 ERR_RPC_FAILED, 00161 ERR_RPC_NOT_ADDED, 00162 } QofBackendError;
KvpFrame* qof_backend_complete_frame | ( | QofBackend * | be | ) |
Complete the backend_configuration and return the frame.
Definition at line 281 of file qofbackend.c.
00282 { 00283 g_return_val_if_fail (be, NULL); 00284 be->config_count = 0; 00285 return be->backend_configuration; 00286 }
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.
be | The QofBackend to be configured. |
Definition at line 483 of file qofbackend.c.
00484 { 00485 if (!be) 00486 return NULL; 00487 if (!be->get_config) 00488 return NULL; 00489 return (be->get_config) (be); 00490 }
void qof_backend_load_config | ( | QofBackend * | be, | |
KvpFrame * | config | |||
) |
Load configuration options specific to this backend.
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 473 of file qofbackend.c.
00474 { 00475 if (!be || !config) 00476 return; 00477 if (!be->load_config) 00478 return; 00479 (be->load_config) (be, config); 00480 }
void qof_backend_option_foreach | ( | KvpFrame * | config, | |
QofBackendOptionCB | cb, | |||
gpointer | data | |||
) |
Iterate over the frame and process each option.
Definition at line 456 of file qofbackend.c.
00458 { 00459 struct config_iterate helper; 00460 00461 if (!config || !cb) 00462 return; 00463 ENTER (" "); 00464 helper.fcn = cb; 00465 helper.count = 1; 00466 helper.data = data; 00467 helper.recursive = config; 00468 kvp_frame_for_each_slot (config, config_foreach_cb, &helper); 00469 LEAVE (" "); 00470 }
void qof_backend_prepare_frame | ( | QofBackend * | be | ) |
Initialise the backend_configuration
Definition at line 184 of file qofbackend.c.
00185 { 00186 g_return_if_fail (be); 00187 if (!kvp_frame_is_empty (be->backend_configuration)) 00188 { 00189 kvp_frame_delete (be->backend_configuration); 00190 be->backend_configuration = kvp_frame_new (); 00191 } 00192 be->config_count = 0; 00193 }
void qof_backend_prepare_option | ( | QofBackend * | be, | |
QofBackendOption * | option | |||
) |
Add an option to the backend_configuration. Repeat for more.
Definition at line 196 of file qofbackend.c.
00198 { 00199 KvpValue *value; 00200 gchar *temp; 00201 gint count; 00202 00203 g_return_if_fail (be || option); 00204 count = be->config_count; 00205 count++; 00206 value = NULL; 00207 switch (option->type) 00208 { 00209 case KVP_TYPE_GINT64: 00210 { 00211 value = kvp_value_new_gint64 (*(gint64 *) option->value); 00212 break; 00213 } 00214 case KVP_TYPE_DOUBLE: 00215 { 00216 value = kvp_value_new_double (*(gdouble *) option->value); 00217 break; 00218 } 00219 case KVP_TYPE_NUMERIC: 00220 { 00221 value = kvp_value_new_numeric (*(QofNumeric *) option->value); 00222 break; 00223 } 00224 case KVP_TYPE_STRING: 00225 { 00226 value = kvp_value_new_string ((const gchar *) option->value); 00227 break; 00228 } 00229 case KVP_TYPE_GUID: 00230 { 00231 break; 00232 } /* unsupported */ 00233 case KVP_TYPE_TIME : 00234 { 00235 value = kvp_value_new_time ((QofTime*) option->value); 00236 break; 00237 } 00238 #ifndef QOF_DISABLE_DEPRECATED 00239 case KVP_TYPE_TIMESPEC: 00240 { 00241 value = kvp_value_new_timespec (*(Timespec *) option->value); 00242 break; 00243 } 00244 #endif 00245 case KVP_TYPE_BINARY: 00246 { 00247 break; 00248 } /* unsupported */ 00249 case KVP_TYPE_GLIST: 00250 { 00251 break; 00252 } /* unsupported */ 00253 case KVP_TYPE_FRAME: 00254 { 00255 break; 00256 } /* unsupported */ 00257 } 00258 if (value) 00259 { 00260 temp = g_strdup_printf ("/%s", option->option_name); 00261 kvp_frame_set_value (be->backend_configuration, temp, value); 00262 g_free (temp); 00263 temp = 00264 g_strdup_printf ("/%s/%s", QOF_CONFIG_DESC, 00265 option->option_name); 00266 kvp_frame_set_string (be->backend_configuration, temp, 00267 option->description); 00268 g_free (temp); 00269 temp = 00270 g_strdup_printf ("/%s/%s", QOF_CONFIG_TIP, 00271 option->option_name); 00272 kvp_frame_set_string (be->backend_configuration, temp, 00273 option->tooltip); 00274 g_free (temp); 00275 /* only increment the counter if successful */ 00276 be->config_count = count; 00277 } 00278 }
void qof_book_set_backend | ( | QofBook * | book, | |
QofBackend * | ||||
) |
gboolean qof_load_backend_library | ( | const gchar * | directory, | |
const gchar * | filename, | |||
const gchar * | init_fcn | |||
) |
Load a QOF-compatible backend shared library.
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. |
Definition at line 504 of file qofbackend.c.
00506 { 00507 gchar *fullpath; 00508 typedef void (*backend_init) (void); 00509 GModule *backend; 00510 backend_init gmod_init; 00511 gpointer g; 00512 00513 g_return_val_if_fail (g_module_supported (), FALSE); 00514 fullpath = g_module_build_path (directory, filename); 00515 backend = g_module_open (fullpath, G_MODULE_BIND_LAZY); 00516 if (!backend) 00517 { 00518 PERR (" No backend found. %s", g_module_error ()); 00519 return FALSE; 00520 } 00521 g = &gmod_init; 00522 if (!g_module_symbol (backend, init_fcn, g)) 00523 { 00524 PERR (" Backend did not initialise. %s", g_module_error ()); 00525 return FALSE; 00526 } 00527 g_module_make_resident (backend); 00528 gmod_init (); 00529 g_free (fullpath); 00530 return TRUE; 00531 }