glib-2.0/glib/gerror.h

0001 /* gerror.h - Error reporting system
0002  *
0003  *  Copyright 2000 Red Hat, Inc.
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public License
0018  * along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  */
0020
0021 #ifndef __G_ERROR_H__
0022 #define __G_ERROR_H__
0023
0024 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0025 #error "Only <glib.h> can be included directly."
0026 #endif
0027
0028 #include <stdarg.h>
0029
0030 #include <glib/gquark.h>
0031
0032 G_BEGIN_DECLS
0033
0034 /**
0035  * GError:
0036  * @domain: error domain, e.g. %G_FILE_ERROR
0037  * @code: error code, e.g. %G_FILE_ERROR_NOENT
0038  * @message: human-readable informative error message
0039  *
0040  * The `GError` structure contains information about
0041  * an error that has occurred.
0042  */
0043 typedef struct _GError GError;
0044
0045 struct _GError
0046 {
0047   GQuark       domain;
0048   gint         code;
0049   gchar       *message;
0050 };
0051
0052 /**
0053  * G_DEFINE_EXTENDED_ERROR:
0054  * @ErrorType: name to return a #GQuark for
0055  * @error_type: prefix for the function name
0056  *
0057  * A convenience macro which defines two functions. First, returning
0058  * the #GQuark for the extended error type @ErrorType; it is called
0059  * `error_type_quark()`. Second, returning the private data from a
0060  * passed #GError; it is called `error_type_get_private()`.
0061  *
0062  * For this macro to work, a type named `ErrorTypePrivate` should be
0063  * defined, `error_type_private_init()`, `error_type_private_copy()`
0064  * and `error_type_private_clear()` functions need to be either
0065  * declared or defined. The functions should be similar to
0066  * #GErrorInitFunc, #GErrorCopyFunc and #GErrorClearFunc,
0067  * respectively, but they should receive the private data type instead
0068  * of #GError.
0069  *
0070  * See [Extended #GError Domains][gerror-extended-domains] for an example.
0071  *
0072  * Since: 2.68
0073  */
0074 #define G_DEFINE_EXTENDED_ERROR(ErrorType, error_type)                  \
0075 static inline ErrorType ## Private *                                    \
0076 error_type ## _get_private (const GError *error)                        \
0077 {                                                                       \
0078   /* Copied from gtype.c (STRUCT_ALIGNMENT and ALIGN_STRUCT macros). */ \
0079   const gsize sa = 2 * sizeof (gsize);                                  \
0080   const gsize as = (sizeof (ErrorType ## Private) + (sa - 1)) & -sa;    \
0081   g_return_val_if_fail (error != NULL, NULL);                           \
0082   g_return_val_if_fail (error->domain == error_type ## _quark (), NULL); \
0083   return (ErrorType ## Private *) (((guint8 *)error) - as); \
0084 }                                                                       \
0085                                                                         \
0086 static void                                                             \
0087 g_error_with_ ## error_type ## _private_init (GError *error)            \
0088 {                                                                       \
0089   ErrorType ## Private *priv = error_type ## _get_private (error);      \
0090   error_type ## _private_init (priv);                                   \
0091 }                                                                       \
0092                                                                         \
0093 static void                                                             \
0094 g_error_with_ ## error_type ## _private_copy (const GError *src_error,  \
0095                                               GError       *dest_error) \
0096 {                                                                       \
0097   const ErrorType ## Private *src_priv = error_type ## _get_private (src_error);  \
0098   ErrorType ## Private *dest_priv = error_type ## _get_private (dest_error); \
0099   error_type ## _private_copy (src_priv, dest_priv);                    \
0100 }                                                                       \
0101                                                                         \
0102 static void                                                             \
0103 g_error_with_ ## error_type ## _private_clear (GError *error)           \
0104 {                                                                       \
0105   ErrorType ## Private *priv = error_type ## _get_private (error);      \
0106   error_type ## _private_clear (priv);                                  \
0107 }                                                                       \
0108                                                                         \
0109 GQuark                                                                  \
0110 error_type ## _quark (void)                                             \
0111 {                                                                       \
0112   static GQuark q;                                                      \
0113   static gsize initialized = 0;                                         \
0114                                                                         \
0115   if (g_once_init_enter (&initialized))                                 \
0116     {                                                                   \
0117       q = g_error_domain_register_static (#ErrorType,                   \
0118                                           sizeof (ErrorType ## Private), \
0119                                           g_error_with_ ## error_type ## _private_init, \
0120                                           g_error_with_ ## error_type ## _private_copy, \
0121                                           g_error_with_ ## error_type ## _private_clear); \
0122       g_once_init_leave (&initialized, 1);                              \
0123     }                                                                   \
0124                                                                         \
0125   return q;                                                             \
0126 }
0127
0128 /**
0129  * GErrorInitFunc:
0130  * @error: extended error
0131  *
0132  * Specifies the type of function which is called just after an
0133  * extended error instance is created and its fields filled. It should
0134  * only initialize the fields in the private data, which can be
0135  * received with the generated `*_get_private()` function.
0136  *
0137  * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
0138  * already takes care of getting the private data from @error.
0139  *
0140  * Since: 2.68
0141  */
0142 typedef void (*GErrorInitFunc) (GError *error);
0143
0144 /**
0145  * GErrorCopyFunc:
0146  * @src_error: source extended error
0147  * @dest_error: destination extended error
0148  *
0149  * Specifies the type of function which is called when an extended
0150  * error instance is copied. It is passed the pointer to the
0151  * destination error and source error, and should copy only the fields
0152  * of the private data from @src_error to @dest_error.
0153  *
0154  * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
0155  * already takes care of getting the private data from @src_error and
0156  * @dest_error.
0157  *
0158  * Since: 2.68
0159  */
0160 typedef void (*GErrorCopyFunc) (const GError *src_error, GError *dest_error);
0161
0162 /**
0163  * GErrorClearFunc:
0164  * @error: extended error to clear
0165  *
0166  * Specifies the type of function which is called when an extended
0167  * error instance is freed. It is passed the error pointer about to be
0168  * freed, and should free the error's private data fields.
0169  *
0170  * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
0171  * already takes care of getting the private data from @error.
0172  *
0173  * Since: 2.68
0174  */
0175 typedef void (*GErrorClearFunc) (GError *error);
0176
0177 GLIB_AVAILABLE_IN_2_68
0178 GQuark   g_error_domain_register_static (const char        *error_type_name,
0179                                          gsize              error_type_private_size,
0180                                          GErrorInitFunc     error_type_init,
0181                                          GErrorCopyFunc     error_type_copy,
0182                                          GErrorClearFunc    error_type_clear);
0183
0184 GLIB_AVAILABLE_IN_2_68
0185 GQuark   g_error_domain_register (const char        *error_type_name,
0186                                   gsize              error_type_private_size,
0187                                   GErrorInitFunc     error_type_init,
0188                                   GErrorCopyFunc     error_type_copy,
0189                                   GErrorClearFunc    error_type_clear);
0190
0191 GLIB_AVAILABLE_IN_ALL
0192 GError*  g_error_new           (GQuark         domain,
0193                                 gint           code,
0194                                 const gchar   *format,
0195                                 ...) G_GNUC_PRINTF (3, 4);
0196
0197 GLIB_AVAILABLE_IN_ALL
0198 GError*  g_error_new_literal   (GQuark         domain,
0199                                 gint           code,
0200                                 const gchar   *message);
0201 GLIB_AVAILABLE_IN_ALL
0202 GError*  g_error_new_valist    (GQuark         domain,
0203                                 gint           code,
0204                                 const gchar   *format,
0205                                 va_list        args) G_GNUC_PRINTF(3, 0);
0206
0207 GLIB_AVAILABLE_IN_ALL
0208 void     g_error_free          (GError        *error);
0209 GLIB_AVAILABLE_IN_ALL
0210 GError*  g_error_copy          (const GError  *error);
0211
0212 GLIB_AVAILABLE_IN_ALL
0213 gboolean g_error_matches       (const GError  *error,
0214                                 GQuark         domain,
0215                                 gint           code);
0216
0217 /* if (err) *err = g_error_new(domain, code, format, ...), also has
0218  * some sanity checks.
0219  */
0220 GLIB_AVAILABLE_IN_ALL
0221 void     g_set_error           (GError       **err,
0222                                 GQuark         domain,
0223                                 gint           code,
0224                                 const gchar   *format,
0225                                 ...) G_GNUC_PRINTF (4, 5);
0226
0227 GLIB_AVAILABLE_IN_ALL
0228 void     g_set_error_literal   (GError       **err,
0229                                 GQuark         domain,
0230                                 gint           code,
0231                                 const gchar   *message);
0232
0233 /* if (dest) *dest = src; also has some sanity checks.
0234  */
0235 GLIB_AVAILABLE_IN_ALL
0236 void     g_propagate_error     (GError       **dest,
0237                 GError        *src);
0238
0239 /* if (err && *err) { g_error_free(*err); *err = NULL; } */
0240 GLIB_AVAILABLE_IN_ALL
0241 void     g_clear_error         (GError       **err);
0242
0243 /* if (err) prefix the formatted string to the ->message */
0244 GLIB_AVAILABLE_IN_ALL
0245 void     g_prefix_error               (GError       **err,
0246                                        const gchar   *format,
0247                                        ...) G_GNUC_PRINTF (2, 3);
0248
0249 /* if (err) prefix the string to the ->message */
0250 GLIB_AVAILABLE_IN_2_70
0251 void     g_prefix_error_literal       (GError       **err,
0252                                        const gchar   *prefix);
0253
0254 /* g_propagate_error then g_error_prefix on dest */
0255 GLIB_AVAILABLE_IN_ALL
0256 void     g_propagate_prefixed_error   (GError       **dest,
0257                                        GError        *src,
0258                                        const gchar   *format,
0259                                        ...) G_GNUC_PRINTF (3, 4);
0260
0261 G_END_DECLS
0262
0263 #endif /* __G_ERROR_H__ */