glib/gerror.h

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