GnuCash  3.7-134-g71bdcdfa6+
Public Member Functions | Static Public Member Functions | Protected Attributes
Inheritance diagram for QofBackend:
GncSqlBackend GncXmlBackend GncDbiBackend< Type >

Public Member Functions

 QofBackend (const QofBackend &)=delete
 
 QofBackend (const QofBackend &&)=delete
 
virtual void session_begin (QofSession *session, const char *book_id, bool ignore_lock, bool create, bool force)=0
 Open the file or connect to the server. More...
 
virtual void session_end ()=0
 
virtual void load (QofBook *, QofBackendLoadType)=0
 Load the minimal set of application data needed for the application to be operable at initial startup. More...
 
virtual void begin (QofInstance *)
 Called when the engine is about to make a change to a data structure. More...
 
virtual void commit (QofInstance *)
 Commits the changes from the engine to the backend data storage.
 
virtual void rollback (QofInstance *)
 Revert changes in the engine and unlock the backend.
 
virtual void sync (QofBook *)=0
 Synchronizes the engine contents to the backend. More...
 
virtual void safe_sync (QofBook *)=0
 Perform a sync in a way that prevents data loss on a DBI backend.
 
virtual void export_coa (QofBook *)
 Extract the chart of accounts from the current database and create a new database with it. More...
 
void set_error (QofBackendError err)
 Set the error value only if there isn't already an error already.
 
QofBackendError get_error ()
 Retrieve the currently-stored error and clear it.
 
bool check_error ()
 Report if there is an error.
 
void set_message (std::string &&)
 Set a descriptive message that can be displayed to the user when there's an error.
 
const std::string && get_message ()
 Retrieve and clear the stored error message.
 
void set_percentage (QofBePercentageFunc pctfn)
 Store and retrieve a backend-specific function for determining the progress in completing a long operation, for use with a progress meter.
 
QofBePercentageFunc get_percentage ()
 
std::string get_uri ()
 Retrieve the backend's storage URI.
 

Static Public Member Functions

static bool register_backend (const char *, const char *)
 Class methods for dynamically loading the several backends and for freeing them at shutdown.
 
static void release_backends ()
 

Protected Attributes

QofBePercentageFunc m_percentage
 
std::string m_fullpath
 Each backend resolves a fully-qualified file path. More...
 

Detailed Description

Definition at line 172 of file qof-backend.hpp.

Member Function Documentation

◆ begin()

virtual void QofBackend::begin ( QofInstance *  )
inlinevirtual

Called when the engine is about to make a change to a data structure.

It could provide an advisory lock on data, but no backend does this.

Reimplemented in GncSqlBackend.

Definition at line 234 of file qof-backend.hpp.

234 {}

◆ export_coa()

virtual void QofBackend::export_coa ( QofBook *  )
inlinevirtual

Extract the chart of accounts from the current database and create a new database with it.

Implemented only in the XML backend at present.

Reimplemented in GncXmlBackend.

Definition at line 267 of file qof-backend.hpp.

267 {}

◆ load()

virtual void QofBackend::load ( QofBook *  ,
QofBackendLoadType   
)
pure virtual

Load the minimal set of application data needed for the application to be operable at initial startup.

It is assumed that the application will perform a 'run_query()' to obtain any additional data that it needs. For file-based backends, it is acceptable for the backend to return all data at load time; for SQL-based backends, it is acceptable for the backend to return no data.

Thus, for example, the old GnuCash postgres backend returned the account tree, all currencies, and the pricedb, as these were needed at startup. It did not have to return any transactions whatsoever, as these were obtained at a later stage when a user opened a register, resulting in a query being sent to the backend. The current DBI backend on the other hand loads the entire database into memory.

(Its OK to send over entities at this point, but one should be careful of the network load; also, its possible that whatever is sent is not what the user wanted anyway, which is why its better to wait for the query).

Implemented in GncDbiBackend< Type >, GncSqlBackend, and GncXmlBackend.

◆ session_begin()

virtual void QofBackend::session_begin ( QofSession *  session,
const char *  book_id,
bool  ignore_lock,
bool  create,
bool  force 
)
pure virtual

Open the file or connect to the server.

Parameters
sessionThe QofSession that will control the backend.
book_idThe book's string identifier.
ignore_lockindicates whether the single-user lock on the backend should be cleared. The typical GUI sequence leading to this is: (1) GUI attempts to open the backend by calling this routine with ignore_lock false. (2) If backend error'ed BACKEND_LOCK, then GUI asks user what to do. (3) if user answers 'break & enter' then this routine is called again with ignore_lock true.
createindicates whether this routine should create a new 'database', if it doesn't already exist. For example, for a file-backend, this would create the file, if it didn't already exist. For an SQL backend, this would create the database (the schema) if it didn't already exist. This flag is used to implement the 'SaveAs' GUI, where the user requests to save data to a new backend.
forceworks with create to force creating a new database even if one already exists at the same URI.

Implemented in GncDbiBackend< Type >, GncDbiBackend< Type >, and GncXmlBackend.

◆ sync()

virtual void QofBackend::sync ( QofBook *  )
pure virtual

Synchronizes the engine contents to the backend.

This should done by using version numbers (hack alert – the engine does not currently contain version numbers). If the engine contents are newer than what is in the backend, the data is stored to the backend. If the engine contents are older, then the engine contents are updated.

Note that this sync operation is only meant to apply to the current contents of the engine. This routine is not intended to be used to fetch entity data from the backend.

File based backends tend to use sync as if it was called dump. Data is written out into the backend, overwriting the previous data. Database backends should implement a more intelligent solution.

Implemented in GncSqlBackend, and GncXmlBackend.

Field Documentation

◆ m_fullpath

std::string QofBackend::m_fullpath
protected

Each backend resolves a fully-qualified file path.

This holds the filepath and communicates it to the frontends.

Definition at line 303 of file qof-backend.hpp.


The documentation for this struct was generated from the following files: