/********************************************************************\ * qofbackend.h: api for data storage backend * * This program is free software; you can redistribute it and/or * * modify it under the terms of the GNU General Public License as * * published by the Free Software Foundation; either version 2 of * * the License, or (at your option) any later version. * * * * This program is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * * GNU General Public License for more details. * * * * You should have received a copy of the GNU General Public License* * along with this program; if not, contact: * * * * Free Software Foundation Voice: +1-617-542-5942 * * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * * Boston, MA 02110-1301, USA gnu@gnu.org * * * \********************************************************************/ /** @addtogroup Object @{ */ /** @addtogroup Backend The QOF Backend is a pseudo-object providing an interface between the engine and a persistent 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. @{ */ /** @file qofbackend.h @brief API for data storage Backend @author Copyright (C) 2000-2001 Linas Vepstas @author Copyright 2004-2005 Neil Williams */ #ifndef QOF_BACKEND_H #define QOF_BACKEND_H #include "qofinstance.h" #ifdef __cplusplus extern "C" { #endif #define QOF_MOD_BACKEND "qof.backend" /** \brief The errors that can be reported to the GUI & other front-end users */ typedef enum { ERR_BACKEND_NO_ERR = 0, 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. */ /* fileio errors */ ERR_FILEIO_FILE_BAD_READ = 1000, /**< 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*/ /* network errors */ ERR_NETIO_SHORT_READ = 2000, /**< 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. */ /* database errors */ ERR_SQL_MISSING_DATA = 3000, /**< 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 */ /* RPC errors */ ERR_RPC_HOST_UNK = 4000, /**< 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 */ } QofBackendError; typedef struct QofBackend QofBackend; /* The following functions are used in C files. */ /** Get the last backend error. */ QofBackendError qof_backend_get_error (QofBackend*); /** Set the error on the specified QofBackend. */ void qof_backend_set_error (QofBackend*, QofBackendError); /* Temporary wrapper so that we don't have to expose qof-backend.hpp to Transaction.c */ gboolean qof_backend_can_rollback (QofBackend*); void qof_backend_rollback_instance (QofBackend*, QofInstance*); /** \brief Load a QOF-compatible backend shared library. \param directory Can be NULL if filename is a complete path. \param module_name Name of the .la file that describes the shared library. This provides platform independence, courtesy of libtool. \return FALSE in case or error, otherwise TRUE. */ gboolean qof_load_backend_library(const gchar *directory, const gchar* module_name); /** \brief Finalize all loaded backend shareable libraries. */ void qof_finalize_backend_libraries(void); /** \brief Retrieve the backend used by this book */ QofBackend* qof_book_get_backend (const QofBook *book); void qof_book_set_backend (QofBook *book, QofBackend *); /** \brief DOCUMENT ME! */ typedef void (*QofBePercentageFunc) (/*@ null @*/ const char *message, double percent); #ifdef __cplusplus } #endif #endif /* QOF_BACKEND_H */ /** @} */ /** @} */