1 /********************************************************************\ 2 * qofbackend.h: api for data storage backend * 3 * This program is free software; you can redistribute it and/or * 4 * modify it under the terms of the GNU General Public License as * 5 * published by the Free Software Foundation; either version 2 of * 6 * the License, or (at your option) any later version. * 7 * * 8 * This program is distributed in the hope that it will be useful, * 9 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 11 * GNU General Public License for more details. * 12 * * 13 * You should have received a copy of the GNU General Public License* 14 * along with this program; if not, contact: * 15 * * 16 * Free Software Foundation Voice: +1-617-542-5942 * 17 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 18 * Boston, MA 02110-1301, USA gnu@gnu.org * 19 * * 20 \********************************************************************/ 21 /** @addtogroup Object 22 @{ 23 */ 24 /** @addtogroup Backend 25 26 The QOF Backend is a pseudo-object providing an interface between the 27 engine and a persistent data store (e.g. a server, a database, or 28 a file). Backends are not meant to be used directly by an 29 application; instead the Session should be used to make a 30 connection with some particular backend. 31 There are no backend functions that are 'public' to 32 users of the engine. The backend can, however, report errors to 33 the GUI & other front-end users. This file defines these errors. 34 35 Backends are used to save and restore Entities in a Book. 36 @{ 37 */ 38 /** @file qofbackend.h 39 @brief API for data storage Backend 40 @author Copyright (C) 2000-2001 Linas Vepstas <linas@linas.org> 41 @author Copyright 2004-2005 Neil Williams <linux@codehelp.co.uk> 42 */ 43 44 #ifndef QOF_BACKEND_H 45 #define QOF_BACKEND_H 46 47 #include "qofinstance.h" 48 #ifdef __cplusplus 49 extern "C" 50 { 51 #endif 52 53 #define QOF_MOD_BACKEND "qof.backend" 54 55 /** \brief The errors that can be reported to the GUI & other front-end users 56 */ 57 typedef enum 58 { 59 ERR_BACKEND_NO_ERR = 0, 60 ERR_BACKEND_NO_HANDLER, /**< no backend handler found for this access method (ENOSYS) */ 61 ERR_BACKEND_NO_BACKEND, /**< Backend * pointer was unexpectedly null */ 62 ERR_BACKEND_BAD_URL, /**< Can't parse url */ 63 ERR_BACKEND_NO_SUCH_DB, /**< the named database doesn't exist */ 64 ERR_BACKEND_CANT_CONNECT, /**< bad dbname/login/passwd or network failure */ 65 ERR_BACKEND_CONN_LOST, /**< Lost connection to server */ 66 ERR_BACKEND_LOCKED, /**< in use by another user (ETXTBSY) */ 67 ERR_BACKEND_STORE_EXISTS, /**< File exists, data would be destroyed */ 68 ERR_BACKEND_READONLY, /**< cannot write to file/directory */ 69 ERR_BACKEND_TOO_NEW, /**< file/db version newer than what we can read */ 70 ERR_BACKEND_DATA_CORRUPT, /**< data in db is corrupt */ 71 ERR_BACKEND_SERVER_ERR, /**< error in response from server */ 72 ERR_BACKEND_ALLOC, /**< internal memory allocation failure */ 73 ERR_BACKEND_PERM, /**< user login successful, but no permissions 74 to access the desired object */ 75 ERR_BACKEND_MODIFIED, /**< commit of object update failed because 76 another user has modified the object */ 77 ERR_BACKEND_MOD_DESTROY, /**< commit of object update failed because 78 another user has deleted the object */ 79 ERR_BACKEND_MISC, /**< undetermined error */ 80 81 ERR_QOF_OVERFLOW, /**< EOVERFLOW - generated by strtol or strtoll. 82 83 When converting XML strings into numbers, an overflow has been detected. The XML file 84 contains invalid data in a field that is meant to hold a signed long integer or signed long long 85 integer. 86 */ 87 88 /* fileio errors */ 89 ERR_FILEIO_FILE_BAD_READ = 1000, /**< read failed or file prematurely truncated */ 90 ERR_FILEIO_FILE_EMPTY, /**< file exists, is readable, but is empty */ 91 ERR_FILEIO_FILE_LOCKERR, /**< mangled locks (unspecified error) */ 92 ERR_FILEIO_FILE_NOT_FOUND, /**< not found / no such file */ 93 ERR_FILEIO_FILE_TOO_OLD, /**< file version so old we can't read it */ 94 ERR_FILEIO_UNKNOWN_FILE_TYPE, /**< didn't recognize the file type */ 95 ERR_FILEIO_PARSE_ERROR, /**< couldn't parse the data in the file */ 96 ERR_FILEIO_BACKUP_ERROR, /**< couldn't make a backup of the file */ 97 ERR_FILEIO_WRITE_ERROR, /**< couldn't write to the file */ 98 ERR_FILEIO_READ_ERROR, /**< Could not open the file for reading. */ 99 ERR_FILEIO_NO_ENCODING, /**< file does not specify encoding */ 100 ERR_FILEIO_FILE_EACCES, /**< No read access permission for the given file */ 101 ERR_FILEIO_RESERVED_WRITE, /**< User attempt to write to a directory reserved 102 for internal use by GnuCash */ 103 ERR_FILEIO_FILE_UPGRADE, /**< file will be upgraded and not be able to be 104 read by prior versions - warn users*/ 105 106 /* network errors */ 107 ERR_NETIO_SHORT_READ = 2000, /**< not enough bytes received */ 108 ERR_NETIO_WRONG_CONTENT_TYPE, /**< wrong kind of server, wrong data served */ 109 ERR_NETIO_NOT_GNCXML, /**< whatever it is, we can't parse it. */ 110 111 /* database errors */ 112 ERR_SQL_MISSING_DATA = 3000, /**< database doesn't contain expected data */ 113 ERR_SQL_DB_TOO_OLD, /**< database is old and needs upgrading */ 114 ERR_SQL_DB_TOO_NEW, /**< database is newer, we can't write to it */ 115 ERR_SQL_DB_BUSY, /**< database is busy, cannot upgrade version */ 116 ERR_SQL_BAD_DBI, /**< LibDBI has numeric errors */ 117 ERR_SQL_DBI_UNTESTABLE, /**< could not complete test for LibDBI bug */ 118 119 /* RPC errors */ 120 ERR_RPC_HOST_UNK = 4000, /**< Host unknown */ 121 ERR_RPC_CANT_BIND, /**< can't bind to address */ 122 ERR_RPC_CANT_ACCEPT, /**< can't accept connection */ 123 ERR_RPC_NO_CONNECTION, /**< no connection to server */ 124 ERR_RPC_BAD_VERSION, /**< RPC Version Mismatch */ 125 ERR_RPC_FAILED, /**< Operation failed */ 126 ERR_RPC_NOT_ADDED, /**< object not added */ 127 } QofBackendError; 128 129 typedef struct QofBackend QofBackend; 130 131 /* The following functions are used in C files. */ 132 /** Get the last backend error. */ 133 QofBackendError qof_backend_get_error (QofBackend*); 134 /** Set the error on the specified QofBackend. */ 135 void qof_backend_set_error (QofBackend*, QofBackendError); 136 137 /* Temporary wrapper so that we don't have to expose qof-backend.hpp to Transaction.c */ 138 gboolean qof_backend_can_rollback (QofBackend*); 139 void qof_backend_rollback_instance (QofBackend*, QofInstance*); 140 141 /** \brief Load a QOF-compatible backend shared library. 142 143 \param directory Can be NULL if filename is a complete path. 144 \param module_name Name of the .la file that describes the 145 shared library. This provides platform independence, 146 courtesy of libtool. 147 148 \return FALSE in case or error, otherwise TRUE. 149 */ 150 gboolean 151 qof_load_backend_library(const gchar *directory, const gchar* module_name); 152 153 /** \brief Finalize all loaded backend shareable libraries. */ 154 void qof_finalize_backend_libraries(void); 155 156 /** \brief Retrieve the backend used by this book */ 157 QofBackend* qof_book_get_backend (const QofBook *book); 158 159 void qof_book_set_backend (QofBook *book, QofBackend *); 160 161 162 /** \brief DOCUMENT ME! */ 163 typedef void (*QofBePercentageFunc) (/*@ null @*/ const char *message, double percent); 164 165 #ifdef __cplusplus 166 } 167 #endif 168 #endif /* QOF_BACKEND_H */ 169 /** @} */ 170 /** @} */ 171