Backend
[Object: Dynamic Object Class Framework]

Data Structures
struct	QofBackendOption_s
Modules
	QOF Serialisation Format
Files
file	qofbackend.h
	API for data storage Backend.
file	qofsession.h
	Encapsulates a connection to a backend (persistent store).
Defines
#define	QOF_MOD_BACKEND   "qof.backend"
#define	QOF_MOD_SESSION   "qof.session"
#define	QOF_STDOUT   ">"
	Allow session data to be printed to stdout.
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).
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_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_FILEIO_FILE_EACCES, 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
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.
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_if_nonexistent)
void	qof_session_load (QofSession *session, QofPercentageFunc percentage_func)
void	qof_session_add_book (QofSession *session, QofBook *book)
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)
gboolean	qof_session_save_may_clobber_data (const QofSession *session)
void	qof_session_save (QofSession *session, QofPercentageFunc percentage_func)
void	qof_session_end (QofSession *session)
void	qof_session_add_close_hook (GFunc fn, gpointer data)
void	qof_session_call_close_hooks (QofSession *session)
gboolean	qof_session_export (QofSession *tmp_session, QofSession *real_session, QofPercentageFunc percentage_func)
GList *	qof_backend_get_registered_access_method_list (void)
void	qof_session_ensure_all_data_loaded (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.

---

Define Documentation

#define QOF_STDOUT   ">"

Allow session data to be printed to stdout.

book_id can't be NULL and we do need to have an access_method, so use one to solve the other.

To print a session to stdout, use qof_session_begin. Example:

qof_session_begin(session,QOF_STDOUT,TRUE,FALSE);

When you call qof_session_save(session, NULL), the output will appear on stdout and can be piped or redirected to other processes.

Currently, only the QSF backend supports writing to stdout, other backends may return a QofBackendError.

Definition at line 401 of file qofsession.h.

---

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 159 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 225 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 149 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 164 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_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_FILEIO_FILE_EACCES	No read access permission for the given file
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_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 55 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_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,         
    /* QSF add-ons */
    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,     
    /* 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,    
    /* 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_BUSY,              
    /* 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

KvpFrame* qof_backend_complete_frame

(

QofBackend *

be

)

Complete the backend_configuration and return the frame.

Definition at line 285 of file qofbackend.c.

{
    g_return_val_if_fail(be, NULL);
    be->config_count = 0;
    return be->backend_configuration;
}

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 489 of file qofbackend.c.

{
    if (!be)
    {
        return NULL;
    }
    if (!be->get_config)
    {
        return NULL;
    }
    return (be->get_config) (be);
}

QofBackendError qof_backend_get_error

(

QofBackend *

be

)

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

Definition at line 56 of file qofbackend.c.

{
    QofBackendError err;
    if (!be) return ERR_BACKEND_NO_BACKEND;

    /* use 'stack-pop' semantics */
    err = be->last_err;
    be->last_err = ERR_BACKEND_NO_ERR;
    return err;
}

GList* qof_backend_get_registered_access_method_list

(

void

)

Return a list of strings for the registered access methods. The owner is responsible for freeing the list but not the strings.

Definition at line 70 of file qofsession.c.

{
    GList* list = NULL;
    GSList* node;

    for ( node = provider_list; node != NULL; node = node->next )
    {
        QofBackendProvider *prov = node->data;
        list = g_list_append( list, (gchar*)prov->access_method );
    }

    return list;
}

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 475 of file qofbackend.c.

{
    if (!be || !config)
    {
        return;
    }
    if (!be->load_config)
    {
        return;
    }
    (be->load_config) (be, config);
}

void qof_backend_option_foreach	(	KvpFrame *	config,
		QofBackendOptionCB	cb,
		gpointer	data
	)

Iterate over the frame and process each option.

Definition at line 457 of file qofbackend.c.

{
    struct config_iterate helper;

    if (!config || !cb)
    {
        return;
    }
    ENTER (" ");
    helper.fcn = cb;
    helper.count = 1;
    helper.data = data;
    helper.recursive = config;
    kvp_frame_for_each_slot(config, config_foreach_cb, &helper);
    LEAVE (" ");
}

void qof_backend_prepare_frame

(

QofBackend *

be

)

Initialise the backend_configuration

Definition at line 200 of file qofbackend.c.

{
    g_return_if_fail(be);
    if (!kvp_frame_is_empty(be->backend_configuration))
    {
        kvp_frame_delete(be->backend_configuration);
        be->backend_configuration = kvp_frame_new();
    }
    be->config_count = 0;
}

void qof_backend_prepare_option	(	QofBackend *	be,
		const QofBackendOption *	option
	)

Add an option to the backend_configuration. Repeat for more.

Definition at line 211 of file qofbackend.c.

{
    KvpValue *value;
    gchar *temp;
    gint count;

    g_return_if_fail(be || option);
    count = be->config_count;
    count++;
    value = NULL;
    switch (option->type)
    {
    case KVP_TYPE_GINT64   :
    {
        value = kvp_value_new_gint64(*(gint64*)option->value);
        break;
    }
    case KVP_TYPE_DOUBLE   :
    {
        value = kvp_value_new_double(*(double*)option->value);
        break;
    }
    case KVP_TYPE_NUMERIC  :
    {
        value = kvp_value_new_numeric(*(gnc_numeric*)option->value);
        break;
    }
    case KVP_TYPE_STRING   :
    {
        value = kvp_value_new_string((const char*)option->value);
        break;
    }
    case KVP_TYPE_GUID     :
    {
        break;  /* unsupported */
    }
    case KVP_TYPE_TIMESPEC :
    {
        value = kvp_value_new_timespec(*(Timespec*)option->value);
        break;
    }
    case KVP_TYPE_BINARY   :
    {
        break;  /* unsupported */
    }
    case KVP_TYPE_GLIST    :
    {
        break;  /* unsupported */
    }
    case KVP_TYPE_FRAME    :
    {
        break;  /* unsupported */
    }
    case KVP_TYPE_GDATE    :
    {
        break;  /* unsupported */
    }
    }
    if (value)
    {
        temp = g_strdup_printf("/%s", option->option_name);
        kvp_frame_set_value(be->backend_configuration, temp, value);
        g_free(temp);
        temp = g_strdup_printf("/%s/%s", QOF_CONFIG_DESC, option->option_name);
        kvp_frame_set_string(be->backend_configuration, temp, option->description);
        g_free(temp);
        temp = g_strdup_printf("/%s/%s", QOF_CONFIG_TIP, option->option_name);
        kvp_frame_set_string(be->backend_configuration, temp, option->tooltip);
        g_free(temp);
        /* only increment the counter if successful */
        be->config_count = count;
    }
}

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

Definition at line 46 of file qofbackend.c.

{
    if (!be) return;

    /* use stack-push semantics. Only the earliest error counts */
    if (ERR_BACKEND_NO_ERR != be->last_err) return;
    be->last_err = err;
}

gboolean qof_instance_copy_coll	(	QofSession *	new_session,
		QofCollection *	entity_coll
	)

Copy a QofCollection of entities.

The QofBook in the new_session must not contain any entities with the same GUID as any entities in the collection - there is no support for handling collisions - instead, use Merging QofBook structures

Parameters:

	new_session	- the target session
	entity_coll	- a QofCollection of any QofIdType.

Returns:

FALSE, without copying, if new_session contains any entities with the same GUID. Otherwise TRUE.

Definition at line 775 of file qofsession.c.

{
    QofInstanceCopyData qecd;

    g_return_val_if_fail(new_session, FALSE);
    if (!entity_coll)
    {
        return FALSE;
    }
    qof_event_suspend();
    qecd.param_list = NULL;
    qecd.new_session = new_session;
    qof_book_set_partial(qof_session_get_book(qecd.new_session));
    qof_collection_foreach(entity_coll, qof_instance_coll_foreach, &qecd);
    qof_class_param_foreach(qof_collection_get_type(entity_coll),
                            qof_instance_param_cb, &qecd);
    qof_collection_foreach(entity_coll, qof_instance_coll_copy, &qecd);
    if (qecd.param_list != NULL)
    {
        g_slist_free(qecd.param_list);
    }
    qof_event_resume();
    return TRUE;
}

gboolean qof_instance_copy_coll_r	(	QofSession *	new_session,
		QofCollection *	coll
	)

Recursively copy a collection of entities to a session.

Note:

This function creates a partial QofBook. See qof_instance_copy_to_session for more information.

The QofBook in the new_session must not contain any entities with the same GUID as any entities to be copied - there is no support for handling collisions - instead, use Merging QofBook structures

Objects can be defined solely in terms of QOF data types or as a mix of data types and other objects, which may in turn include other objects. These references can be copied recursively down to the third level. See QofInstanceReference.

Note:

This is a deep recursive copy - every referenced entity is copied to the new session, including all parameters. The starting point is all entities in the top level collection. It can take some time.

Parameters:

	coll	A QofCollection of entities that may or may not have references.
	new_session	The QofSession to receive the copied entities.

Returns:

TRUE on success; if any individual copy fails, returns FALSE. Note : Some entities may have been copied successfully even if one of the references fails to copy.

Definition at line 948 of file qofsession.c.

{
    struct recurse_s store;
    gboolean success;

    if ((!new_session) || (!coll))
    {
        return FALSE;
    }
    store.session = new_session;
    success = TRUE;
    store.success = success;
    store.ent_list = NULL;
    store.ref_list = qof_class_get_referenceList(qof_collection_get_type(coll));
    success = qof_instance_copy_coll(new_session, coll);
    if (success)
    {
        qof_collection_foreach(coll, recurse_ent_cb, &store);
    }
    return success;
}

gboolean qof_instance_copy_list	(	QofSession *	new_session,
		GList *	entity_list
	)

Copy a GList of entities to another session.

The QofBook in the new_session must not contain any entities with the same GUID as any of the source entities - there is no support for handling collisions, instead use Merging QofBook structures

Note that the GList (e.g. from qof_sql_query_run) can contain QofInstance pointers of any QofIdType, in any sequence. As long as all members of the list are QofInstance*, and all GUID's are unique, the list can be copied.

Parameters:

	new_session	- the target session
	entity_list	- a GList of QofInstance pointers of any type(s).

Returns:

FALSE, without copying, if new_session contains any entities with the same GUID. Otherwise TRUE.

Definition at line 749 of file qofsession.c.

{
    QofInstanceCopyData *qecd;

    if (!new_session || !entity_list)
    {
        return FALSE;
    }
    ENTER (" list=%d", g_list_length(entity_list));
    qecd = g_new0(QofInstanceCopyData, 1);
    qof_event_suspend();
    qecd->param_list = NULL;
    qecd->new_session = new_session;
    qof_book_set_partial(qof_session_get_book(new_session));
    g_list_foreach(entity_list, qof_instance_list_foreach, qecd);
    qof_event_resume();
    if (qecd->error)
    {
        PWARN (" some/all entities in the list could not be copied.");
    }
    g_free(qecd);
    LEAVE (" ");
    return TRUE;
}

gboolean qof_instance_copy_one_r	(	QofSession *	new_session,
		QofInstance *	ent
	)

Recursively copy a single entity to a new session.

Copy the single entity and all referenced entities to the second level.

Only entities that are directly referenced by the top level entity are copied.

This is a deep copy - all parameters of all referenced entities are copied. If the top level entity has no references, this is identical to qof_instance_copy_to_session.

Parameters:

	ent	A single entity that may or may not have references.
	new_session	The QofSession to receive the copied entities.

Returns:

TRUE on success; if any individual copy fails, returns FALSE. Note : Some entities may have been copied successfully even if one of the references fails to copy.

Definition at line 970 of file qofsession.c.

{
    struct recurse_s store;
    QofCollection *coll;
    gboolean success;

    if ((!new_session) || (!ent))
    {
        return FALSE;
    }
    store.session = new_session;
    success = TRUE;
    store.success = success;
    store.ref_list = qof_class_get_referenceList(ent->e_type);
    success = qof_instance_copy_to_session(new_session, ent);
    if (success == TRUE)
    {
        coll = qof_book_get_collection(qof_session_get_book(new_session), ent->e_type);
        if (coll)
        {
            qof_collection_foreach(coll, recurse_ent_cb, &store);
        }
    }
    return success;
}

gboolean qof_instance_copy_to_session	(	QofSession *	new_session,
		QofInstance *	original
	)

Copy a single QofInstance to another session.

Checks first that no entity in the session book contains the GUID of the source entity.

Parameters:

	new_session	- the target session
	original	- the QofInstance* to copy

Returns:

FALSE without copying if the session contains an entity with the same GUID already, otherwise TRUE.

Definition at line 709 of file qofsession.c.

{
    QofInstanceCopyData qecd;
    QofInstance *inst;
    QofBook *book;

    if (!new_session || !original)
    {
        return FALSE;
    }
    if (qof_instance_guid_match(new_session, original))
    {
        return FALSE;
    }
    if (!qof_object_compliance(original->e_type, TRUE))
    {
        return FALSE;
    }
    qof_event_suspend();
    qecd.param_list = NULL;
    book = qof_session_get_book(new_session);
    qecd.new_session = new_session;
    qof_book_set_partial(book);
    inst = (QofInstance*)qof_object_new_instance(original->e_type, book);
    qecd.to = inst;
    qecd.from = original;
    qof_instance_set_guid(qecd.to, qof_instance_get_guid(original));
    qof_begin_edit(inst);
    qof_class_param_foreach(original->e_type, qof_instance_param_cb, &qecd);
    qof_commit_edit(inst);
    if (g_slist_length(qecd.param_list) == 0)
    {
        return FALSE;
    }
    g_slist_foreach(qecd.param_list, qof_instance_foreach_copy, &qecd);
    g_slist_free(qecd.param_list);
    qof_event_resume();
    return TRUE;
}

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_add_book	(	QofSession *	session,
		QofBook *	book
	)

The qof_session_add_book() allows additional books to be added to a session. XXX Under construction, clarify the following when done: XXX There must already be an open book in the session already!? XXX Only one open book at a time per session is allowed!? XXX each book gets its own unique backend ???

Definition at line 249 of file qofsession.c.

{
    GList *node;
    if (!session) return;

    ENTER (" sess=%p book=%p", session, addbook);

    /* See if this book is already there ... */
    for (node = session->books; node; node = node->next)
    {
        QofBook *book = node->data;
        if (addbook == book) return;
    }

    if ('y' == addbook->book_open)
    {
        /* hack alert -- someone should free all the books in the list,
         * but it should probably not be us ... since the books backends
         * should be shutdown first, etc */
        /* XXX this should probably be an error XXX */
        g_list_free (session->books);
        session->books = g_list_append (NULL, addbook);
    }
    else
    {
        /* XXX Need to tell the backend to add a book as well */
        session->books = g_list_append (session->books, addbook);
    }

    qof_book_set_backend (addbook, session->backend);
    LEAVE (" ");
}

void qof_session_add_close_hook	(	GFunc	fn,
		gpointer	data
	)

Register a function to be called just before a session is closed.

Parameters:

	fn	The function to be called. The function definition must be func(gpointer session, gpointer user_data);
	data	The data to be passed to the function.

Definition at line 89 of file qofsession.c.

{
    GHook *hook;

    if (session_closed_hooks == NULL)
    {
        session_closed_hooks = malloc(sizeof(GHookList)); /* LEAKED */
        g_hook_list_init (session_closed_hooks, sizeof(GHook));
    }

    hook = g_hook_alloc(session_closed_hooks);
    if (!hook)
        return;

    hook->func = (GHookFunc)fn;
    hook->data = data;
    g_hook_append(session_closed_hooks, hook);
}

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

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. In the absence of a customised backend, only QSF XML would be accepted). 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. Customised 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 multi-user datastores (e.g. the SQL backend) typically will not need to get a global lock, and thus, the user will not be locked out. That's the whole point of 'multi-user'.

If the file/database doesn't exist, and the create_if_nonexistent flag is set to TRUE, then the database is created.

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

Definition at line 1140 of file qofsession.c.

{
    gchar **splituri;

    if (!session) return;

    ENTER (" sess=%p ignore_lock=%d, book-id=%s",
           session, ignore_lock,
           book_id ? book_id : "(null)");

    /* Clear the error condition of previous errors */
    qof_session_clear_error (session);

    /* Check to see if this session is already open */
    if (session->book_id)
    {
        qof_session_push_error (session, ERR_BACKEND_LOCKED, NULL);
        LEAVE("push error book is already open ");
        return;
    }

    /* seriously invalid */
    if (!book_id)
    {
        qof_session_push_error (session, ERR_BACKEND_BAD_URL, NULL);
        LEAVE("push error missing book_id");
        return;
    }

    /* destroy the old backend */
    qof_session_destroy_backend(session);

    /* Store the session URL  */
    session->book_id = g_strdup (book_id);

    /* Look for something of the form of "file://", "http://" or
     * "postgres://". Everything before the colon is the access
     * method.  Load the first backend found for that access method.
     */
    splituri = g_strsplit ( book_id, "://", 2 );
    if ( splituri[1] == NULL ) /* no access method in the uri, use generic "file" backend */
        qof_session_load_backend(session, "file");
    else                       /* access method found, load appropriate backend */
        qof_session_load_backend(session, splituri[0]);
    g_strfreev ( splituri );

    /* No backend was found. That's bad. */
    if (NULL == session->backend)
    {
        g_free(session->book_id);
        session->book_id = NULL;
        qof_session_push_error (session, ERR_BACKEND_BAD_URL, NULL);
        LEAVE (" BAD: no backend: sess=%p book-id=%s",
               session,  book_id ? book_id : "(null)");
        return;
    }

    /* If there's a begin method, call that. */
    if (session->backend->session_begin)
    {
        char *msg;
        int err;

        (session->backend->session_begin)(session->backend, session,
                                          session->book_id, ignore_lock,
                                          create_if_nonexistent);
        PINFO("Done running session_begin on backend");
        err = qof_backend_get_error(session->backend);
        msg = qof_backend_get_message(session->backend);
        if (err != ERR_BACKEND_NO_ERR)
        {
            g_free(session->book_id);
            session->book_id = NULL;
            qof_session_push_error (session, err, msg);
            LEAVE(" backend error %d %s", err, msg ? msg : "(null)");
            return;
        }
        if (msg != NULL)
        {
            PWARN("%s", msg);
            g_free(msg);
        }
    }

    LEAVE (" sess=%p book-id=%s",
           session,  book_id ? book_id : "(null)");
}

void qof_session_call_close_hooks

(

QofSession *

session

)

Call all registered session close hooks, informing them that the specified session is about to be closed.

Parameters:

session

A pointer to the session being closed.

Definition at line 109 of file qofsession.c.

{
    GHook *hook;
    GFunc fn;

    if (session_closed_hooks == NULL)
        return;

    hook = g_hook_first_valid (session_closed_hooks, FALSE);
    while (hook)
    {
        fn = (GFunc)hook->func;
        fn(session, hook->data);
        hook = g_hook_next_valid (session_closed_hooks, hook, FALSE);
    }
}

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 1516 of file qofsession.c.

{
    if (!session) return;

    ENTER ("sess=%p book_id=%s", session, session->book_id
           ? session->book_id : "(null)");

    /* close down the backend first */
    if (session->backend && session->backend->session_end)
    {
        (session->backend->session_end)(session->backend);
    }

    qof_session_clear_error (session);

    g_free (session->book_id);
    session->book_id = NULL;

    LEAVE ("sess=%p book_id=%s", session, session->book_id
           ? session->book_id : "(null)");
}

void qof_session_ensure_all_data_loaded

(

QofSession *

session

)

Ensure all of the data is loaded from the session.

Definition at line 305 of file qofsession.c.

{
    QofBackend* backend;

    if (session == NULL) return;
    backend = qof_session_get_backend(session);
    if (backend == NULL) return;

    if (backend->load == NULL) return;
    backend->load(backend, qof_session_get_book(session), LOAD_TYPE_LOAD_ALL);
    qof_session_push_error (session, qof_backend_get_error(backend), NULL);
}

gboolean qof_session_events_pending

(

const QofSession *

session

)

The qof_session_events_pending() method will return TRUE if the backend has pending events which must be processed to bring the engine up to date with the backend.

Definition at line 1602 of file qofsession.c.

{
    if (!session) return FALSE;
    if (!session->backend) return FALSE;
    if (!session->backend->events_pending) return FALSE;

    return session->backend->events_pending (session->backend);
}

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 162 of file qofsession.c.

{
    QofBackendError err;

    if (!session) return ERR_BACKEND_NO_BACKEND;

    /* if we have a local error, return that. */
    if (ERR_BACKEND_NO_ERR != session->last_err)
    {
        return session->last_err;
    }

    /* maybe we should return a no-backend error ??? */
    if (! session->backend) return ERR_BACKEND_NO_ERR;

    err = qof_backend_get_error (session->backend);
    session->last_err = err;
    return err;
}

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 290 of file qofsession.c.

{
    if (!session) return NULL;
    if (!session->backend) return NULL;
    return session->backend->fullpath;
}

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 198 of file qofsession.c.

{
    QofBackendError err;

    if (!session) return ERR_BACKEND_NO_BACKEND;

    err = qof_session_get_error(session);
    qof_session_clear_error(session);

    return err;
}

gboolean qof_session_process_events

(

QofSession *

session

)

The qof_session_process_events() method will process any events indicated by the qof_session_events_pending() method. It returns TRUE if the engine was modified while engine events were suspended.

Definition at line 1612 of file qofsession.c.

{
    if (!session) return FALSE;
    if (!session->backend) return FALSE;
    if (!session->backend->process_events) return FALSE;

    return session->backend->process_events (session->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. 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.

Todo:

check the access_method too, not in scope here, yet.

Definition at line 1345 of file qofsession.c.

{
    GList *node;
    QofBackend *be;
    gboolean partial, change_backend;
    QofBackendProvider *prov;
    GSList *p;
    QofBook *book, *abook;
    int err;
    gint num;
    char *msg = NULL;
    char *book_id;

    if (!session) return;
    if (!g_atomic_int_dec_and_test(&session->lock))
        goto leave;
    ENTER ("sess=%p book_id=%s",
           session, session->book_id ? session->book_id : "(null)");
    /* Partial book handling. */
    book = qof_session_get_book(session);
    partial = (gboolean)GPOINTER_TO_INT(qof_book_get_data(book, PARTIAL_QOFBOOK));
    change_backend = FALSE;
    msg = g_strdup_printf(" ");
    book_id = g_strdup(session->book_id);
    if (partial == TRUE)
    {
        if (session->backend && session->backend->provider)
        {
            prov = session->backend->provider;
            if (TRUE == prov->partial_book_supported)
            {
                /* if current backend supports partial, leave alone. */
                change_backend = FALSE;
            }
            else
            {
                change_backend = TRUE;
            }
        }
        /* If provider is undefined, assume partial not supported. */
        else
        {
            change_backend = TRUE;
        }
    }
    if (change_backend == TRUE)
    {
        qof_session_destroy_backend(session);
        if (!qof_providers_initialized)
        {
            for (num = 0; backend_list[num].filename != NULL; num++)
            {
                qof_load_backend_library(backend_list[num].libdir,
                                         backend_list[num].filename);
            }
            qof_providers_initialized = TRUE;
        }
        p = provider_list;
        while (p != NULL)
        {
            prov = p->data;
            if (TRUE == prov->partial_book_supported)
            {
                /*      if((TRUE == prov->partial_book_supported) &&
                (0 == g_ascii_strcasecmp (access_method, prov->access_method)))
                {*/
                if (NULL == prov->backend_new) continue;
                /* Use the providers creation callback */
                session->backend = (*(prov->backend_new))();
                session->backend->provider = prov;
                if (session->backend->session_begin)
                {
                    /* Call begin - backend has been changed,
                       so make sure a file can be written,
                       use ignore_lock and create_if_nonexistent */
                    g_free(session->book_id);
                    session->book_id = NULL;
                    (session->backend->session_begin)(session->backend, session,
                                                      book_id, TRUE, TRUE);
                    PINFO("Done running session_begin on changed backend");
                    err = qof_backend_get_error(session->backend);
                    msg = qof_backend_get_message(session->backend);
                    if (err != ERR_BACKEND_NO_ERR)
                    {
                        g_free(session->book_id);
                        session->book_id = NULL;
                        qof_session_push_error (session, err, msg);
                        LEAVE("changed backend error %d", err);
                        goto leave;
                    }
                    if (msg != NULL)
                    {
                        PWARN("%s", msg);
                        g_free(msg);
                        msg = NULL;
                    }
                }
                /* Tell the books about the backend that they'll be using. */
                for (node = session->books; node; node = node->next)
                {
                    book = node->data;
                    qof_book_set_backend (book, session->backend);
                }
                p = NULL;
            }
            if (p)
            {
                p = p->next;
            }
        }
        if (!session->backend)
        {
            msg = g_strdup_printf("failed to load backend");
            qof_session_push_error(session, ERR_BACKEND_NO_HANDLER, msg);
            goto leave;
        }
    }
    /* If there is a backend, and the backend is reachable
    * (i.e. we can communicate with it), then synchronize with
    * the backend.  If we cannot contact the backend (e.g.
    * because we've gone offline, the network has crashed, etc.)
    * then give the user the option to save to the local disk.
    *
    * hack alert -- FIXME -- XXX the code below no longer
    * does what the words above say.  This needs fixing.
    */
    be = session->backend;
    if (be)
    {
        for (node = session->books; node; node = node->next)
        {
            abook = node->data;
            /* if invoked as SaveAs(), then backend not yet set */
            qof_book_set_backend (abook, be);
            be->percentage = percentage_func;
            if (be->sync)
            {
                (be->sync)(be, abook);
                if (save_error_handler(be, session))
                    goto leave;
            }
        }
        /* If we got to here, then the backend saved everything
        * just fine, and we are done. So return. */
        /* Return the book_id to previous value. */
        qof_session_clear_error (session);
        LEAVE("Success");
        goto leave;
    }
    else
    {
        msg = g_strdup_printf("failed to load backend");
        qof_session_push_error(session, ERR_BACKEND_NO_HANDLER, msg);
    }
    LEAVE("error -- No backend!");
leave:
    if (msg != NULL) g_free(msg);
    g_atomic_int_inc(&session->lock);
    return;
}

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.

Definition at line 1510 of file qofsession.c.

{
    return (session && g_atomic_int_get(&session->lock) != 1);
}

gboolean qof_session_save_may_clobber_data

(

const QofSession *

session

)

Allows the backend to warn the user if a dataset already exists.

Definition at line 1321 of file qofsession.c.

{
    if (!session) return FALSE;
    if (!session->backend) return FALSE;
    if (!session->backend->save_may_clobber_data) return FALSE;

    return (*(session->backend->save_may_clobber_data)) (session->backend);
}

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 1570 of file qofsession.c.

{
    GList *books_1, *books_2, *node;

    if (session_1 == session_2) return;
    if (!session_1 || !session_2) return;

    ENTER ("sess1=%p sess2=%p", session_1, session_2);

    books_1 = session_1->books;
    books_2 = session_2->books;

    session_1->books = books_2;
    session_2->books = books_1;

    for (node = books_1; node; node = node->next)
    {
        QofBook *book_1 = node->data;
        qof_book_set_backend (book_1, session_2->backend);
    }
    for (node = books_2; node; node = node->next)
    {
        QofBook *book_2 = node->data;
        qof_book_set_backend (book_2, session_1->backend);
    }

    LEAVE (" ");
}