Error: Extensible error handling.
[Query Object Framework]


Files

file  qoferror.h
 Extensible error handling.

Defines

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

Typedefs

typedef struct QofError_s QofError

Functions

QofErrorId qof_error_register (const gchar *err_message, gboolean use_file)
 Generate and register a new error.
void qof_error_unregister (QofErrorId id)
 Unregister an error.
void qof_error_set (QofSession *session, QofErrorId error)
 Add an error to the stack for this session.
void qof_error_set_be (QofBackend *be, QofErrorId error)
void qof_error_clear (QofSession *session)
 clear the error stack for the session.
QofErrorId qof_error_check_be (QofBackend *be)
 Check for errors.
QofErrorId qof_error_check (QofSession *session)
QofTimeqof_error_get_time_be (QofBackend *be)
 Get the time of the most recent error.
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.
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.
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

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

00198 {
00199     g_return_val_if_fail (session, QOF_FATAL);
00200     return qof_error_check_be (session->backend);
00201 }

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

00205 {
00206     QofError * qerr;
00207     GList * first;
00208 
00209     if (!be)
00210         return QOF_FATAL;
00211     if (g_list_length (be->error_stack) == 0)
00212         return QOF_SUCCESS;
00213     first = g_list_first (be->error_stack);
00214     qerr = (QofError*)first->data;
00215     if (!qerr)
00216         return QOF_FATAL;
00217     return qerr->id;
00218 }

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.

00183 {
00184     g_return_if_fail (session);
00185     if (!session->backend)
00186         return;
00187     g_list_foreach (session->backend->error_stack, clear_list, NULL);
00188     g_list_free (session->backend->error_stack);
00189     session->backend->error_stack = NULL;
00190     if (session->error_message)
00191         g_free (session->error_message);
00192     session->error_message = NULL;
00193     session->last_err = QOF_SUCCESS;
00194 }

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

00267 {
00268     QofError * qerr;
00269     GList * first;
00270 
00271     if (!be)
00272         return QOF_FATAL;
00273     if (g_list_length (be->error_stack) == 0)
00274         return QOF_SUCCESS;
00275     first = g_list_first (be->error_stack);
00276     qerr = (QofError*)first->data;
00277     if (!qerr)
00278         return QOF_FATAL;
00279     be->error_stack = 
00280         g_list_remove (be->error_stack, qerr);
00281     return qerr->id;
00282 }

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

00299 {
00300     QofError * qerr;
00301     GList * first;
00302 
00303     g_return_val_if_fail (be, NULL);
00304     if (g_list_length (be->error_stack) == 0)
00305     {
00306         DEBUG (" empty error stack");
00307         return NULL;
00308     }
00309     first = g_list_first (be->error_stack);
00310     qerr = (QofError*)first->data;
00311     if (!qerr)
00312     {
00313         DEBUG (" empty QofError value");
00314         return NULL;
00315     }
00316     DEBUG (" qerr->message=%s", qerr->message);
00317     be->error_stack = 
00318         g_list_remove (be->error_stack, qerr);
00319     return qerr->message;
00320 }

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

00222 {
00223     QofError * qerr;
00224     GList * first;
00225 
00226     if (g_list_length(be->error_stack) == 0)
00227         return NULL;
00228     first = g_list_first (be->error_stack);
00229     qerr = (QofError*)first->data;
00230     return qerr->qt;
00231 }

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

00074 {
00075     QofError * qerr;
00076 
00077     ENTER (" ");
00078     qerr = g_new0 (QofError, 1);
00079     count++;
00080     qerr->id = count;
00081     if (use_file)
00082     {
00083         gchar * spec;
00084 
00085         spec = g_strrstr (err_message, "%s");
00086         use_file = (spec) ? TRUE : FALSE;
00087     }
00088     qerr->use_file = use_file;
00089     qerr->message = g_strdup (err_message);
00090     g_hash_table_insert (error_table, GINT_TO_POINTER(qerr->id), qerr);
00091     LEAVE (" ");
00092     return qerr->id;
00093 }

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

00113 {
00114     QofError * qerr, * set;
00115 
00116     g_return_if_fail (session);
00117     if (error == QOF_SUCCESS)
00118     {
00119         DEBUG (" passed success, not error.");
00120         return;
00121     }
00122     qerr = g_hash_table_lookup (error_table, GINT_TO_POINTER(error));
00123     if (!qerr)
00124     {
00125         DEBUG (" failed hash table lookup");
00126         return;
00127     }
00128     session->last_err = error;
00129     if (session->error_message)
00130         g_free (session->error_message);
00131     if (qerr->use_file)
00132         session->error_message = g_strdup_printf (qerr->message,
00133             qof_session_get_url (session));
00134     else
00135         session->error_message = g_strdup (qerr->message);
00136     if (!session->backend)
00137         return;
00138     /* create a new error for the list */
00139     set = g_new0 (QofError, 1);
00140     if (qerr->use_file)
00141         set->message = g_strdup_printf (qerr->message,
00142             qof_session_get_file_path (session));
00143     else
00144         set->message = g_strdup (qerr->message);
00145     set->id = error;
00146     set->qt = qof_time_get_current ();
00147     session->backend->error_stack = 
00148         g_list_prepend (session->backend->error_stack, set);
00149 }

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.

00097 {
00098     QofError * qerr;
00099     gboolean result;
00100 
00101     ENTER (" ");
00102     qerr = g_hash_table_lookup (error_table, GINT_TO_POINTER(id));
00103     qof_error_free (qerr);
00104     result = g_hash_table_remove (error_table, 
00105         GINT_TO_POINTER(id));
00106     if (!result)
00107         LEAVE ("unable to remove registered error.");
00108     LEAVE (" ok.");
00109 }


Generated on Mon Jul 13 05:15:22 2009 for QOF by  doxygen 1.5.9