/usr/include/qof/qoferror.h is in libqof-dev 0.8.4-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 | /********************************************************************
* qoferror.h
*
* Sun Sep 10 19:55:48 2006
* Copyright 2006 Neil Williams
* linux@codehelp.co.uk
*******************************************************************/
/*
* 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, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef _QOFERROR_H
#define _QOFERROR_H
#include "qofsession.h"
/** @addtogroup Error
QofError supports the creation of new error codes (complete with
error strings) along the lines of GdaError. Applications and
backends can generate their own QofError values and register them
with QofError. Any function can then set this error value and
retrieve the error with ::qof_error_get_id or
::qof_error_get_message. The main advantage is that
applications can set error states that are unrelated to the old
QofBackendError values but retrieve all errors in the same manner.
- Use QofLog to record information for programmers and maintainers.
- Use QofError to communicate descriptive error messages to the user.
An error must be registered to be set. Registered errors can be
set repeatedly into an error stack for the relevant session.
Setting an error copies the registered error to the error stack
and sets a time index in the copy.
Once an error has been unregistered, it cannot be set later.
If the error has already been set on the error stack, the
stack is \b not changed and the error remains readable.
Each error stack is specific to one QofSession.
Registered errors can be set in any session (if the
QofErrorId is known) but most errors are specific to one session.
Applications can register new error values with ::qof_error_register
passing the error message string, already marked for translation -
a new QofErrorId will be returned. Error values are unregistered
when the session ends or can be unregistered manually.
Each backend can also generate specific QofError values, in
which case the translation is done within QOF.
Set an error by passing the QofErrorId (or the deprecated
QofBackendError) to ::qof_error_set.
To check the error condition use ::qof_error_check - if an error
has been set, qof_error_check returns the QofErrorId of that error
without clearing the error from the stack.
To retrieve an error and clear it from the stack, use
::qof_error_get_id or ::qof_error_get_message.
Precise values of QofErrorId are \b not to be stored in applications
as values (other than deprecated values) may change at any time.
There are no default errors - previous QofBackendError values
are retained only as deprecated macros. Until libqof2, QofErrorId
is guaranteed not to overlap a previous QofBackendError value but
once deprecated code is removed in libqof2, any value can be used.
This deliberately makes it harder to re-use the same error time
after time. The purpose is to encourage more detailed error
reporting by supporting an unlimited number of error values.
Applications and backends can store the QofErrorId in a context
or static values if the error must be set from multiple locations,
otherwise an error can be registered and set locally.
If a subsystem or dependency generates an error message of it's own,
this can also be passed to qof_error_register to generate a new
error within the session, complete with the (translated) message
direct from the subsystem. This increases the detail and clarity
of the messages presented to the user. Programming errors and
complex errors should still be logged using QofLog - QofError
is for messages destined for the end user of the application using
QOF.
Many applications already include message strings for the previous
QofBackendError values but all are welcome to move to the new
QofError strings.
QofError strings remain the property of QofError and should not
be freed.
@since 0.7.2
@{
*/
/** @file qoferror.h
@brief Extensible error handling
@author Copyright 2006 Neil Williams <linux@codehelp.co.uk>
*/
/** opaque QofError type. */
typedef struct QofError_s QofError;
/** QofError log_module name. */
#define QOF_MOD_ERROR "qof-error-module"
/** success value */
#define QOF_SUCCESS 0
/** \brief general error value
Can be returned by any function handling QofErrorId
to indicate a fatal error, e.g. g_return_val_if_fail
*/
#define QOF_FATAL -1
/** \brief Generate and register a new error
@param err_message The user-friendly string to add as
an error, already marked for translation.
@param use_file TRUE if the session filename should be
substituted in the string - err_message \b must
contain a bare string format specifier: %s. Note that
flags, width, precision or size specifiers are \b not
accepted and the filename is output in full,
complete with the access_method.
e.g. file:/home/user/app/data.xml
To use a different presentation of the filename or other
customised strings, prepare the error message before
registering it with QofError.
Registered errors are cleared when the session is destroyed.
Applications need to plan the use of locally registered
error codes so that the same errors are not repeatedly
registered.
@return The QofErrorId of this error.
*/
QofErrorId
qof_error_register (const gchar * err_message, gboolean use_file);
/** \brief Unregister an error
Registered errors are normally freed when the session ends.
Errors can also be unregistered (and freed) directly.
An unregistered error can not be set later.
*/
void
qof_error_unregister (QofErrorId id);
/** \brief Add an error to the stack for this session.
@param session The session that raised the error.
@param error The QofErrorId of the error to be recorded.
*/
void
qof_error_set (QofSession * session, QofErrorId error);
void
qof_error_set_be (QofBackend * be, QofErrorId error);
/** \brief clear the error stack for the session.
Applications should clear the stack once errors have been
presented to the user.
*/
void
qof_error_clear (QofSession * session);
/** \brief Check for errors
@param be The backend to check.
@return QOF_SUCCESS if no errors have been set, otherwise
the QofErrorId of the most recently set error.
*/
QofErrorId
qof_error_check_be (QofBackend * be);
/** alternative for applications. */
QofErrorId
qof_error_check (QofSession * session);
/** \brief Get the time of the most recent error
All QofError values are timestamped at the moment
that the error is set.
@param be The Backend where the error was set.
@return NULL if no error exists, otherwise the QofTime
that the error was set.
*/
QofTime *
qof_error_get_time_be (QofBackend * be);
/** \brief Alternative for applications */
QofTime *
qof_error_get_time (QofSession * session);
/** @brief Pop the most recent error from the backend stack
Returns and clears the most recently set error for this
backend, if any.
@param be The Backend that recorded the error.
@return QOF_SUCCESS if no errors have been set, otherwise
the QofErrorId of the most recently set error.
*/
QofErrorId
qof_error_get_id_be (QofBackend * be);
/** \brief Alternative for applications */
QofErrorId
qof_error_get_id (QofSession * session);
/** @brief Pop the most recent error and get the message.
Clears the most recently set error for this backend and
returns the error message, if any.
@param be The Backend that recorded the error.
@return NULL if no errors have been set, otherwise
the translated message for the most recently set error.
*/
const gchar *
qof_error_get_message_be (QofBackend * be);
/** \brief Alternative for applications. */
const gchar *
qof_error_get_message (QofSession * session);
/** @} */
#endif /* _QOFERROR_H */
|