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