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
30G_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 */
41typedef struct _GError GError;
42
43struct _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) \
73static inline ErrorType ## Private * \
74error_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 \
84static void \
85g_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 \
91static void \
92g_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 \
100static void \
101g_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 \
107GQuark \
108error_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 */
140typedef 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 */
158typedef 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 */
173typedef void (*GErrorClearFunc) (GError *error);
174
175GLIB_AVAILABLE_IN_2_68
176GQuark 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
182GLIB_AVAILABLE_IN_2_68
183GQuark 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
189GLIB_AVAILABLE_IN_ALL
190GError* g_error_new (GQuark domain,
191 gint code,
192 const gchar *format,
193 ...) G_GNUC_PRINTF (3, 4);
194
195GLIB_AVAILABLE_IN_ALL
196GError* g_error_new_literal (GQuark domain,
197 gint code,
198 const gchar *message);
199GLIB_AVAILABLE_IN_ALL
200GError* g_error_new_valist (GQuark domain,
201 gint code,
202 const gchar *format,
203 va_list args) G_GNUC_PRINTF(3, 0);
204
205GLIB_AVAILABLE_IN_ALL
206void g_error_free (GError *error);
207GLIB_AVAILABLE_IN_ALL
208GError* g_error_copy (const GError *error);
209
210GLIB_AVAILABLE_IN_ALL
211gboolean 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 */
218GLIB_AVAILABLE_IN_ALL
219void g_set_error (GError **err,
220 GQuark domain,
221 gint code,
222 const gchar *format,
223 ...) G_GNUC_PRINTF (4, 5);
224
225GLIB_AVAILABLE_IN_ALL
226void 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 */
233GLIB_AVAILABLE_IN_ALL
234void g_propagate_error (GError **dest,
235 GError *src);
236
237/* if (err && *err) { g_error_free(*err); *err = NULL; } */
238GLIB_AVAILABLE_IN_ALL
239void g_clear_error (GError **err);
240
241/* if (err) prefix the formatted string to the ->message */
242GLIB_AVAILABLE_IN_ALL
243void g_prefix_error (GError **err,
244 const gchar *format,
245 ...) G_GNUC_PRINTF (2, 3);
246
247/* if (err) prefix the string to the ->message */
248GLIB_AVAILABLE_IN_2_70
249void g_prefix_error_literal (GError **err,
250 const gchar *prefix);
251
252/* g_propagate_error then g_error_prefix on dest */
253GLIB_AVAILABLE_IN_ALL
254void g_propagate_prefixed_error (GError **dest,
255 GError *src,
256 const gchar *format,
257 ...) G_GNUC_PRINTF (3, 4);
258
259G_END_DECLS
260
261#endif /* __G_ERROR_H__ */
262

source code of include/glib-2.0/glib/gerror.h