QOF  0.8.7
Files | Macros | Typedefs | Functions
Error: Extensible error handling.

Files

file  qoferror.h
 Extensible error handling.
 

Macros

#define QOF_MOD_ERROR   "qof-error-module"
 
#define QOF_SUCCESS   0
 
#define QOF_FATAL   -1
 general error value More...
 

Typedefs

typedef struct QofError_s QofError
 

Functions

QofErrorId qof_error_register (const gchar *err_message, gboolean use_file)
 Generate and register a new error. More...
 
void qof_error_unregister (QofErrorId id)
 Unregister an error. More...
 
void qof_error_set (QofSession *session, QofErrorId error)
 Add an error to the stack for this session. More...
 
void qof_error_set_be (QofBackend *be, QofErrorId error)
 
void qof_error_clear (QofSession *session)
 clear the error stack for the session. More...
 
QofErrorId qof_error_check_be (QofBackend *be)
 Check for errors. More...
 
QofErrorId qof_error_check (QofSession *session)
 
QofTimeqof_error_get_time_be (QofBackend *be)
 Get the time of the most recent error. More...
 
QofTimeqof_error_get_time (QofSession *session)
 Alternative for applications.
 
QofErrorId qof_error_get_id_be (QofBackend *be)
 Pop the most recent error from the backend stack. More...
 
QofErrorId qof_error_get_id (QofSession *session)
 Alternative for applications.
 
const gchar * qof_error_get_message_be (QofBackend *be)
 Pop the most recent error and get the message. More...
 
const gchar * qof_error_get_message (QofSession *session)
 Alternative for applications.
 

Detailed Description

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.

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

Macro Definition Documentation

#define QOF_FATAL   -1

general error value

Can be returned by any function handling QofErrorId to indicate a fatal error, e.g. g_return_val_if_fail

Definition at line 131 of file qoferror.h.

#define QOF_MOD_ERROR   "qof-error-module"

QofError log_module name.

Definition at line 121 of file qoferror.h.

#define QOF_SUCCESS   0

success value

Definition at line 124 of file qoferror.h.

Typedef Documentation

typedef struct QofError_s QofError

opaque QofError type.

Definition at line 118 of file qoferror.h.

Function Documentation

QofErrorId qof_error_check ( QofSession session)

alternative for applications.

Definition at line 197 of file qoferror.c.

198 {
199  g_return_val_if_fail (session, QOF_FATAL);
200  return qof_error_check_be (session->backend);
201 }
QofErrorId qof_error_check_be(QofBackend *be)
Check for errors.
Definition: qoferror.c:204
#define QOF_FATAL
general error value
Definition: qoferror.h:131
QofErrorId qof_error_check_be ( QofBackend be)

Check for errors.

Parameters
beThe backend to check.
Returns
QOF_SUCCESS if no errors have been set, otherwise the QofErrorId of the most recently set error.

Definition at line 204 of file qoferror.c.

205 {
206  QofError * qerr;
207  GList * first;
208 
209  if (!be)
210  return QOF_FATAL;
211  if (g_list_length (be->error_stack) == 0)
212  return QOF_SUCCESS;
213  first = g_list_first (be->error_stack);
214  qerr = (QofError*)first->data;
215  if (!qerr)
216  return QOF_FATAL;
217  return qerr->id;
218 }
struct QofError_s QofError
Definition: qoferror.h:118
#define QOF_SUCCESS
Definition: qoferror.h:124
#define QOF_FATAL
general error value
Definition: qoferror.h:131
void qof_error_clear ( QofSession session)

clear the error stack for the session.

Applications should clear the stack once errors have been presented to the user.

Definition at line 182 of file qoferror.c.

183 {
184  g_return_if_fail (session);
185  if (!session->backend)
186  return;
187  g_list_foreach (session->backend->error_stack, clear_list, NULL);
188  g_list_free (session->backend->error_stack);
189  session->backend->error_stack = NULL;
190  if (session->error_message)
191  g_free (session->error_message);
192  session->error_message = NULL;
193  session->last_err = QOF_SUCCESS;
194 }
#define QOF_SUCCESS
Definition: qoferror.h:124
QofErrorId last_err
Definition: qofsession-p.h:53
gchar * error_message
Definition: qofsession-p.h:56
QofErrorId qof_error_get_id_be ( QofBackend be)

Pop the most recent error from the backend stack.

Returns and clears the most recently set error for this backend, if any.

Parameters
beThe Backend that recorded the error.
Returns
QOF_SUCCESS if no errors have been set, otherwise the QofErrorId of the most recently set error.

Definition at line 266 of file qoferror.c.

267 {
268  QofError * qerr;
269  GList * first;
270 
271  if (!be)
272  return QOF_FATAL;
273  if (g_list_length (be->error_stack) == 0)
274  return QOF_SUCCESS;
275  first = g_list_first (be->error_stack);
276  qerr = (QofError*)first->data;
277  if (!qerr)
278  return QOF_FATAL;
279  be->error_stack =
280  g_list_remove (be->error_stack, qerr);
281  return qerr->id;
282 }
struct QofError_s QofError
Definition: qoferror.h:118
#define QOF_SUCCESS
Definition: qoferror.h:124
#define QOF_FATAL
general error value
Definition: qoferror.h:131
const gchar* qof_error_get_message_be ( QofBackend be)

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.

Parameters
beThe Backend that recorded the error.
Returns
NULL if no errors have been set, otherwise the translated message for the most recently set error.

Definition at line 298 of file qoferror.c.

299 {
300  QofError * qerr;
301  GList * first;
302 
303  g_return_val_if_fail (be, NULL);
304  if (g_list_length (be->error_stack) == 0)
305  {
306  DEBUG (" empty error stack");
307  return NULL;
308  }
309  first = g_list_first (be->error_stack);
310  qerr = (QofError*)first->data;
311  if (!qerr)
312  {
313  DEBUG (" empty QofError value");
314  return NULL;
315  }
316  DEBUG (" qerr->message=%s", qerr->message);
317  be->error_stack =
318  g_list_remove (be->error_stack, qerr);
319  return qerr->message;
320 }
struct QofError_s QofError
Definition: qoferror.h:118
#define DEBUG(format, args...)
Definition: qoflog.h:208
QofTime* qof_error_get_time_be ( QofBackend be)

Get the time of the most recent error.

All QofError values are timestamped at the moment that the error is set.

Parameters
beThe Backend where the error was set.
Returns
NULL if no error exists, otherwise the QofTime that the error was set.

Definition at line 221 of file qoferror.c.

222 {
223  QofError * qerr;
224  GList * first;
225 
226  if (g_list_length(be->error_stack) == 0)
227  return NULL;
228  first = g_list_first (be->error_stack);
229  qerr = (QofError*)first->data;
230  return qerr->qt;
231 }
struct QofError_s QofError
Definition: qoferror.h:118
QofErrorId qof_error_register ( const gchar *  err_message,
gboolean  use_file 
)

Generate and register a new error.

Parameters
err_messageThe user-friendly string to add as an error, already marked for translation.
use_fileTRUE if the session filename should be substituted in the string - err_message must contain a bare string format specifier: s. Note that flags, width, precision or size specifiers are 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.

Returns
The QofErrorId of this error.

Definition at line 73 of file qoferror.c.

74 {
75  QofError * qerr;
76 
77  ENTER (" ");
78  qerr = g_new0 (QofError, 1);
79  count++;
80  qerr->id = count;
81  if (use_file)
82  {
83  gchar * spec;
84 
85  spec = g_strrstr (err_message, "%s");
86  use_file = (spec) ? TRUE : FALSE;
87  }
88  qerr->use_file = use_file;
89  qerr->message = g_strdup (err_message);
90  g_hash_table_insert (error_table, GINT_TO_POINTER(qerr->id), qerr);
91  LEAVE (" ");
92  return qerr->id;
93 }
#define LEAVE(format, args...)
Definition: qoflog.h:227
struct QofError_s QofError
Definition: qoferror.h:118
#define ENTER(format, args...)
Definition: qoflog.h:217
void qof_error_set ( QofSession session,
QofErrorId  error 
)

Add an error to the stack for this session.

Parameters
sessionThe session that raised the error.
errorThe QofErrorId of the error to be recorded.

Definition at line 112 of file qoferror.c.

113 {
114  QofError * qerr, * set;
115 
116  g_return_if_fail (session);
117  if (error == QOF_SUCCESS)
118  {
119  DEBUG (" passed success, not error.");
120  return;
121  }
122  qerr = g_hash_table_lookup (error_table, GINT_TO_POINTER(error));
123  if (!qerr)
124  {
125  DEBUG (" failed hash table lookup");
126  return;
127  }
128  session->last_err = error;
129  if (session->error_message)
130  g_free (session->error_message);
131  if (qerr->use_file)
132  session->error_message = g_strdup_printf (qerr->message,
133  qof_session_get_url (session));
134  else
135  session->error_message = g_strdup (qerr->message);
136  if (!session->backend)
137  return;
138  /* create a new error for the list */
139  set = g_new0 (QofError, 1);
140  if (qerr->use_file)
141  set->message = g_strdup_printf (qerr->message,
142  qof_session_get_file_path (session));
143  else
144  set->message = g_strdup (qerr->message);
145  set->id = error;
146  set->qt = qof_time_get_current ();
147  session->backend->error_stack =
148  g_list_prepend (session->backend->error_stack, set);
149 }
QofTime * qof_time_get_current(void)
Get the current QofTime.
Definition: qoftime.c:362
struct QofError_s QofError
Definition: qoferror.h:118
#define QOF_SUCCESS
Definition: qoferror.h:124
#define DEBUG(format, args...)
Definition: qoflog.h:208
const gchar * qof_session_get_file_path(QofSession *session)
Definition: qofsession.c:189
QofErrorId last_err
Definition: qofsession-p.h:53
gchar * error_message
Definition: qofsession-p.h:56
void qof_error_unregister ( QofErrorId  id)

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.

Definition at line 96 of file qoferror.c.

97 {
98  QofError * qerr;
99  gboolean result;
100 
101  ENTER (" ");
102  qerr = g_hash_table_lookup (error_table, GINT_TO_POINTER(id));
103  qof_error_free (qerr);
104  result = g_hash_table_remove (error_table,
105  GINT_TO_POINTER(id));
106  if (!result)
107  LEAVE ("unable to remove registered error.");
108  LEAVE (" ok.");
109 }
#define LEAVE(format, args...)
Definition: qoflog.h:227
struct QofError_s QofError
Definition: qoferror.h:118
#define ENTER(format, args...)
Definition: qoflog.h:217