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


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


Enumeration Type Documentation

enum QofBackendError

The errors that can be reported to the GUI & other front-end users.

Enumerator:
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 
Deprecated:
whatever it is, we can't parse it.
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;


Function Documentation

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.

Parameters:
be The QofBackend to be configured.
Returns:
A new KvpFrame containing the available options or NULL on failure.

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.

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

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


Generated on Fri Nov 10 04:06:05 2006 for QOF by  doxygen 1.5.1