GnuCash  4.8a-132-gcdaeb421d+
Files | Macros | Typedefs | Enumerations | Functions

The QOF Backend is a pseudo-object providing an interface between the engine and a persistent data store (e.g. More...

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 void(* QofBePercentageFunc) (const char *message, double percent)
 DOCUMENT ME!
 
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. More...
 

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...
 
enum  SessionOpenMode {
  SESSION_NORMAL_OPEN = 0, SESSION_NEW_STORE = 2, SESSION_NEW_OVERWRITE = 3, SESSION_READ_ONLY = 4,
  SESSION_BREAK_LOCK = 5
}
 Mode for opening sessions. More...
 

Functions

QofBackendError qof_backend_get_error (QofBackend *)
 Get the last backend error. More...
 
void qof_backend_set_error (QofBackend *, QofBackendError)
 Set the error on the specified QofBackend. More...
 
gboolean qof_backend_can_rollback (QofBackend *)
 
void qof_backend_rollback_instance (QofBackend *, QofInstance *)
 
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 shareable libraries. More...
 
QofBackendqof_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 (QofBook *book)
 
void qof_session_destroy (QofSession *session)
 
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. More...
 
void qof_session_begin (QofSession *session, const char *new_uri, SessionOpenMode mode)
 Begins a new session. More...
 
void qof_session_load (QofSession *session, QofPercentageFunc percentage_func)
 
QofBook * qof_session_get_book (const QofSession *session)
 Returns the QofBook of this session. More...
 
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. More...
 
const char * qof_session_get_url (const QofSession *session)
 
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.
 
QofBackendqof_session_get_backend (const QofSession *session)
 Returns the qof session's backend.
 
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. More...
 
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. More...
 
void qof_session_end (QofSession *session)
 The qof_session_end() method will release the session lock. More...
 

Session Errors

QofBackendError qof_session_get_error (QofSession *session)
 The qof_session_get_error() routine can be used to obtain the reason for any failure. More...
 
const char * qof_session_get_error_message (const QofSession *session)
 
QofBackendError qof_session_pop_error (QofSession *session)
 The qof_session_pop_error() routine can be used to obtain the reason for any failure. More...
 

Detailed Description

The QOF Backend is a pseudo-object providing an interface between the engine and a persistent data store (e.g.

The QOF Session encapsulates a connection to a storage backend.

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.

That is, it manages the connection to a persistent 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

◆ QofPercentageFunc

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 accommodate 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 199 of file qofsession.h.

Enumeration Type Documentation

◆ 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_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 57 of file qofbackend.h.

58 {
59  ERR_BACKEND_NO_ERR = 0,
88  /* fileio errors */
106  /* network errors */
107  ERR_NETIO_SHORT_READ = 2000,
111  /* database errors */
112  ERR_SQL_MISSING_DATA = 3000,
119  /* RPC errors */
120  ERR_RPC_HOST_UNK = 4000,
commit of object update failed because another user has deleted the object
Definition: qofbackend.h:77
No read access permission for the given file.
Definition: qofbackend.h:100
Lost connection to server.
Definition: qofbackend.h:65
can't accept connection
Definition: qofbackend.h:122
database is busy, cannot upgrade version
Definition: qofbackend.h:115
couldn't parse the data in the file
Definition: qofbackend.h:95
whatever it is, we can't parse it.
Definition: qofbackend.h:109
not found / no such file
Definition: qofbackend.h:92
QofBackendError
The errors that can be reported to the GUI & other front-end users.
Definition: qofbackend.h:57
wrong kind of server, wrong data served
Definition: qofbackend.h:108
commit of object update failed because another user has modified the object
Definition: qofbackend.h:75
RPC Version Mismatch.
Definition: qofbackend.h:124
database is old and needs upgrading
Definition: qofbackend.h:113
Operation failed.
Definition: qofbackend.h:125
Can't parse url.
Definition: qofbackend.h:62
in use by another user (ETXTBSY)
Definition: qofbackend.h:66
couldn't write to the file
Definition: qofbackend.h:97
file will be upgraded and not be able to be read by prior versions - warn users
Definition: qofbackend.h:103
error in response from server
Definition: qofbackend.h:71
didn't recognize the file type
Definition: qofbackend.h:94
user login successful, but no permissions to access the desired object
Definition: qofbackend.h:73
file does not specify encoding
Definition: qofbackend.h:99
not enough bytes received
Definition: qofbackend.h:107
database is newer, we can't write to it
Definition: qofbackend.h:114
database doesn't contain expected data
Definition: qofbackend.h:112
EOVERFLOW - generated by strtol or strtoll.
Definition: qofbackend.h:81
User attempt to write to a directory reserved for internal use by GnuCash.
Definition: qofbackend.h:101
undetermined error
Definition: qofbackend.h:79
Host unknown.
Definition: qofbackend.h:120
file exists, is readable, but is empty
Definition: qofbackend.h:90
file/db version newer than what we can read
Definition: qofbackend.h:69
no backend handler found for this access method (ENOSYS)
Definition: qofbackend.h:60
read failed or file prematurely truncated
Definition: qofbackend.h:89
data in db is corrupt
Definition: qofbackend.h:70
LibDBI has numeric errors.
Definition: qofbackend.h:116
no connection to server
Definition: qofbackend.h:123
can't bind to address
Definition: qofbackend.h:121
the named database doesn't exist
Definition: qofbackend.h:63
couldn't make a backup of the file
Definition: qofbackend.h:96
File exists, data would be destroyed.
Definition: qofbackend.h:67
mangled locks (unspecified error)
Definition: qofbackend.h:91
Backend * pointer was unexpectedly null.
Definition: qofbackend.h:61
cannot write to file/directory
Definition: qofbackend.h:68
bad dbname/login/passwd or network failure
Definition: qofbackend.h:64
could not complete test for LibDBI bug
Definition: qofbackend.h:117
internal memory allocation failure
Definition: qofbackend.h:72
object not added
Definition: qofbackend.h:126
file version so old we can't read it
Definition: qofbackend.h:93
Could not open the file for reading.
Definition: qofbackend.h:98

◆ SessionOpenMode

Mode for opening sessions.

Enumerator
SESSION_NEW_STORE 

Open will fail if the URI doesn't exist or is locked.

SESSION_NEW_OVERWRITE 

Create a new store at the URI.

It will fail if the store already exists and is found to contain data that would be overwritten.

SESSION_READ_ONLY 

Create a new store at the URI even if a store already exists there.

SESSION_BREAK_LOCK 

Open the session read-only, ignoring any existing lock and not creating one if the URI isn't locked.

Definition at line 120 of file qofsession.h.

121 {
122  SESSION_NORMAL_OPEN = 0, // All False
124  SESSION_NEW_STORE = 2, // False, True, False (create)
126  SESSION_NEW_OVERWRITE = 3, // False, True, True (create | force)
128  SESSION_READ_ONLY = 4, // True, False, False (ignore_lock)
130  SESSION_BREAK_LOCK = 5 // True, False, True (ignore_lock | force)
Create a new store at the URI.
Definition: qofsession.h:126
Open the session read-only, ignoring any existing lock and not creating one if the URI isn't locked...
Definition: qofsession.h:130
Create a new store at the URI even if a store already exists there.
Definition: qofsession.h:128
SessionOpenMode
Mode for opening sessions.
Definition: qofsession.h:120
Open will fail if the URI doesn't exist or is locked.
Definition: qofsession.h:124

Function Documentation

◆ qof_backend_get_error()

QofBackendError qof_backend_get_error ( QofBackend )

Get the last backend error.

Definition at line 147 of file qof-backend.cpp.

148 {
149  if (qof_be == nullptr) return ERR_BACKEND_NO_ERR;
150  return ((QofBackend*)qof_be)->get_error();
151 }

◆ qof_backend_set_error()

void qof_backend_set_error ( QofBackend ,
QofBackendError   
)

Set the error on the specified QofBackend.

Definition at line 154 of file qof-backend.cpp.

155 {
156  if (qof_be == nullptr) return;
157  ((QofBackend*)qof_be)->set_error(err);
158 }

◆ qof_finalize_backend_libraries()

void qof_finalize_backend_libraries ( void  )

Finalize all loaded backend shareable libraries.

Definition at line 181 of file qof-backend.cpp.

182 {
183  QofBackend::release_backends();
184 }

◆ qof_load_backend_library()

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

Load a QOF-compatible backend shared library.

Parameters
directoryCan be NULL if filename is a complete path.
module_nameName of the .la file that describes the shared library. This provides platform independence, courtesy of libtool.
Returns
FALSE in case or error, otherwise TRUE.

◆ qof_session_begin()

void qof_session_begin ( QofSession *  session,
const char *  new_uri,
SessionOpenMode  mode 
)

Begins a new session.

Parameters
sessionNewly-allocated with qof_session_new.
urimust 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 or URI schemes as well.
modeThe SessionOpenMode.
==== SessionOpenMode ====
SESSION_NORMAL_OPEN: Find an existing file or database at the provided uri and open it if it is unlocked. If it is locked post a QOF_BACKEND_LOCKED error.
SESSION_NEW_STORE: Check for an existing file or database at the provided uri and if none is found, create it. If the file or database exists post a QOF_BACKED_STORE_EXISTS and return.
SESSION_NEW_OVERWRITE: Create a new file or database at the provided uri, deleting any existing file or database.
SESSION_READ_ONLY: Find an existing file or database and open it without disturbing the lock if it exists or setting one if not. This will also set a flag on the book that will prevent many elements from being edited and will prevent the backend from saving any edits.
SESSION_BREAK_LOCK: Find an existing file or database, lock it, and open it. If there is already a lock replace it with a new one for this session.
==== Errors ====
This function signals failure by queuing errors. After it completes use qof_session_get_error() and test that the value is ERROR_BACKEND_NONE to determine that the session began successfully.

Definition at line 614 of file qofsession.cpp.

615 {
616  if (!session) return;
617  session->begin(uri, mode);
618 }

◆ qof_session_end()

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.

Definition at line 651 of file qofsession.cpp.

652 {
653  if (!session) return;
654  session->end ();
655 }

◆ qof_session_get_book()

QofBook* qof_session_get_book ( const QofSession *  session)

Returns the QofBook of this session.

Definition at line 578 of file qofsession.cpp.

579 {
580  if (!session) return NULL;
581  return session->get_book ();
582 }

◆ qof_session_get_error()

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.

Definition at line 732 of file qofsession.cpp.

733 {
734  if (!session) return ERR_BACKEND_NO_BACKEND;
735  return session->get_error();
736 }
Backend * pointer was unexpectedly null.
Definition: qofbackend.h:61

◆ qof_session_get_file_path()

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

Definition at line 585 of file qofsession.cpp.

586 {
587  if (!session) return nullptr;
588  auto& path{session->get_file_path()};
589  return path.empty() ? nullptr : path.c_str ();
590 }

◆ qof_session_pop_error()

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.

Definition at line 571 of file qofsession.cpp.

572 {
573  if (!session) return ERR_BACKEND_NO_BACKEND;
574  return session->pop_error ();
575 }
Backend * pointer was unexpectedly null.
Definition: qofbackend.h:61

◆ qof_session_safe_save()

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.

Definition at line 637 of file qofsession.cpp.

638 {
639  if (!session) return;
640  session->safe_save (percentage_func);
641 }

◆ qof_session_save()

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.

Definition at line 629 of file qofsession.cpp.

631 {
632  if (!session) return;
633  session->save (percentage_func);
634 }

◆ qof_session_swap_data()

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.

Definition at line 658 of file qofsession.cpp.

659 {
660  if (session_1 == session_2) return;
661  if (!session_1 || !session_2) return;
662  session_1->swap_books (*session_2);
663 }