Files
file	qofbackend.h
	API for data storage Backend.

file	qofsession.h
	Encapsulates a connection to a backend (persistent store)

Macros
#define	QOF_MOD_BACKEND "qof.backend"

#define	QOF_MOD_SESSION "qof.session"

Typedefs
typedef struct QofBackendProvider_s	QofBackendProvider

typedef struct 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). More...

typedef void(*	QofBePercentageFunc )(const char *message, double percent)
	DOCUMENT ME!

typedef struct _QofSession	QofSession

typedef void(*	QofPercentageFunc )(const char *message, double percent)

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_STORE_EXISTS, 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_QOF_OVERFLOW, 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_FILEIO_FILE_EACCES, ERR_FILEIO_RESERVED_WRITE, ERR_FILEIO_FILE_UPGRADE, 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_TOO_NEW, ERR_SQL_DB_BUSY, ERR_SQL_BAD_DBI, ERR_SQL_DBI_UNTESTABLE, 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
void	qof_backend_set_error (QofBackend *be, QofBackendError err)

QofBackendError	qof_backend_get_error (QofBackend *be)

gboolean	qof_load_backend_library (const gchar directory, const gchar module_name)
	Load a QOF-compatible backend shared library. More...

void	qof_finalize_backend_libraries (void)
	Finalize all loaded backend sharable libraries.

QofBackend *	qof_book_get_backend (const QofBook *book)
	Retrieve the backend used by this book.

void	qof_book_set_backend (QofBook book, QofBackend )

QofSession *	qof_session_new (void)

void	qof_session_destroy (QofSession *session)

void	qof_session_swap_data (QofSession session_1, QofSession session_2)

void	qof_session_begin (QofSession session, const char book_id, gboolean ignore_lock, gboolean create, gboolean force)

void	qof_session_load (QofSession *session, QofPercentageFunc percentage_func)

QofBook *	qof_session_get_book (const QofSession *session)

const char *	qof_session_get_file_path (const QofSession *session)

const char *	qof_session_get_url (const QofSession *session)

gboolean	qof_session_save_in_progress (const QofSession *session)

void	qof_session_save (QofSession *session, QofPercentageFunc percentage_func)

void	qof_session_safe_save (QofSession *session, QofPercentageFunc percentage_func)

void	qof_session_end (QofSession *session)

Allow access to the begin routine for this backend.
void	qof_backend_run_begin (QofBackend be, QofInstance inst)

gboolean	qof_backend_begin_exists (const QofBackend *be)

void	qof_backend_run_commit (QofBackend be, QofInstance inst)

gboolean	qof_backend_commit_exists (const QofBackend *be)

Session Errors
QofBackendError	qof_session_get_error (QofSession *session)

const char *	qof_session_get_error_message (const QofSession *session)

QofBackendError	qof_session_pop_error (QofSession *session)

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.

The QOF Session encapsulates a connection to a storage backend. That is, it manages the connection to a persistant data store; whereas the backend is the thing that performs the actual datastore access.

This class provides several important services:

1) It resolves and loads the appropriate backend, based on the URL.

2) It reports backend errors (e.g. network errors, storage corruption errors) through a single, backend-independent API.

3) It reports non-error events received from the backend.

4) It helps manage global dataset locks. For example, for the file backend, the lock prevents multiple users from editing the same file at the same time, thus avoiding lost data due to race conditions. Thus, an open session implies that the associated file is locked.

5) Misc utilities, such as a search path for the file to be edited, and/or other URL resolution utilities. This should simplify install & maintenance problems for naive users who may not have a good grasp on what a file system is, or where they want to keep their data files.

6) In the future, this class is probably a good place to manage a portion of the user authentication process, and hold user credentials/cookies/keys/tokens. This is because at the coarsest level, authorization can happen at the datastore level: i.e. does this user even have the authority to connect to and open this datastore?

A brief note about books & sessions: A book encapsulates the datasets manipulated by QOF. A book holds the actual data. By contrast, the session mediates the connection between a book (the thing that lives in virtual memory in the local process) and the datastore (the place where book data lives permanently, e.g., file, database).

In the current design, a session may hold multiple books. For now, exactly what this means is somewhat vague, and code in various places makes some implicit assumptions: first, only one book is 'current' and open for editing. Next, its assumed that all of the books in a session are related in some way. i.e. that they are all earlier accounting periods of the currently open book. In particular, the backends probably make that assumption, in order to store the different accounting periods in a clump so that one can be found, given another.

If you want multiple books that are unrelated to each other, use multiple sessions.

The session now calls QofBackendProvider->check_data_type to check that the incoming path contains data that the backend provider can open. The backend provider should also check if it can contact it's storage media (disk, network, server, etc.) and abort if it can't. Malformed file URL's would be handled the same way.

Typedef Documentation

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

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.

Definition at line 147 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 137 of file qofbackend.h.

typedef void(* QofPercentageFunc)(const char *message, double percent)

The qof_session_load() method causes the QofBook to be made ready to to use with this URL/datastore. When the URL points at a file, then this routine would load the data from the file. With remote backends, e.g. network or SQL, this would load only enough data to make the book actually usable; it would not cause all of the data to be loaded.

XXX the current design tries to accomodate multiple calls to 'load' for each session, each time wiping out the old books; this seems wrong to me, and should be restricted to allow only one load per session.

Definition at line 173 of file qofsession.h.

Enumeration Type Documentation

enum QofBackendError

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

Warning: (GnuCash) If you modify QofBackendError, please update src/engine/gw-engine-spec.scm

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_STORE_EXISTS	File exists, data would be destroyed
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_QOF_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	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_FILEIO_FILE_EACCES	No read access permission for the given file
ERR_FILEIO_RESERVED_WRITE	User attempt to write to a directory reserved for internal use by GnuCash
ERR_FILEIO_FILE_UPGRADE	file will be upgraded and not be able to be read by prior versions - warn users
ERR_NETIO_SHORT_READ	not enough bytes received
ERR_NETIO_WRONG_CONTENT_TYPE	wrong kind of server, wrong data served
ERR_NETIO_NOT_GNCXML	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_TOO_NEW	database is newer, we can't write to it
ERR_SQL_DB_BUSY	database is busy, cannot upgrade version
ERR_SQL_BAD_DBI	LibDBI has numeric errors
ERR_SQL_DBI_UNTESTABLE	could not complete test for LibDBI bug
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 59 of file qofbackend.h.

 {
     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_STORE_EXISTS, 
     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_QOF_OVERFLOW,                   
     /* fileio errors */
     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_FILEIO_FILE_EACCES,    
     ERR_FILEIO_RESERVED_WRITE, 
     ERR_FILEIO_FILE_UPGRADE,   
     /* network errors */
     ERR_NETIO_SHORT_READ = 2000,  
     ERR_NETIO_WRONG_CONTENT_TYPE, 
     ERR_NETIO_NOT_GNCXML,         
     /* database errors */
     ERR_SQL_MISSING_DATA = 3000,  
     ERR_SQL_DB_TOO_OLD,           
     ERR_SQL_DB_TOO_NEW,           
     ERR_SQL_DB_BUSY,              
     ERR_SQL_BAD_DBI,              
     ERR_SQL_DBI_UNTESTABLE,       
     /* RPC errors */
     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,            
 } QofBackendError;

Function Documentation

QofBackendError qof_backend_get_error ( QofBackend * be )

The qof_backend_get_error() routine pops an error code off the error stack.

void qof_backend_set_error	(	QofBackend *	be,
		QofBackendError	err
	)

The qof_backend_set_error() routine pushes an error code onto the error stack. (FIXME: the stack is 1 deep in current implementation).

gboolean qof_load_backend_library	(	const gchar *	directory,
		const gchar *	module_name
	)

Load a QOF-compatible backend shared library.

Parameters

directory	Can be NULL if filename is a complete path.
module_name	Name of the .la file that describes the shared library. This provides platform independence, courtesy of libtool.

Returns: FALSE in case or error, otherwise TRUE.

void qof_session_begin	(	QofSession *	session,
		const char *	book_id,
		gboolean	ignore_lock,
		gboolean	create,
		gboolean	force
	)

The qof_session_begin () method begins a new session. It takes as an argument the book id. The book id must be a string in the form of a URI/URL. The access method specified depends on the loaded backends. Paths may be relative or absolute. If the path is relative; that is, if the argument is "file://somefile.xml" then the current working directory is assumed. Customized backends can choose to search other, application-specific, directories as well.

The 'ignore_lock' argument, if set to TRUE, will cause this routine to ignore any global-datastore locks (e.g. file locks) that it finds. If set to FALSE, then file/database-global locks will be tested and obeyed.

If the datastore exists, can be reached (e.g over the net), connected to, opened and read, and a lock can be obtained then a lock will be obtained. Note that while multi-user datastores (e.g. the SQL backend) typically will have record-level locking and therefor should not need to get a global lock, qof works by having a local copy of the whole database and can't be trusted to handle multiple users writing data, so we lock the database anyway.

If qof_session_begin is called with create == TRUE, then it will check for the existence of the file or database and return after posting a QOF_BACKEND_STORE_EXISTS error if it exists, unless force is also set to true.

If an error occurs, it will be pushed onto the session error stack, and that is where it should be examined.

void qof_session_end ( QofSession * session )

The qof_session_end() method will release the session lock. For the file backend, it will not save the data to a file. Thus, this method acts as an "abort" or "rollback" primitive. However, for other backends, such as the sql backend, the data would have been written out before this, and so this routines wouldn't roll-back anything; it would just shut the connection.

QofBook* qof_session_get_book ( const QofSession * session )

Returns the QofBook of this session.

QofBackendError qof_session_get_error ( QofSession * session )

The qof_session_get_error() routine can be used to obtain the reason for any failure. Calling this routine returns the current error.

const char* qof_session_get_file_path ( const QofSession * session )

The qof_session_get_file_path() routine returns the fully-qualified file path for the session. That is, if a relative or partial filename was for the session, then it had to have been fully resolved to open the session. This routine returns the result of this resolution. The path is always guaranteed to reside in the local file system, even if the session itself was opened as a URL. (currently, the filepath is derived from the url by substituting commas for slashes).

The qof_session_get_url() routine returns the url that was opened. URL's for local files take the form of file:/some/where/some/file.gml

QofBackendError qof_session_pop_error ( QofSession * session )

The qof_session_pop_error() routine can be used to obtain the reason for any failure. Calling this routine resets the error value.

This routine allows an implementation of multiple error values, e.g. in a stack, where this routine pops the top value. The current implementation has a stack that is one-deep.

See qofbackend.h for a listing of returned errors.

void qof_session_safe_save	(	QofSession *	session,
		QofPercentageFunc	percentage_func
	)

A special version of save used in the sql backend which moves the existing tables aside, then saves everything to new tables, then deletes the old tables after the save is completed without error. If there are errors, it removes the old tables and renames the new tables back.

void qof_session_save	(	QofSession *	session,
		QofPercentageFunc	percentage_func
	)

The qof_session_save() method will commit all changes that have been made to the session. For the file backend, this is nothing more than a write to the file of the current Accounts & etc. For the SQL backend, this is typically a no-op (since all data has already been written out to the database.

gboolean qof_session_save_in_progress ( const QofSession * session )

The qof_session_not_saved() subroutine will return TRUE if any data in the session hasn't been saved to long-term storage.

void qof_session_swap_data	(	QofSession *	session_1,
		QofSession *	session_2
	)

The qof_session_swap_data () method swaps the book of the two given sessions. It is useful for 'Save As' type functionality.

Files

Macros

Typedefs

Enumerations

Functions

Allow access to the begin routine for this backend.

Session Errors

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation