nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /* GDBus - GLib D-Bus Library
2 *
3 * Copyright (C) 2008-2010 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 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
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 *
18 * Author: David Zeuthen <davidz@redhat.com>
19 */
20  
21 #include "config.h"
22  
23 #include <stdlib.h>
24 #include <string.h>
25  
26 #include "gdbuserror.h"
27 #include "gioenums.h"
28 #include "gioenumtypes.h"
29 #include "gioerror.h"
30 #include "gdbusprivate.h"
31  
32 #include "glibintl.h"
33  
34 /**
35 * SECTION:gdbuserror
36 * @title: GDBusError
37 * @short_description: Mapping D-Bus errors to and from GError
38 * @include: gio/gio.h
39 *
40 * All facilities that return errors from remote methods (such as
41 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
42 * errors (e.g. errors returned from the other peer) and locally
43 * in-process generated errors.
44 *
45 * To check if a returned #GError is an error from a remote peer, use
46 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
47 * use g_dbus_error_get_remote_error(). Before presenting an error,
48 * always use g_dbus_error_strip_remote_error().
49 *
50 * In addition, facilities used to return errors to a remote peer also
51 * use #GError. See g_dbus_method_invocation_return_error() for
52 * discussion about how the D-Bus error name is set.
53 *
54 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
55 * automatically map from D-Bus errors to #GError and back. This
56 * is typically done in the function returning the #GQuark for the
57 * error domain:
58 * |[<!-- language="C" -->
59 * // foo-bar-error.h:
60 *
61 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
62 * GQuark foo_bar_error_quark (void);
63 *
64 * typedef enum
65 * {
66 * FOO_BAR_ERROR_FAILED,
67 * FOO_BAR_ERROR_ANOTHER_ERROR,
68 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
69 * FOO_BAR_N_ERRORS / *< skip >* /
70 * } FooBarError;
71 *
72 * // foo-bar-error.c:
73 *
74 * static const GDBusErrorEntry foo_bar_error_entries[] =
75 * {
76 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
77 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
78 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
79 * };
80 *
81 * // Ensure that every error code has an associated D-Bus error name
82 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
83 *
84 * GQuark
85 * foo_bar_error_quark (void)
86 * {
87 * static volatile gsize quark_volatile = 0;
88 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
89 * &quark_volatile,
90 * foo_bar_error_entries,
91 * G_N_ELEMENTS (foo_bar_error_entries));
92 * return (GQuark) quark_volatile;
93 * }
94 * ]|
95 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
96 * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
97 *
98 * If the other peer is using GDBus, and has registered the association with
99 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
100 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
101 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
102 * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
103 *
104 * Note that errors in the %G_DBUS_ERROR error domain is intended only
105 * for returning errors from a remote message bus process. Errors
106 * generated locally in-process by e.g. #GDBusConnection is from the
107 * %G_IO_ERROR domain.
108 */
109  
110 static const GDBusErrorEntry g_dbus_error_entries[] =
111 {
112 {G_DBUS_ERROR_FAILED, "org.freedesktop.DBus.Error.Failed"},
113 {G_DBUS_ERROR_NO_MEMORY, "org.freedesktop.DBus.Error.NoMemory"},
114 {G_DBUS_ERROR_SERVICE_UNKNOWN, "org.freedesktop.DBus.Error.ServiceUnknown"},
115 {G_DBUS_ERROR_NAME_HAS_NO_OWNER, "org.freedesktop.DBus.Error.NameHasNoOwner"},
116 {G_DBUS_ERROR_NO_REPLY, "org.freedesktop.DBus.Error.NoReply"},
117 {G_DBUS_ERROR_IO_ERROR, "org.freedesktop.DBus.Error.IOError"},
118 {G_DBUS_ERROR_BAD_ADDRESS, "org.freedesktop.DBus.Error.BadAddress"},
119 {G_DBUS_ERROR_NOT_SUPPORTED, "org.freedesktop.DBus.Error.NotSupported"},
120 {G_DBUS_ERROR_LIMITS_EXCEEDED, "org.freedesktop.DBus.Error.LimitsExceeded"},
121 {G_DBUS_ERROR_ACCESS_DENIED, "org.freedesktop.DBus.Error.AccessDenied"},
122 {G_DBUS_ERROR_AUTH_FAILED, "org.freedesktop.DBus.Error.AuthFailed"},
123 {G_DBUS_ERROR_NO_SERVER, "org.freedesktop.DBus.Error.NoServer"},
124 {G_DBUS_ERROR_TIMEOUT, "org.freedesktop.DBus.Error.Timeout"},
125 {G_DBUS_ERROR_NO_NETWORK, "org.freedesktop.DBus.Error.NoNetwork"},
126 {G_DBUS_ERROR_ADDRESS_IN_USE, "org.freedesktop.DBus.Error.AddressInUse"},
127 {G_DBUS_ERROR_DISCONNECTED, "org.freedesktop.DBus.Error.Disconnected"},
128 {G_DBUS_ERROR_INVALID_ARGS, "org.freedesktop.DBus.Error.InvalidArgs"},
129 {G_DBUS_ERROR_FILE_NOT_FOUND, "org.freedesktop.DBus.Error.FileNotFound"},
130 {G_DBUS_ERROR_FILE_EXISTS, "org.freedesktop.DBus.Error.FileExists"},
131 {G_DBUS_ERROR_UNKNOWN_METHOD, "org.freedesktop.DBus.Error.UnknownMethod"},
132 {G_DBUS_ERROR_TIMED_OUT, "org.freedesktop.DBus.Error.TimedOut"},
133 {G_DBUS_ERROR_MATCH_RULE_NOT_FOUND, "org.freedesktop.DBus.Error.MatchRuleNotFound"},
134 {G_DBUS_ERROR_MATCH_RULE_INVALID, "org.freedesktop.DBus.Error.MatchRuleInvalid"},
135 {G_DBUS_ERROR_SPAWN_EXEC_FAILED, "org.freedesktop.DBus.Error.Spawn.ExecFailed"},
136 {G_DBUS_ERROR_SPAWN_FORK_FAILED, "org.freedesktop.DBus.Error.Spawn.ForkFailed"},
137 {G_DBUS_ERROR_SPAWN_CHILD_EXITED, "org.freedesktop.DBus.Error.Spawn.ChildExited"},
138 {G_DBUS_ERROR_SPAWN_CHILD_SIGNALED, "org.freedesktop.DBus.Error.Spawn.ChildSignaled"},
139 {G_DBUS_ERROR_SPAWN_FAILED, "org.freedesktop.DBus.Error.Spawn.Failed"},
140 {G_DBUS_ERROR_SPAWN_SETUP_FAILED, "org.freedesktop.DBus.Error.Spawn.FailedToSetup"},
141 {G_DBUS_ERROR_SPAWN_CONFIG_INVALID, "org.freedesktop.DBus.Error.Spawn.ConfigInvalid"},
142 {G_DBUS_ERROR_SPAWN_SERVICE_INVALID, "org.freedesktop.DBus.Error.Spawn.ServiceNotValid"},
143 {G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND, "org.freedesktop.DBus.Error.Spawn.ServiceNotFound"},
144 {G_DBUS_ERROR_SPAWN_PERMISSIONS_INVALID, "org.freedesktop.DBus.Error.Spawn.PermissionsInvalid"},
145 {G_DBUS_ERROR_SPAWN_FILE_INVALID, "org.freedesktop.DBus.Error.Spawn.FileInvalid"},
146 {G_DBUS_ERROR_SPAWN_NO_MEMORY, "org.freedesktop.DBus.Error.Spawn.NoMemory"},
147 {G_DBUS_ERROR_UNIX_PROCESS_ID_UNKNOWN, "org.freedesktop.DBus.Error.UnixProcessIdUnknown"},
148 {G_DBUS_ERROR_INVALID_SIGNATURE, "org.freedesktop.DBus.Error.InvalidSignature"},
149 {G_DBUS_ERROR_INVALID_FILE_CONTENT, "org.freedesktop.DBus.Error.InvalidFileContent"},
150 {G_DBUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN, "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown"},
151 {G_DBUS_ERROR_ADT_AUDIT_DATA_UNKNOWN, "org.freedesktop.DBus.Error.AdtAuditDataUnknown"},
152 {G_DBUS_ERROR_OBJECT_PATH_IN_USE, "org.freedesktop.DBus.Error.ObjectPathInUse"},
153 {G_DBUS_ERROR_UNKNOWN_OBJECT, "org.freedesktop.DBus.Error.UnknownObject"},
154 {G_DBUS_ERROR_UNKNOWN_INTERFACE, "org.freedesktop.DBus.Error.UnknownInterface"},
155 {G_DBUS_ERROR_UNKNOWN_PROPERTY, "org.freedesktop.DBus.Error.UnknownProperty"},
156 {G_DBUS_ERROR_PROPERTY_READ_ONLY, "org.freedesktop.DBus.Error.PropertyReadOnly"},
157 };
158  
159 GQuark
160 g_dbus_error_quark (void)
161 {
162 G_STATIC_ASSERT (G_N_ELEMENTS (g_dbus_error_entries) - 1 == G_DBUS_ERROR_PROPERTY_READ_ONLY);
163 static volatile gsize quark_volatile = 0;
164 g_dbus_error_register_error_domain ("g-dbus-error-quark",
165 &quark_volatile,
166 g_dbus_error_entries,
167 G_N_ELEMENTS (g_dbus_error_entries));
168 return (GQuark) quark_volatile;
169 }
170  
171 /**
172 * g_dbus_error_register_error_domain:
173 * @error_domain_quark_name: The error domain name.
174 * @quark_volatile: A pointer where to store the #GQuark.
175 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
176 * @num_entries: Number of items to register.
177 *
178 * Helper function for associating a #GError error domain with D-Bus error names.
179 *
180 * Since: 2.26
181 */
182 void
183 g_dbus_error_register_error_domain (const gchar *error_domain_quark_name,
184 volatile gsize *quark_volatile,
185 const GDBusErrorEntry *entries,
186 guint num_entries)
187 {
188 g_return_if_fail (error_domain_quark_name != NULL);
189 g_return_if_fail (quark_volatile != NULL);
190 g_return_if_fail (entries != NULL);
191 g_return_if_fail (num_entries > 0);
192  
193 if (g_once_init_enter (quark_volatile))
194 {
195 guint n;
196 GQuark quark;
197  
198 quark = g_quark_from_static_string (error_domain_quark_name);
199  
200 for (n = 0; n < num_entries; n++)
201 {
202 g_warn_if_fail (g_dbus_error_register_error (quark,
203 entries[n].error_code,
204 entries[n].dbus_error_name));
205 }
206 g_once_init_leave (quark_volatile, quark);
207 }
208 }
209  
210 static gboolean
211 _g_dbus_error_decode_gerror (const gchar *dbus_name,
212 GQuark *out_error_domain,
213 gint *out_error_code)
214 {
215 gboolean ret;
216 guint n;
217 GString *s;
218 gchar *domain_quark_string;
219  
220 ret = FALSE;
221 s = NULL;
222  
223 if (g_str_has_prefix (dbus_name, "org.gtk.GDBus.UnmappedGError.Quark._"))
224 {
225 s = g_string_new (NULL);
226  
227 for (n = sizeof "org.gtk.GDBus.UnmappedGError.Quark._" - 1;
228 dbus_name[n] != '.' && dbus_name[n] != '\0';
229 n++)
230 {
231 if (g_ascii_isalnum (dbus_name[n]))
232 {
233 g_string_append_c (s, dbus_name[n]);
234 }
235 else if (dbus_name[n] == '_')
236 {
237 guint nibble_top;
238 guint nibble_bottom;
239  
240 n++;
241  
242 nibble_top = dbus_name[n];
243 if (nibble_top >= '0' && nibble_top <= '9')
244 nibble_top -= '0';
245 else if (nibble_top >= 'a' && nibble_top <= 'f')
246 nibble_top -= ('a' - 10);
247 else
248 goto not_mapped;
249  
250 n++;
251  
252 nibble_bottom = dbus_name[n];
253 if (nibble_bottom >= '0' && nibble_bottom <= '9')
254 nibble_bottom -= '0';
255 else if (nibble_bottom >= 'a' && nibble_bottom <= 'f')
256 nibble_bottom -= ('a' - 10);
257 else
258 goto not_mapped;
259  
260 g_string_append_c (s, (nibble_top<<4) | nibble_bottom);
261 }
262 else
263 {
264 goto not_mapped;
265 }
266 }
267  
268 if (!g_str_has_prefix (dbus_name + n, ".Code"))
269 goto not_mapped;
270  
271 domain_quark_string = g_string_free (s, FALSE);
272 s = NULL;
273  
274 if (out_error_domain != NULL)
275 *out_error_domain = g_quark_from_string (domain_quark_string);
276 g_free (domain_quark_string);
277  
278 if (out_error_code != NULL)
279 *out_error_code = atoi (dbus_name + n + sizeof ".Code" - 1);
280  
281 ret = TRUE;
282 }
283  
284 not_mapped:
285  
286 if (s != NULL)
287 g_string_free (s, TRUE);
288  
289 return ret;
290 }
291  
292 /* ---------------------------------------------------------------------------------------------------- */
293  
294 typedef struct
295 {
296 GQuark error_domain;
297 gint error_code;
298 } QuarkCodePair;
299  
300 static guint
301 quark_code_pair_hash_func (const QuarkCodePair *pair)
302 {
303 gint val;
304 val = pair->error_domain + pair->error_code;
305 return g_int_hash (&val);
306 }
307  
308 static gboolean
309 quark_code_pair_equal_func (const QuarkCodePair *a,
310 const QuarkCodePair *b)
311 {
312 return (a->error_domain == b->error_domain) && (a->error_code == b->error_code);
313 }
314  
315 typedef struct
316 {
317 QuarkCodePair pair;
318 gchar *dbus_error_name;
319 } RegisteredError;
320  
321 static void
322 registered_error_free (RegisteredError *re)
323 {
324 g_free (re->dbus_error_name);
325 g_free (re);
326 }
327  
328 G_LOCK_DEFINE_STATIC (error_lock);
329  
330 /* maps from QuarkCodePair* -> RegisteredError* */
331 static GHashTable *quark_code_pair_to_re = NULL;
332  
333 /* maps from gchar* -> RegisteredError* */
334 static GHashTable *dbus_error_name_to_re = NULL;
335  
336 /**
337 * g_dbus_error_register_error:
338 * @error_domain: A #GQuark for a error domain.
339 * @error_code: An error code.
340 * @dbus_error_name: A D-Bus error name.
341 *
342 * Creates an association to map between @dbus_error_name and
343 * #GErrors specified by @error_domain and @error_code.
344 *
345 * This is typically done in the routine that returns the #GQuark for
346 * an error domain.
347 *
348 * Returns: %TRUE if the association was created, %FALSE if it already
349 * exists.
350 *
351 * Since: 2.26
352 */
353 gboolean
354 g_dbus_error_register_error (GQuark error_domain,
355 gint error_code,
356 const gchar *dbus_error_name)
357 {
358 gboolean ret;
359 QuarkCodePair pair;
360 RegisteredError *re;
361  
362 g_return_val_if_fail (dbus_error_name != NULL, FALSE);
363  
364 ret = FALSE;
365  
366 G_LOCK (error_lock);
367  
368 if (quark_code_pair_to_re == NULL)
369 {
370 g_assert (dbus_error_name_to_re == NULL); /* check invariant */
371 quark_code_pair_to_re = g_hash_table_new ((GHashFunc) quark_code_pair_hash_func,
372 (GEqualFunc) quark_code_pair_equal_func);
373 dbus_error_name_to_re = g_hash_table_new_full (g_str_hash,
374 g_str_equal,
375 NULL,
376 (GDestroyNotify) registered_error_free);
377 }
378  
379 if (g_hash_table_lookup (dbus_error_name_to_re, dbus_error_name) != NULL)
380 goto out;
381  
382 pair.error_domain = error_domain;
383 pair.error_code = error_code;
384  
385 if (g_hash_table_lookup (quark_code_pair_to_re, &pair) != NULL)
386 goto out;
387  
388 re = g_new0 (RegisteredError, 1);
389 re->pair = pair;
390 re->dbus_error_name = g_strdup (dbus_error_name);
391  
392 g_hash_table_insert (quark_code_pair_to_re, &(re->pair), re);
393 g_hash_table_insert (dbus_error_name_to_re, re->dbus_error_name, re);
394  
395 ret = TRUE;
396  
397 out:
398 G_UNLOCK (error_lock);
399 return ret;
400 }
401  
402 /**
403 * g_dbus_error_unregister_error:
404 * @error_domain: A #GQuark for a error domain.
405 * @error_code: An error code.
406 * @dbus_error_name: A D-Bus error name.
407 *
408 * Destroys an association previously set up with g_dbus_error_register_error().
409 *
410 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
411 *
412 * Since: 2.26
413 */
414 gboolean
415 g_dbus_error_unregister_error (GQuark error_domain,
416 gint error_code,
417 const gchar *dbus_error_name)
418 {
419 gboolean ret;
420 RegisteredError *re;
421 guint hash_size;
422  
423 g_return_val_if_fail (dbus_error_name != NULL, FALSE);
424  
425 ret = FALSE;
426  
427 G_LOCK (error_lock);
428  
429 if (dbus_error_name_to_re == NULL)
430 {
431 g_assert (quark_code_pair_to_re == NULL); /* check invariant */
432 goto out;
433 }
434  
435 re = g_hash_table_lookup (dbus_error_name_to_re, dbus_error_name);
436 if (re == NULL)
437 {
438 QuarkCodePair pair;
439 pair.error_domain = error_domain;
440 pair.error_code = error_code;
441 g_warn_if_fail (g_hash_table_lookup (quark_code_pair_to_re, &pair) == NULL); /* check invariant */
442 goto out;
443 }
444  
445 ret = TRUE;
446  
447 g_warn_if_fail (g_hash_table_lookup (quark_code_pair_to_re, &(re->pair)) == re); /* check invariant */
448  
449 g_warn_if_fail (g_hash_table_remove (quark_code_pair_to_re, &(re->pair)));
450 g_warn_if_fail (g_hash_table_remove (dbus_error_name_to_re, re->dbus_error_name));
451  
452 /* destroy hashes if empty */
453 hash_size = g_hash_table_size (dbus_error_name_to_re);
454 if (hash_size == 0)
455 {
456 g_warn_if_fail (g_hash_table_size (quark_code_pair_to_re) == 0); /* check invariant */
457  
458 g_hash_table_unref (dbus_error_name_to_re);
459 dbus_error_name_to_re = NULL;
460 g_hash_table_unref (quark_code_pair_to_re);
461 quark_code_pair_to_re = NULL;
462 }
463 else
464 {
465 g_warn_if_fail (g_hash_table_size (quark_code_pair_to_re) == hash_size); /* check invariant */
466 }
467  
468 out:
469 G_UNLOCK (error_lock);
470 return ret;
471 }
472  
473 /* ---------------------------------------------------------------------------------------------------- */
474  
475 /**
476 * g_dbus_error_is_remote_error:
477 * @error: A #GError.
478 *
479 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
480 * use g_dbus_error_get_remote_error() to get the name of the error.
481 *
482 * Returns: %TRUE if @error represents an error from a remote peer,
483 * %FALSE otherwise.
484 *
485 * Since: 2.26
486 */
487 gboolean
488 g_dbus_error_is_remote_error (const GError *error)
489 {
490 g_return_val_if_fail (error != NULL, FALSE);
491 return g_str_has_prefix (error->message, "GDBus.Error:");
492 }
493  
494  
495 /**
496 * g_dbus_error_get_remote_error:
497 * @error: a #GError
498 *
499 * Gets the D-Bus error name used for @error, if any.
500 *
501 * This function is guaranteed to return a D-Bus error name for all
502 * #GErrors returned from functions handling remote method calls
503 * (e.g. g_dbus_connection_call_finish()) unless
504 * g_dbus_error_strip_remote_error() has been used on @error.
505 *
506 * Returns: an allocated string or %NULL if the D-Bus error name
507 * could not be found. Free with g_free().
508 *
509 * Since: 2.26
510 */
511 gchar *
512 g_dbus_error_get_remote_error (const GError *error)
513 {
514 RegisteredError *re;
515 gchar *ret;
516  
517 g_return_val_if_fail (error != NULL, NULL);
518  
519 /* Ensure that e.g. G_DBUS_ERROR is registered using g_dbus_error_register_error() */
520 _g_dbus_initialize ();
521  
522 ret = NULL;
523  
524 G_LOCK (error_lock);
525  
526 re = NULL;
527 if (quark_code_pair_to_re != NULL)
528 {
529 QuarkCodePair pair;
530 pair.error_domain = error->domain;
531 pair.error_code = error->code;
532 g_assert (dbus_error_name_to_re != NULL); /* check invariant */
533 re = g_hash_table_lookup (quark_code_pair_to_re, &pair);
534 }
535  
536 if (re != NULL)
537 {
538 ret = g_strdup (re->dbus_error_name);
539 }
540 else
541 {
542 if (g_str_has_prefix (error->message, "GDBus.Error:"))
543 {
544 const gchar *begin;
545 const gchar *end;
546 begin = error->message + sizeof ("GDBus.Error:") -1;
547 end = strstr (begin, ":");
548 if (end != NULL && end[1] == ' ')
549 {
550 ret = g_strndup (begin, end - begin);
551 }
552 }
553 }
554  
555 G_UNLOCK (error_lock);
556  
557 return ret;
558 }
559  
560 /* ---------------------------------------------------------------------------------------------------- */
561  
562 /**
563 * g_dbus_error_new_for_dbus_error:
564 * @dbus_error_name: D-Bus error name.
565 * @dbus_error_message: D-Bus error message.
566 *
567 * Creates a #GError based on the contents of @dbus_error_name and
568 * @dbus_error_message.
569 *
570 * Errors registered with g_dbus_error_register_error() will be looked
571 * up using @dbus_error_name and if a match is found, the error domain
572 * and code is used. Applications can use g_dbus_error_get_remote_error()
573 * to recover @dbus_error_name.
574 *
575 * If a match against a registered error is not found and the D-Bus
576 * error name is in a form as returned by g_dbus_error_encode_gerror()
577 * the error domain and code encoded in the name is used to
578 * create the #GError. Also, @dbus_error_name is added to the error message
579 * such that it can be recovered with g_dbus_error_get_remote_error().
580 *
581 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
582 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
583 * added to the error message such that it can be recovered with
584 * g_dbus_error_get_remote_error().
585 *
586 * In all three cases, @dbus_error_name can always be recovered from the
587 * returned #GError using the g_dbus_error_get_remote_error() function
588 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
589 *
590 * This function is typically only used in object mappings to prepare
591 * #GError instances for applications. Regular applications should not use
592 * it.
593 *
594 * Returns: An allocated #GError. Free with g_error_free().
595 *
596 * Since: 2.26
597 */
598 GError *
599 g_dbus_error_new_for_dbus_error (const gchar *dbus_error_name,
600 const gchar *dbus_error_message)
601 {
602 GError *error;
603 RegisteredError *re;
604  
605 g_return_val_if_fail (dbus_error_name != NULL, NULL);
606 g_return_val_if_fail (dbus_error_message != NULL, NULL);
607  
608 /* Ensure that e.g. G_DBUS_ERROR is registered using g_dbus_error_register_error() */
609 _g_dbus_initialize ();
610  
611 G_LOCK (error_lock);
612  
613 re = NULL;
614 if (dbus_error_name_to_re != NULL)
615 {
616 g_assert (quark_code_pair_to_re != NULL); /* check invariant */
617 re = g_hash_table_lookup (dbus_error_name_to_re, dbus_error_name);
618 }
619  
620 if (re != NULL)
621 {
622 error = g_error_new (re->pair.error_domain,
623 re->pair.error_code,
624 "GDBus.Error:%s: %s",
625 dbus_error_name,
626 dbus_error_message);
627 }
628 else
629 {
630 GQuark error_domain = 0;
631 gint error_code = 0;
632  
633 if (_g_dbus_error_decode_gerror (dbus_error_name,
634 &error_domain,
635 &error_code))
636 {
637 error = g_error_new (error_domain,
638 error_code,
639 "GDBus.Error:%s: %s",
640 dbus_error_name,
641 dbus_error_message);
642 }
643 else
644 {
645 error = g_error_new (G_IO_ERROR,
646 G_IO_ERROR_DBUS_ERROR,
647 "GDBus.Error:%s: %s",
648 dbus_error_name,
649 dbus_error_message);
650 }
651 }
652  
653 G_UNLOCK (error_lock);
654 return error;
655 }
656  
657 /**
658 * g_dbus_error_set_dbus_error:
659 * @error: A pointer to a #GError or %NULL.
660 * @dbus_error_name: D-Bus error name.
661 * @dbus_error_message: D-Bus error message.
662 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
663 * @...: Arguments for @format.
664 *
665 * Does nothing if @error is %NULL. Otherwise sets *@error to
666 * a new #GError created with g_dbus_error_new_for_dbus_error()
667 * with @dbus_error_message prepend with @format (unless %NULL).
668 *
669 * Since: 2.26
670 */
671 void
672 g_dbus_error_set_dbus_error (GError **error,
673 const gchar *dbus_error_name,
674 const gchar *dbus_error_message,
675 const gchar *format,
676 ...)
677 {
678 g_return_if_fail (error == NULL || *error == NULL);
679 g_return_if_fail (dbus_error_name != NULL);
680 g_return_if_fail (dbus_error_message != NULL);
681  
682 if (error == NULL)
683 return;
684  
685 if (format == NULL)
686 {
687 *error = g_dbus_error_new_for_dbus_error (dbus_error_name, dbus_error_message);
688 }
689 else
690 {
691 va_list var_args;
692 va_start (var_args, format);
693 g_dbus_error_set_dbus_error_valist (error,
694 dbus_error_name,
695 dbus_error_message,
696 format,
697 var_args);
698 va_end (var_args);
699 }
700 }
701  
702 /**
703 * g_dbus_error_set_dbus_error_valist:
704 * @error: A pointer to a #GError or %NULL.
705 * @dbus_error_name: D-Bus error name.
706 * @dbus_error_message: D-Bus error message.
707 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
708 * @var_args: Arguments for @format.
709 *
710 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
711 *
712 * Since: 2.26
713 */
714 void
715 g_dbus_error_set_dbus_error_valist (GError **error,
716 const gchar *dbus_error_name,
717 const gchar *dbus_error_message,
718 const gchar *format,
719 va_list var_args)
720 {
721 g_return_if_fail (error == NULL || *error == NULL);
722 g_return_if_fail (dbus_error_name != NULL);
723 g_return_if_fail (dbus_error_message != NULL);
724  
725 if (error == NULL)
726 return;
727  
728 if (format != NULL)
729 {
730 gchar *message;
731 gchar *s;
732 message = g_strdup_vprintf (format, var_args);
733 s = g_strdup_printf ("%s: %s", message, dbus_error_message);
734 *error = g_dbus_error_new_for_dbus_error (dbus_error_name, s);
735 g_free (s);
736 g_free (message);
737 }
738 else
739 {
740 *error = g_dbus_error_new_for_dbus_error (dbus_error_name, dbus_error_message);
741 }
742 }
743  
744 /**
745 * g_dbus_error_strip_remote_error:
746 * @error: A #GError.
747 *
748 * Looks for extra information in the error message used to recover
749 * the D-Bus error name and strips it if found. If stripped, the
750 * message field in @error will correspond exactly to what was
751 * received on the wire.
752 *
753 * This is typically used when presenting errors to the end user.
754 *
755 * Returns: %TRUE if information was stripped, %FALSE otherwise.
756 *
757 * Since: 2.26
758 */
759 gboolean
760 g_dbus_error_strip_remote_error (GError *error)
761 {
762 gboolean ret;
763  
764 g_return_val_if_fail (error != NULL, FALSE);
765  
766 ret = FALSE;
767  
768 if (g_str_has_prefix (error->message, "GDBus.Error:"))
769 {
770 const gchar *begin;
771 const gchar *end;
772 gchar *new_message;
773  
774 begin = error->message + sizeof ("GDBus.Error:") -1;
775 end = strstr (begin, ":");
776 if (end != NULL && end[1] == ' ')
777 {
778 new_message = g_strdup (end + 2);
779 g_free (error->message);
780 error->message = new_message;
781 ret = TRUE;
782 }
783 }
784  
785 return ret;
786 }
787  
788 /**
789 * g_dbus_error_encode_gerror:
790 * @error: A #GError.
791 *
792 * Creates a D-Bus error name to use for @error. If @error matches
793 * a registered error (cf. g_dbus_error_register_error()), the corresponding
794 * D-Bus error name will be returned.
795 *
796 * Otherwise the a name of the form
797 * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
798 * will be used. This allows other GDBus applications to map the error
799 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
800 *
801 * This function is typically only used in object mappings to put a
802 * #GError on the wire. Regular applications should not use it.
803 *
804 * Returns: A D-Bus error name (never %NULL). Free with g_free().
805 *
806 * Since: 2.26
807 */
808 gchar *
809 g_dbus_error_encode_gerror (const GError *error)
810 {
811 RegisteredError *re;
812 gchar *error_name;
813  
814 g_return_val_if_fail (error != NULL, NULL);
815  
816 /* Ensure that e.g. G_DBUS_ERROR is registered using g_dbus_error_register_error() */
817 _g_dbus_initialize ();
818  
819 error_name = NULL;
820  
821 G_LOCK (error_lock);
822 re = NULL;
823 if (quark_code_pair_to_re != NULL)
824 {
825 QuarkCodePair pair;
826 pair.error_domain = error->domain;
827 pair.error_code = error->code;
828 g_assert (dbus_error_name_to_re != NULL); /* check invariant */
829 re = g_hash_table_lookup (quark_code_pair_to_re, &pair);
830 }
831 if (re != NULL)
832 {
833 error_name = g_strdup (re->dbus_error_name);
834 G_UNLOCK (error_lock);
835 }
836 else
837 {
838 const gchar *domain_as_string;
839 GString *s;
840 guint n;
841  
842 G_UNLOCK (error_lock);
843  
844 /* We can't make a lot of assumptions about what domain_as_string
845 * looks like and D-Bus is extremely picky about error names so
846 * hex-encode it for transport across the wire.
847 */
848 domain_as_string = g_quark_to_string (error->domain);
849  
850 /* 0 is not a domain; neither are non-quark integers */
851 g_return_val_if_fail (domain_as_string != NULL, NULL);
852  
853 s = g_string_new ("org.gtk.GDBus.UnmappedGError.Quark._");
854 for (n = 0; domain_as_string[n] != 0; n++)
855 {
856 gint c = domain_as_string[n];
857 if (g_ascii_isalnum (c))
858 {
859 g_string_append_c (s, c);
860 }
861 else
862 {
863 guint nibble_top;
864 guint nibble_bottom;
865 g_string_append_c (s, '_');
866 nibble_top = ((int) domain_as_string[n]) >> 4;
867 nibble_bottom = ((int) domain_as_string[n]) & 0x0f;
868 if (nibble_top < 10)
869 nibble_top += '0';
870 else
871 nibble_top += 'a' - 10;
872 if (nibble_bottom < 10)
873 nibble_bottom += '0';
874 else
875 nibble_bottom += 'a' - 10;
876 g_string_append_c (s, nibble_top);
877 g_string_append_c (s, nibble_bottom);
878 }
879 }
880 g_string_append_printf (s, ".Code%d", error->code);
881 error_name = g_string_free (s, FALSE);
882 }
883  
884 return error_name;
885 }