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, 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: (nullable): 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: (nullable): 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 }