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__ */ |
264 | |