glib/gerror.h

   1 /* gerror.h - Error reporting system
   2  *
   3  *  Copyright 2000 Red Hat, Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public License
  16  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef __G_ERROR_H__
  20 #define __G_ERROR_H__
  21
  22 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  23 #error "Only <glib.h> can be included directly."
  24 #endif
  25
  26 #include <stdarg.h>
  27
  28 #include <glib/gquark.h>
  29
  30 G_BEGIN_DECLS
  31
  32 /**
  33  * GError:
  34  * @domain: error domain, e.g. #G_FILE_ERROR
  35  * @code: error code, e.g. %G_FILE_ERROR_NOENT
  36  * @message: human-readable informative error message
  37  *
  38  * The `GError` structure contains information about
  39  * an error that has occurred.
  40  */
  41 typedef struct _GError GError;
  42
  43 struct _GError
  44 {
  45   GQuark       domain;
  46   gint         code;
  47   gchar       *message;
  48 };
  49
  50 /**
  51  * G_DEFINE_EXTENDED_ERROR:
  52  * @ErrorType: name to return a #GQuark for
  53  * @error_type: prefix for the function name
  54  *
  55  * A convenience macro which defines two functions. First, returning
  56  * the #GQuark for the extended error type @ErrorType; it is called
  57  * `@error_type_quark()`. Second, returning the private data from a
  58  * passed #GError; it is called `@error_type_get_private()`.
  59  *
  60  * For this macro to work, a type named `@ErrorTypePrivate` should be
  61  * defined, `@error_type_private_init()`, `@error_type_private_copy()`
  62  * and `@error_type_private_clear()` functions need to be either
  63  * declared or defined. The functions should be similar to
  64  * #GErrorInitFunc, #GErrorCopyFunc and #GErrorClearFunc,
  65  * respectively, but they should receive the private data type instead
  66  * of #GError.
  67  *
  68  * Since: 2.68
  69  */
  70 #define G_DEFINE_EXTENDED_ERROR(ErrorType, error_type)                  \
  71 static inline ErrorType ## Private *                                    \
  72 error_type ## _get_private (const GError *error)                        \
  73 {                                                                       \
  74   /* Copied from gtype.c (STRUCT_ALIGNMENT and ALIGN_STRUCT macros). */ \
  75   const gsize sa = 2 * sizeof (gsize);                                  \
  76   const gsize as = (sizeof (ErrorType ## Private) + (sa - 1)) & -sa;    \
  77   g_return_val_if_fail (error != NULL, NULL);                           \
  78   g_return_val_if_fail (error->domain == error_type ## _quark (), NULL); \
  79   return (ErrorType ## Private *) (((guint8 *)error) - as); \
  80 }                                                                       \
  81                                                                         \
  82 static void                                                             \
  83 g_error_with_ ## error_type ## _private_init (GError *error)            \
  84 {                                                                       \
  85   ErrorType ## Private *priv = error_type ## _get_private (error);      \
  86   error_type ## _private_init (priv);                                   \
  87 }                                                                       \
  88                                                                         \
  89 static void                                                             \
  90 g_error_with_ ## error_type ## _private_copy (const GError *src_error,  \
  91                                               GError       *dest_error) \
  92 {                                                                       \
  93   const ErrorType ## Private *src_priv = error_type ## _get_private (src_error);  \
  94   ErrorType ## Private *dest_priv = error_type ## _get_private (dest_error); \
  95   error_type ## _private_copy (src_priv, dest_priv);                    \
  96 }                                                                       \
  97                                                                         \
  98 static void                                                             \
  99 g_error_with_ ## error_type ## _private_clear (GError *error)           \
 100 {                                                                       \
 101   ErrorType ## Private *priv = error_type ## _get_private (error);      \
 102   error_type ## _private_clear (priv);                                  \
 103 }                                                                       \
 104                                                                         \
 105 GQuark                                                                  \
 106 error_type ## _quark (void)                                             \
 107 {                                                                       \
 108   static GQuark q;                                                      \
 109   static gsize initialized = 0;                                         \
 110                                                                         \
 111   if (g_once_init_enter (&initialized))                                 \
 112     {                                                                   \
 113       q = g_error_domain_register_static (#ErrorType,                   \
 114                                           sizeof (ErrorType ## Private), \
 115                                           g_error_with_ ## error_type ## _private_init, \
 116                                           g_error_with_ ## error_type ## _private_copy, \
 117                                           g_error_with_ ## error_type ## _private_clear); \
 118       g_once_init_leave (&initialized, 1);                              \
 119     }                                                                   \
 120                                                                         \
 121   return q;                                                             \
 122 }
 123
 124 /**
 125  * GErrorInitFunc:
 126  * @error: extended error
 127  *
 128  * Specifies the type of function which is called just after an
 129  * extended error instance is created and its fields filled. It should
 130  * only initialize the fields in the private data, which can be
 131  * received with the generated `*_get_private()` function.
 132  *
 133  * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
 134  * already takes care of getting the private data from @error.
 135  *
 136  * Since: 2.68
 137  */
 138 typedef void (*GErrorInitFunc) (GError *error);
 139
 140 /**
 141  * GErrorCopyFunc:
 142  * @src_error: source extended error
 143  * @dest_error: destination extended error
 144  *
 145  * Specifies the type of function which is called when an extended
 146  * error instance is copied. It is passed the pointer to the
 147  * destination error and source error, and should copy only the fields
 148  * of the private data from @src_error to @dest_error.
 149  *
 150  * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
 151  * already takes care of getting the private data from @src_error and
 152  * @dest_error.
 153  *
 154  * Since: 2.68
 155  */
 156 typedef void (*GErrorCopyFunc) (const GError *src_error, GError *dest_error);
 157
 158 /**
 159  * GErrorClearFunc:
 160  * @error: extended error to clear
 161  *
 162  * Specifies the type of function which is called when an extended
 163  * error instance is freed. It is passed the error pointer about to be
 164  * freed, and should free the error's private data fields.
 165  *
 166  * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
 167  * already takes care of getting the private data from @error.
 168  *
 169  * Since: 2.68
 170  */
 171 typedef void (*GErrorClearFunc) (GError *error);
 172
 173 GLIB_AVAILABLE_IN_2_68
 174 GQuark   g_error_domain_register_static (const char        *error_type_name,
 175                                          gsize              error_type_private_size,
 176                                          GErrorInitFunc     error_type_init,
 177                                          GErrorCopyFunc     error_type_copy,
 178                                          GErrorClearFunc    error_type_clear);
 179
 180 GLIB_AVAILABLE_IN_2_68
 181 GQuark   g_error_domain_register (const char        *error_type_name,
 182                                   gsize              error_type_private_size,
 183                                   GErrorInitFunc     error_type_init,
 184                                   GErrorCopyFunc     error_type_copy,
 185                                   GErrorClearFunc    error_type_clear);
 186
 187 GLIB_AVAILABLE_IN_ALL
 188 GError*  g_error_new           (GQuark         domain,
 189                                 gint           code,
 190                                 const gchar   *format,
 191                                 ...) G_GNUC_PRINTF (3, 4);
 192
 193 GLIB_AVAILABLE_IN_ALL
 194 GError*  g_error_new_literal   (GQuark         domain,
 195                                 gint           code,
 196                                 const gchar   *message);
 197 GLIB_AVAILABLE_IN_ALL
 198 GError*  g_error_new_valist    (GQuark         domain,
 199                                 gint           code,
 200                                 const gchar   *format,
 201                                 va_list        args) G_GNUC_PRINTF(3, 0);
 202
 203 GLIB_AVAILABLE_IN_ALL
 204 void     g_error_free          (GError        *error);
 205 GLIB_AVAILABLE_IN_ALL
 206 GError*  g_error_copy          (const GError  *error);
 207
 208 GLIB_AVAILABLE_IN_ALL
 209 gboolean g_error_matches       (const GError  *error,
 210                                 GQuark         domain,
 211                                 gint           code);
 212
 213 /* if (err) *err = g_error_new(domain, code, format, ...), also has
 214  * some sanity checks.
 215  */
 216 GLIB_AVAILABLE_IN_ALL
 217 void     g_set_error           (GError       **err,
 218                                 GQuark         domain,
 219                                 gint           code,
 220                                 const gchar   *format,
 221                                 ...) G_GNUC_PRINTF (4, 5);
 222
 223 GLIB_AVAILABLE_IN_ALL
 224 void     g_set_error_literal   (GError       **err,
 225                                 GQuark         domain,
 226                                 gint           code,
 227                                 const gchar   *message);
 228
 229 /* if (dest) *dest = src; also has some sanity checks.
 230  */
 231 GLIB_AVAILABLE_IN_ALL
 232 void     g_propagate_error     (GError       **dest,
 233                                 GError        *src);
 234
 235 /* if (err && *err) { g_error_free(*err); *err = NULL; } */
 236 GLIB_AVAILABLE_IN_ALL
 237 void     g_clear_error         (GError       **err);
 238
 239 /* if (err) prefix the formatted string to the ->message */
 240 GLIB_AVAILABLE_IN_ALL
 241 void     g_prefix_error               (GError       **err,
 242                                        const gchar   *format,
 243                                        ...) G_GNUC_PRINTF (2, 3);
 244
 245 /* g_propagate_error then g_error_prefix on dest */
 246 GLIB_AVAILABLE_IN_ALL
 247 void     g_propagate_prefixed_error   (GError       **dest,
 248                                        GError        *src,
 249                                        const gchar   *format,
 250                                        ...) G_GNUC_PRINTF (3, 4);
 251
 252 G_END_DECLS
 253
 254 #endif /* __G_ERROR_H__ */