QOF: Error: Extensible error handling.

QOF 0.7.5

Files | Macros | Typedefs | Functions
Error: Extensible error handling.
Query Object Framework

## 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)
QofTime * | qof_error_get_time_be (QofBackend *be)
| Get the time of the most recent error. More...
QofTime * | qof_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.

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

## ◆ QOF_FATAL

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

## ◆ QOF_MOD_ERROR

#define QOF_MOD_ERROR "qof-error-module"

QofError log_module name.

Definition at line 121 of file qoferror.h.

## ◆ QOF_SUCCESS

#define QOF_SUCCESS 0

success value

Definition at line 124 of file qoferror.h.

## Typedef Documentation

## ◆ QofError

typedef struct QofError_s QofError

opaque QofError type.

Definition at line 118 of file qoferror.h.

## Function Documentation

## ◆ qof_error_check()

QofErrorId qof_error_check | ( | QofSession * | session | ) |

alternative for applications.

Definition at line 227 of file qoferror.c.

228 {
229 g_return_val_if_fail (session, QOF_FATAL);
230 return qof_error_check_be (session->backend);
231 }
qof_error_check_be
QofErrorId qof_error_check_be(QofBackend *be)
Check for errors.
Definition: qoferror.c:234
QOF_FATAL
#define QOF_FATAL
general error value
Definition: qoferror.h:131

## ◆ qof_error_check_be()

QofErrorId qof_error_check_be | ( | QofBackend * | be | ) |

Check for errors.

Parameters

  be | The backend to check.

Returns
  QOF_SUCCESS if no errors have been set, otherwise the QofErrorId of the most recently set error.

Definition at line 234 of file qoferror.c.

235 {
236 QofError * qerr;
237 GList * first;
238
239 if (!be)
240 return QOF_FATAL;
241 if (g_list_length (be->error_stack) == 0)
242 return QOF_SUCCESS;
243 first = g_list_first (be->error_stack);
244 qerr = (QofError*)first->data;
245 if (!qerr)
246 return QOF_FATAL;
247 return qerr->id;
248 }
QofError
struct QofError_s QofError
Definition: qoferror.h:118
QOF_SUCCESS
#define QOF_SUCCESS
Definition: qoferror.h:124
QOF_FATAL
#define QOF_FATAL
general error value
Definition: qoferror.h:131

## ◆ qof_error_clear()

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 209 of file qoferror.c.

210 {
211 g_return_if_fail (session);
212 if (!session->backend)
213 return;
214 g_list_foreach (session->backend->error_stack, clear_list, NULL);
215 g_list_free (session->backend->error_stack);
216 session->backend->error_stack = NULL;
217 if (session->error_message)
218 g_free (session->error_message);
219 session->error_message = NULL;
220 session->last_err = QOF_SUCCESS;
221 #ifndef QOF_DISABLE_DEPRECATED
222 session->backend->last_err = QOF_SUCCESS;
223 #endif
224 }
QofBackend_s::last_err
QofErrorId last_err
Definition: qofbackend-p.h:324
QOF_SUCCESS
#define QOF_SUCCESS
Definition: qoferror.h:124
_QofSession::last_err
QofErrorId last_err
Definition: qofsession-p.h:53
_QofSession::error_message
gchar * error_message
Definition: qofsession-p.h:56

## ◆ qof_error_get_id_be()

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

  be | The 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 314 of file qoferror.c.

315 {
316 QofError * qerr;
317 GList * first;
318
319 if (!be)
320 return QOF_FATAL;
321 if (g_list_length (be->error_stack) == 0)
322 return QOF_SUCCESS;
323 first = g_list_first (be->error_stack);
324 qerr = (QofError*)first->data;
325 if (!qerr)
326 return QOF_FATAL;
327 be->error_stack =
328 g_list_remove (be->error_stack, qerr);
329 #ifndef QOF_DISABLE_DEPRECATED
330 set_previous_error (be);
331 #endif
332 return qerr->id;
333 }
QofError
struct QofError_s QofError
Definition: qoferror.h:118
QOF_SUCCESS
#define QOF_SUCCESS
Definition: qoferror.h:124
QOF_FATAL
#define QOF_FATAL
general error value
Definition: qoferror.h:131

## ◆ qof_error_get_message_be()

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

  be | The 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 364 of file qoferror.c.

365 {
366 QofError * qerr;
367 GList * first;
368
369 g_return_val_if_fail (be, NULL);
370 if (g_list_length (be->error_stack) == 0)
371 {
372 DEBUG (" empty error stack");
373 return NULL;
374 }
375 first = g_list_first (be->error_stack);
376 qerr = (QofError*)first->data;
377 if (!qerr)
378 {
379 DEBUG (" empty QofError value");
380 return NULL;
381 }
382 DEBUG (" qerr->message=%s", qerr->message);
383 be->error_stack =
384 g_list_remove (be->error_stack, qerr);
385 #ifndef QOF_DISABLE_DEPRECATED
386 be->error_msg = qerr->message;
387 set_previous_error (be);
388 #endif
389 return qerr->message;
390 }
QofError
struct QofError_s QofError
Definition: qoferror.h:118
DEBUG
#define DEBUG(format, args...)
Definition: qoflog.h:208
QofBackend_s::error_msg
gchar * error_msg
Definition: qofbackend-p.h:326

## ◆ qof_error_get_time_be()

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

  be | The Backend where the error was set.

Returns
  NULL if no error exists, otherwise the QofTime that the error was set.

Definition at line 251 of file qoferror.c.

252 {
253 QofError * qerr;
254 GList * first;
255
256 if (g_list_length(be->error_stack) == 0)
257 return NULL;
258 first = g_list_first (be->error_stack);
259 qerr = (QofError*)first->data;
260 return qerr->qt;
261 }
QofError
struct QofError_s QofError
Definition: qoferror.h:118

## ◆ qof_error_register()

QofErrorId qof_error_register | ( | const gchar * | err_message,
|  | gboolean | use_file
| ) |  |

Generate and register a new error.

Parameters

  err_message | The user-friendly string to add as an error, already marked for translation.
  use_file | TRUE 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 91 of file qoferror.c.

92 {
93 QofError * qerr;
94
95 ENTER (" ");
96 qerr = g_new0 (QofError, 1);
97 count++;
98 #ifndef QOF_DISABLE_DEPRECATED
99 count += ERR_LAST;
100 #endif
101 qerr->id = count;
102 if (use_file)
103 {
104 gchar * spec;
105
106 spec = g_strrstr (err_message, "%s");
107 use_file = (spec) ? TRUE : FALSE;
108 }
109 qerr->use_file = use_file;
110 qerr->message = g_strdup (err_message);
111 g_hash_table_insert (error_table, GINT_TO_POINTER(qerr->id), qerr);
112 LEAVE (" ");
113 return qerr->id;
114 }
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
QofError
struct QofError_s QofError
Definition: qoferror.h:118
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qof_error_set()

void qof_error_set | ( | QofSession * | session,
|  | QofErrorId | error
| ) |  |

Add an error to the stack for this session.

Parameters

  session | The session that raised the error.
  error | The QofErrorId of the error to be recorded.

Definition at line 133 of file qoferror.c.

134 {
135 QofError * qerr, * set;
136
137 g_return_if_fail (session);
138 if (error == QOF_SUCCESS)
139 {
140 DEBUG (" passed success, not error.");
141 return;
142 }
143 qerr = g_hash_table_lookup (error_table, GINT_TO_POINTER(error));
144 if (!qerr)
145 {
146 DEBUG (" failed hash table lookup");
147 return;
148 }
149 session->last_err = error;
150 if (session->error_message)
151 g_free (session->error_message);
152 if (qerr->use_file)
153 session->error_message = g_strdup_printf (qerr->message,
154 qof_session_get_url (session));
155 else
156 session->error_message = g_strdup (qerr->message);
157 if (!session->backend)
158 return;
159 /* create a new error for the list */
160 set = g_new0 (QofError, 1);
161 if (qerr->use_file)
162 set->message = g_strdup_printf (qerr->message,
163 qof_session_get_file_path (session));
164 else
165 set->message = g_strdup (qerr->message);
166 set->id = error;
167 set->qt = qof_time_get_current ();
168 session->backend->error_stack =
169 g_list_prepend (session->backend->error_stack, set);
170 #ifndef QOF_DISABLE_DEPRECATED
171 session->backend->last_err = error;
172 #endif
173 }
qof_time_get_current
QofTime * qof_time_get_current(void)
Get the current QofTime.
Definition: qoftime.c:362
QofBackend_s::last_err
QofErrorId last_err
Definition: qofbackend-p.h:324
QofError
struct QofError_s QofError
Definition: qoferror.h:118
QOF_SUCCESS
#define QOF_SUCCESS
Definition: qoferror.h:124
DEBUG
#define DEBUG(format, args...)
Definition: qoflog.h:208
qof_session_get_file_path
const gchar * qof_session_get_file_path(QofSession *session)
Definition: qofsession.c:192
_QofSession::last_err
QofErrorId last_err
Definition: qofsession-p.h:53
_QofSession::error_message
gchar * error_message
Definition: qofsession-p.h:56

## ◆ qof_error_unregister()

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 117 of file qoferror.c.

118 {
119 QofError * qerr;
120 gboolean result;
121
122 ENTER (" ");
123 qerr = g_hash_table_lookup (error_table, GINT_TO_POINTER(id));
124 qof_error_free (qerr);
125 result = g_hash_table_remove (error_table,
126 GINT_TO_POINTER(id));
127 if (!result)
128 LEAVE ("unable to remove registered error.");
129 LEAVE (" ok.");
130 }
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
QofError
struct QofError_s QofError
Definition: qoferror.h:118
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217