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 * See [Extended #GError Domains][gerror-extended-domains] for an example. 69 * 70 * Since: 2.68 71 */ 72 #define G_DEFINE_EXTENDED_ERROR(ErrorType, error_type) \ 73 static inline ErrorType ## Private * \ 74 error_type ## _get_private (const GError *error) \ 75 { \ 76 /* Copied from gtype.c (STRUCT_ALIGNMENT and ALIGN_STRUCT macros). */ \ 77 const gsize sa = 2 * sizeof (gsize); \ 78 const gsize as = (sizeof (ErrorType ## Private) + (sa - 1)) & -sa; \ 79 g_return_val_if_fail (error != NULL, NULL); \ 80 g_return_val_if_fail (error->domain == error_type ## _quark (), NULL); \ 81 return (ErrorType ## Private *) (((guint8 *)error) - as); \ 82 } \ 83 \ 84 static void \ 85 g_error_with_ ## error_type ## _private_init (GError *error) \ 86 { \ 87 ErrorType ## Private *priv = error_type ## _get_private (error); \ 88 error_type ## _private_init (priv); \ 89 } \ 90 \ 91 static void \ 92 g_error_with_ ## error_type ## _private_copy (const GError *src_error, \ 93 GError *dest_error) \ 94 { \ 95 const ErrorType ## Private *src_priv = error_type ## _get_private (src_error); \ 96 ErrorType ## Private *dest_priv = error_type ## _get_private (dest_error); \ 97 error_type ## _private_copy (src_priv, dest_priv); \ 98 } \ 99 \ 100 static void \ 101 g_error_with_ ## error_type ## _private_clear (GError *error) \ 102 { \ 103 ErrorType ## Private *priv = error_type ## _get_private (error); \ 104 error_type ## _private_clear (priv); \ 105 } \ 106 \ 107 GQuark \ 108 error_type ## _quark (void) \ 109 { \ 110 static GQuark q; \ 111 static gsize initialized = 0; \ 112 \ 113 if (g_once_init_enter (&initialized)) \ 114 { \ 115 q = g_error_domain_register_static (#ErrorType, \ 116 sizeof (ErrorType ## Private), \ 117 g_error_with_ ## error_type ## _private_init, \ 118 g_error_with_ ## error_type ## _private_copy, \ 119 g_error_with_ ## error_type ## _private_clear); \ 120 g_once_init_leave (&initialized, 1); \ 121 } \ 122 \ 123 return q; \ 124 } 125 126 /** 127 * GErrorInitFunc: 128 * @error: extended error 129 * 130 * Specifies the type of function which is called just after an 131 * extended error instance is created and its fields filled. It should 132 * only initialize the fields in the private data, which can be 133 * received with the generated `*_get_private()` function. 134 * 135 * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it 136 * already takes care of getting the private data from @error. 137 * 138 * Since: 2.68 139 */ 140 typedef void (*GErrorInitFunc) (GError *error); 141 142 /** 143 * GErrorCopyFunc: 144 * @src_error: source extended error 145 * @dest_error: destination extended error 146 * 147 * Specifies the type of function which is called when an extended 148 * error instance is copied. It is passed the pointer to the 149 * destination error and source error, and should copy only the fields 150 * of the private data from @src_error to @dest_error. 151 * 152 * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it 153 * already takes care of getting the private data from @src_error and 154 * @dest_error. 155 * 156 * Since: 2.68 157 */ 158 typedef void (*GErrorCopyFunc) (const GError *src_error, GError *dest_error); 159 160 /** 161 * GErrorClearFunc: 162 * @error: extended error to clear 163 * 164 * Specifies the type of function which is called when an extended 165 * error instance is freed. It is passed the error pointer about to be 166 * freed, and should free the error's private data fields. 167 * 168 * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it 169 * already takes care of getting the private data from @error. 170 * 171 * Since: 2.68 172 */ 173 typedef void (*GErrorClearFunc) (GError *error); 174 175 GLIB_AVAILABLE_IN_2_68 176 GQuark g_error_domain_register_static (const char *error_type_name, 177 gsize error_type_private_size, 178 GErrorInitFunc error_type_init, 179 GErrorCopyFunc error_type_copy, 180 GErrorClearFunc error_type_clear); 181 182 GLIB_AVAILABLE_IN_2_68 183 GQuark g_error_domain_register (const char *error_type_name, 184 gsize error_type_private_size, 185 GErrorInitFunc error_type_init, 186 GErrorCopyFunc error_type_copy, 187 GErrorClearFunc error_type_clear); 188 189 GLIB_AVAILABLE_IN_ALL 190 GError* g_error_new (GQuark domain, 191 gint code, 192 const gchar *format, 193 ...) G_GNUC_PRINTF (3, 4); 194 195 GLIB_AVAILABLE_IN_ALL 196 GError* g_error_new_literal (GQuark domain, 197 gint code, 198 const gchar *message); 199 GLIB_AVAILABLE_IN_ALL 200 GError* g_error_new_valist (GQuark domain, 201 gint code, 202 const gchar *format, 203 va_list args) G_GNUC_PRINTF(3, 0); 204 205 GLIB_AVAILABLE_IN_ALL 206 void g_error_free (GError *error); 207 GLIB_AVAILABLE_IN_ALL 208 GError* g_error_copy (const GError *error); 209 210 GLIB_AVAILABLE_IN_ALL 211 gboolean g_error_matches (const GError *error, 212 GQuark domain, 213 gint code); 214 215 /* if (err) *err = g_error_new(domain, code, format, ...), also has 216 * some sanity checks. 217 */ 218 GLIB_AVAILABLE_IN_ALL 219 void g_set_error (GError **err, 220 GQuark domain, 221 gint code, 222 const gchar *format, 223 ...) G_GNUC_PRINTF (4, 5); 224 225 GLIB_AVAILABLE_IN_ALL 226 void g_set_error_literal (GError **err, 227 GQuark domain, 228 gint code, 229 const gchar *message); 230 231 /* if (dest) *dest = src; also has some sanity checks. 232 */ 233 GLIB_AVAILABLE_IN_ALL 234 void g_propagate_error (GError **dest, 235 GError *src); 236 237 /* if (err && *err) { g_error_free(*err); *err = NULL; } */ 238 GLIB_AVAILABLE_IN_ALL 239 void g_clear_error (GError **err); 240 241 /* if (err) prefix the formatted string to the ->message */ 242 GLIB_AVAILABLE_IN_ALL 243 void g_prefix_error (GError **err, 244 const gchar *format, 245 ...) G_GNUC_PRINTF (2, 3); 246 247 /* g_propagate_error then g_error_prefix on dest */ 248 GLIB_AVAILABLE_IN_ALL 249 void g_propagate_prefixed_error (GError **dest, 250 GError *src, 251 const gchar *format, 252 ...) G_GNUC_PRINTF (3, 4); 253 254 G_END_DECLS 255 256 #endif /* __G_ERROR_H__ */ 257