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