dbus/dbus-errors.c

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2 /* dbus-errors.c Error reporting
   3  *
   4  * Copyright (C) 2002, 2004  Red Hat Inc.
   5  * Copyright (C) 2003  CodeFactory AB
   6  *
   7  * Licensed under the Academic Free License version 2.1
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  22  *
  23  */
  24
  25 #include <config.h>
  26 #include "dbus-errors.h"
  27 #include "dbus-internals.h"
  28 #include "dbus-string.h"
  29 #include "dbus-protocol.h"
  30 #include <stdarg.h>
  31 #include <string.h>
  32
  33 /**
  34  * @defgroup DBusErrorInternals Error reporting internals
  35  * @ingroup  DBusInternals
  36  * @brief Error reporting internals
  37  * @{
  38  */
  39
  40 /**
  41  * @def DBUS_ERROR_INIT
  42  *
  43  * Expands to a suitable initializer for a DBusError on the stack.
  44  * Declaring a DBusError with:
  45  *
  46  * @code
  47  * DBusError error = DBUS_ERROR_INIT;
  48  *
  49  * do_things_with (&error);
  50  * @endcode
  51  *
  52  * is a more concise form of:
  53  *
  54  * @code
  55  * DBusError error;
  56  *
  57  * dbus_error_init (&error);
  58  * do_things_with (&error);
  59  * @endcode
  60  */
  61
  62 /**
  63  * Internals of DBusError
  64  */
  65 typedef struct
  66 {
  67   char *name; /**< error name */
  68   char *message; /**< error message */
  69
  70   unsigned int const_message : 1; /**< Message is not owned by DBusError */
  71
  72   unsigned int dummy2 : 1; /**< placeholder */
  73   unsigned int dummy3 : 1; /**< placeholder */
  74   unsigned int dummy4 : 1; /**< placeholder */
  75   unsigned int dummy5 : 1; /**< placeholder */
  76
  77   void *padding1; /**< placeholder */
  78
  79 } DBusRealError;
  80
  81 _DBUS_STATIC_ASSERT (sizeof (DBusRealError) == sizeof (DBusError));
  82
  83 /**
  84  * Returns a longer message describing an error name.
  85  * If the error name is unknown, returns the name
  86  * itself.
  87  *
  88  * @param error the error to describe
  89  * @returns a constant string describing the error.
  90  */
  91 static const char*
  92 message_from_error (const char *error)
  93 {
  94   if (strcmp (error, DBUS_ERROR_FAILED) == 0)
  95     return "Unknown error";
  96   else if (strcmp (error, DBUS_ERROR_NO_MEMORY) == 0)
  97     return "Not enough memory available";
  98   else if (strcmp (error, DBUS_ERROR_IO_ERROR) == 0)
  99     return "Error reading or writing data";
 100   else if (strcmp (error, DBUS_ERROR_BAD_ADDRESS) == 0)
 101     return "Could not parse address";
 102   else if (strcmp (error, DBUS_ERROR_NOT_SUPPORTED) == 0)
 103     return "Feature not supported";
 104   else if (strcmp (error, DBUS_ERROR_LIMITS_EXCEEDED) == 0)
 105     return "Resource limits exceeded";
 106   else if (strcmp (error, DBUS_ERROR_ACCESS_DENIED) == 0)
 107     return "Permission denied";
 108   else if (strcmp (error, DBUS_ERROR_AUTH_FAILED) == 0)
 109     return "Could not authenticate to server";
 110   else if (strcmp (error, DBUS_ERROR_NO_SERVER) == 0)
 111     return "No server available at address";
 112   else if (strcmp (error, DBUS_ERROR_TIMEOUT) == 0)
 113     return "Connection timed out";
 114   else if (strcmp (error, DBUS_ERROR_NO_NETWORK) == 0)
 115     return "Network unavailable";
 116   else if (strcmp (error, DBUS_ERROR_ADDRESS_IN_USE) == 0)
 117     return "Address already in use";
 118   else if (strcmp (error, DBUS_ERROR_DISCONNECTED) == 0)
 119     return "Disconnected.";
 120   else if (strcmp (error, DBUS_ERROR_INVALID_ARGS) == 0)
 121     return "Invalid arguments.";
 122   else if (strcmp (error, DBUS_ERROR_NO_REPLY) == 0)
 123     return "Did not get a reply message.";
 124   else if (strcmp (error, DBUS_ERROR_FILE_NOT_FOUND) == 0)
 125     return "File doesn't exist.";
 126   else if (strcmp (error, DBUS_ERROR_OBJECT_PATH_IN_USE) == 0)
 127     return "Object path already in use";
 128   else
 129     return error;
 130 }
 131
 132 /** @} */ /* End of internals */
 133
 134 /**
 135  * @defgroup DBusErrors Error reporting
 136  * @ingroup  DBus
 137  * @brief Error reporting
 138  *
 139  * Types and functions related to reporting errors.
 140  *
 141  *
 142  * In essence D-Bus error reporting works as follows:
 143  *
 144  * @code
 145  * DBusError error;
 146  * dbus_error_init (&error);
 147  * dbus_some_function (arg1, arg2, &error);
 148  * if (dbus_error_is_set (&error))
 149  *   {
 150  *     fprintf (stderr, "an error occurred: %s\n", error.message);
 151  *     dbus_error_free (&error);
 152  *   }
 153  * @endcode
 154  *
 155  * By convention, all functions allow #NULL instead of a DBusError*,
 156  * so callers who don't care about the error can ignore it.
 157  *
 158  * There are some rules. An error passed to a D-Bus function must
 159  * always be unset; you can't pass in an error that's already set.  If
 160  * a function has a return code indicating whether an error occurred,
 161  * and also a #DBusError parameter, then the error will always be set
 162  * if and only if the return code indicates an error occurred. i.e.
 163  * the return code and the error are never going to disagree.
 164  *
 165  * An error only needs to be freed if it's been set, not if
 166  * it's merely been initialized.
 167  *
 168  * You can check the specific error that occurred using
 169  * dbus_error_has_name().
 170  *
 171  * Errors will not be set for programming errors, such as passing
 172  * invalid arguments to the libdbus API. Instead, libdbus will print
 173  * warnings, exit on a failed assertion, or even crash in those cases
 174  * (in other words, incorrect use of the API results in undefined
 175  * behavior, possibly accompanied by helpful debugging output if
 176  * you're lucky).
 177  *
 178  * @{
 179  */
 180
 181 /**
 182  * Initializes a DBusError structure. Does not allocate any memory;
 183  * the error only needs to be freed if it is set at some point.
 184  *
 185  * @param error the DBusError.
 186  */
 187 void
 188 dbus_error_init (DBusError *error)
 189 {
 190   DBusRealError *real;
 191
 192   _dbus_return_if_fail (error != NULL);
 193
 194   _dbus_assert (sizeof (DBusError) == sizeof (DBusRealError));
 195
 196   real = (DBusRealError *)error;
 197
 198   real->name = NULL;
 199   real->message = NULL;
 200
 201   real->const_message = TRUE;
 202 }
 203
 204 /**
 205  * Frees an error that's been set (or just initialized),
 206  * then reinitializes the error as in dbus_error_init().
 207  *
 208  * @param error memory where the error is stored.
 209  */
 210 void
 211 dbus_error_free (DBusError *error)
 212 {
 213   DBusRealError *real;
 214
 215   _dbus_return_if_fail (error != NULL);
 216
 217   real = (DBusRealError *)error;
 218
 219   if (!real->const_message)
 220     {
 221       dbus_free (real->name);
 222       dbus_free (real->message);
 223     }
 224
 225   dbus_error_init (error);
 226 }
 227
 228 /**
 229  * Assigns an error name and message to a DBusError.  Does nothing if
 230  * error is #NULL. The message may be #NULL, which means a default
 231  * message will be deduced from the name. The default message will be
 232  * totally useless, though, so using a #NULL message is not recommended.
 233  *
 234  * Because this function does not copy the error name or message, you
 235  * must ensure the name and message are global data that won't be
 236  * freed. You probably want dbus_set_error() instead, in most cases.
 237  *
 238  * @param error the error or #NULL
 239  * @param name the error name (not copied!!!)
 240  * @param message the error message (not copied!!!)
 241  */
 242 void
 243 dbus_set_error_const (DBusError  *error,
 244                       const char *name,
 245                       const char *message)
 246 {
 247   DBusRealError *real;
 248
 249   _dbus_return_if_error_is_set (error);
 250   _dbus_return_if_fail (name != NULL);
 251
 252   if (error == NULL)
 253     return;
 254
 255   _dbus_assert (error->name == NULL);
 256   _dbus_assert (error->message == NULL);
 257
 258   if (message == NULL)
 259     message = message_from_error (name);
 260
 261   real = (DBusRealError *)error;
 262
 263   real->name = (char*) name;
 264   real->message = (char *)message;
 265   real->const_message = TRUE;
 266 }
 267
 268 /**
 269  * Moves an error src into dest, freeing src and
 270  * overwriting dest. Both src and dest must be initialized.
 271  * src is reinitialized to an empty error. dest may not
 272  * contain an existing error. If the destination is
 273  * #NULL, just frees and reinits the source error.
 274  *
 275  * @param src the source error
 276  * @param dest the destination error or #NULL
 277  */
 278 void
 279 dbus_move_error (DBusError *src,
 280                  DBusError *dest)
 281 {
 282   _dbus_return_if_error_is_set (dest);
 283
 284   if (dest)
 285     {
 286       dbus_error_free (dest);
 287       *dest = *src;
 288       dbus_error_init (src);
 289     }
 290   else
 291     dbus_error_free (src);
 292 }
 293
 294 /**
 295  * Checks whether the error is set and has the given
 296  * name.
 297  * @param error the error
 298  * @param name the name
 299  * @returns #TRUE if the given named error occurred
 300  */
 301 dbus_bool_t
 302 dbus_error_has_name (const DBusError *error,
 303                      const char      *name)
 304 {
 305   _dbus_return_val_if_fail (error != NULL, FALSE);
 306   _dbus_return_val_if_fail (name != NULL, FALSE);
 307
 308   _dbus_assert ((error->name != NULL && error->message != NULL) ||
 309                 (error->name == NULL && error->message == NULL));
 310
 311   if (error->name != NULL)
 312     {
 313       DBusString str1, str2;
 314       _dbus_string_init_const (&str1, error->name);
 315       _dbus_string_init_const (&str2, name);
 316       return _dbus_string_equal (&str1, &str2);
 317     }
 318   else
 319     return FALSE;
 320 }
 321
 322 /**
 323  * Checks whether an error occurred (the error is set).
 324  *
 325  * @param error the error object
 326  * @returns #TRUE if an error occurred
 327  */
 328 dbus_bool_t
 329 dbus_error_is_set (const DBusError *error)
 330 {
 331   _dbus_return_val_if_fail (error != NULL, FALSE);
 332   _dbus_assert ((error->name != NULL && error->message != NULL) ||
 333                 (error->name == NULL && error->message == NULL));
 334   return error->name != NULL;
 335 }
 336
 337 /**
 338  * Assigns an error name and message to a DBusError.
 339  * Does nothing if error is #NULL.
 340  *
 341  * The format may be #NULL, which means a (pretty much useless)
 342  * default message will be deduced from the name. This is not a good
 343  * idea, just go ahead and provide a useful error message. It won't
 344  * hurt you.
 345  *
 346  * If no memory can be allocated for the error message,
 347  * an out-of-memory error message will be set instead.
 348  *
 349  * @param error the error.or #NULL
 350  * @param name the error name
 351  * @param format printf-style format string.
 352  */
 353 void
 354 dbus_set_error (DBusError  *error,
 355                 const char *name,
 356                 const char *format,
 357                 ...)
 358 {
 359   DBusRealError *real;
 360   DBusString str;
 361   va_list args;
 362
 363   if (error == NULL)
 364     return;
 365
 366   /* it's a bug to pile up errors */
 367   _dbus_return_if_error_is_set (error);
 368   _dbus_return_if_fail (name != NULL);
 369
 370   _dbus_assert (error->name == NULL);
 371   _dbus_assert (error->message == NULL);
 372
 373   if (!_dbus_string_init (&str))
 374     goto nomem;
 375
 376   if (format == NULL)
 377     {
 378       if (!_dbus_string_append (&str,
 379                                 message_from_error (name)))
 380         {
 381           _dbus_string_free (&str);
 382           goto nomem;
 383         }
 384     }
 385   else
 386     {
 387       va_start (args, format);
 388       if (!_dbus_string_append_printf_valist (&str, format, args))
 389         {
 390           _dbus_string_free (&str);
 391           va_end (args);
 392           goto nomem;
 393         }
 394       va_end (args);
 395     }
 396
 397   real = (DBusRealError *)error;
 398
 399   if (!_dbus_string_steal_data (&str, &real->message))
 400     {
 401       _dbus_string_free (&str);
 402       goto nomem;
 403     }
 404   _dbus_string_free (&str);
 405
 406   real->name = _dbus_strdup (name);
 407   if (real->name == NULL)
 408     {
 409       dbus_free (real->message);
 410       real->message = NULL;
 411       goto nomem;
 412     }
 413   real->const_message = FALSE;
 414
 415   return;
 416
 417  nomem:
 418   _DBUS_SET_OOM (error);
 419 }
 420
 421 /** @} */ /* End public API */