dbus-errors.c revision afa4ffbd852686633086569cd34942917c5c49af 
1/* -*- mode: C; c-file-style: "gnu" -*- */
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 */
41typedef 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 */
65static const char*
66message_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
101    return error;
102}
103
104/** @} */ /* End of internals */
105
106/**
107 * @defgroup DBusErrors Error reporting
108 * @ingroup  DBus
109 * @brief Error reporting
110 *
111 * Types and functions related to reporting errors.
112 *
113 *
114 * In essence D-Bus error reporting works as follows:
115 *
116 * @code
117 * DBusError error;
118 * dbus_error_init (&error);
119 * dbus_some_function (arg1, arg2, &error);
120 * if (dbus_error_is_set (&error))
121 *   {
122 *     fprintf (stderr, "an error occurred: %s\n", error.message);
123 *     dbus_error_free (&error);
124 *   }
125 * @endcode
126 *
127 * By convention, all functions allow #NULL instead of a DBusError*,
128 * so callers who don't care about the error can ignore it.
129 *
130 * There are some rules. An error passed to a D-Bus function must
131 * always be unset; you can't pass in an error that's already set.  If
132 * a function has a return code indicating whether an error occurred,
133 * and also a #DBusError parameter, then the error will always be set
134 * if and only if the return code indicates an error occurred. i.e.
135 * the return code and the error are never going to disagree.
136 *
137 * An error only needs to be freed if it's been set, not if
138 * it's merely been initialized.
139 *
140 * You can check the specific error that occurred using
141 * dbus_error_has_name().
142 *
143 * Errors will not be set for programming errors, such as passing
144 * invalid arguments to the libdbus API. Instead, libdbus will print
145 * warnings, exit on a failed assertion, or even crash in those cases
146 * (in other words, incorrect use of the API results in undefined
147 * behavior, possibly accompanied by helpful debugging output if
148 * you're lucky).
149 *
150 * @{
151 */
152
153/**
154 * Initializes a DBusError structure. Does not allocate any memory;
155 * the error only needs to be freed if it is set at some point.
156 *
157 * @param error the DBusError.
158 */
159void
160dbus_error_init (DBusError *error)
161{
162  DBusRealError *real;
163
164  _dbus_return_if_fail (error != NULL);
165
166  _dbus_assert (sizeof (DBusError) == sizeof (DBusRealError));
167
168  real = (DBusRealError *)error;
169
170  real->name = NULL;
171  real->message = NULL;
172
173  real->const_message = TRUE;
174}
175
176/**
177 * Frees an error that's been set (or just initialized),
178 * then reinitializes the error as in dbus_error_init().
179 *
180 * @param error memory where the error is stored.
181 */
182void
183dbus_error_free (DBusError *error)
184{
185  DBusRealError *real;
186
187  _dbus_return_if_fail (error != NULL);
188
189  real = (DBusRealError *)error;
190
191  if (!real->const_message)
192    {
193      dbus_free (real->name);
194      dbus_free (real->message);
195    }
196
197  dbus_error_init (error);
198}
199
200/**
201 * Assigns an error name and message to a DBusError.  Does nothing if
202 * error is #NULL. The message may be #NULL, which means a default
203 * message will be deduced from the name. The default message will be
204 * totally useless, though, so using a #NULL message is not recommended.
205 *
206 * Because this function does not copy the error name or message, you
207 * must ensure the name and message are global data that won't be
208 * freed. You probably want dbus_set_error() instead, in most cases.
209 *
210 * @param error the error.or #NULL
211 * @param name the error name (not copied!!!)
212 * @param message the error message (not copied!!!)
213 */
214void
215dbus_set_error_const (DBusError  *error,
216		      const char *name,
217		      const char *message)
218{
219  DBusRealError *real;
220
221  _dbus_return_if_error_is_set (error);
222  _dbus_return_if_fail (name != NULL);
223
224  if (error == NULL)
225    return;
226
227  _dbus_assert (error->name == NULL);
228  _dbus_assert (error->message == NULL);
229
230  if (message == NULL)
231    message = message_from_error (name);
232
233  real = (DBusRealError *)error;
234
235  real->name = (char*) name;
236  real->message = (char *)message;
237  real->const_message = TRUE;
238}
239
240/**
241 * Moves an error src into dest, freeing src and
242 * overwriting dest. Both src and dest must be initialized.
243 * src is reinitialized to an empty error. dest may not
244 * contain an existing error. If the destination is
245 * #NULL, just frees and reinits the source error.
246 *
247 * @param src the source error
248 * @param dest the destination error or #NULL
249 */
250void
251dbus_move_error (DBusError *src,
252                 DBusError *dest)
253{
254  _dbus_return_if_error_is_set (dest);
255
256  if (dest)
257    {
258      dbus_error_free (dest);
259      *dest = *src;
260      dbus_error_init (src);
261    }
262  else
263    dbus_error_free (src);
264}
265
266/**
267 * Checks whether the error is set and has the given
268 * name.
269 * @param error the error
270 * @param name the name
271 * @returns #TRUE if the given named error occurred
272 */
273dbus_bool_t
274dbus_error_has_name (const DBusError *error,
275                     const char      *name)
276{
277  _dbus_return_val_if_fail (error != NULL, FALSE);
278  _dbus_return_val_if_fail (name != NULL, FALSE);
279
280  _dbus_assert ((error->name != NULL && error->message != NULL) ||
281                (error->name == NULL && error->message == NULL));
282
283  if (error->name != NULL)
284    {
285      DBusString str1, str2;
286      _dbus_string_init_const (&str1, error->name);
287      _dbus_string_init_const (&str2, name);
288      return _dbus_string_equal (&str1, &str2);
289    }
290  else
291    return FALSE;
292}
293
294/**
295 * Checks whether an error occurred (the error is set).
296 *
297 * @param error the error object
298 * @returns #TRUE if an error occurred
299 */
300dbus_bool_t
301dbus_error_is_set (const DBusError *error)
302{
303  _dbus_return_val_if_fail (error != NULL, FALSE);
304  _dbus_assert ((error->name != NULL && error->message != NULL) ||
305                (error->name == NULL && error->message == NULL));
306  return error->name != NULL;
307}
308
309/**
310 * Assigns an error name and message to a DBusError.
311 * Does nothing if error is #NULL.
312 *
313 * The format may be #NULL, which means a (pretty much useless)
314 * default message will be deduced from the name. This is not a good
315 * idea, just go ahead and provide a useful error message. It won't
316 * hurt you.
317 *
318 * If no memory can be allocated for the error message,
319 * an out-of-memory error message will be set instead.
320 *
321 * @param error the error.or #NULL
322 * @param name the error name
323 * @param format printf-style format string.
324 */
325void
326dbus_set_error (DBusError  *error,
327		const char *name,
328		const char *format,
329		...)
330{
331  DBusRealError *real;
332  DBusString str;
333  va_list args;
334
335  if (error == NULL)
336    return;
337
338  /* it's a bug to pile up errors */
339  _dbus_return_if_error_is_set (error);
340  _dbus_return_if_fail (name != NULL);
341
342  _dbus_assert (error->name == NULL);
343  _dbus_assert (error->message == NULL);
344
345  if (!_dbus_string_init (&str))
346    goto nomem;
347
348  if (format == NULL)
349    {
350      if (!_dbus_string_append (&str,
351                                message_from_error (name)))
352        {
353          _dbus_string_free (&str);
354          goto nomem;
355        }
356    }
357  else
358    {
359      va_start (args, format);
360      if (!_dbus_string_append_printf_valist (&str, format, args))
361        {
362          _dbus_string_free (&str);
363          goto nomem;
364        }
365      va_end (args);
366    }
367
368  real = (DBusRealError *)error;
369
370  if (!_dbus_string_steal_data (&str, &real->message))
371    {
372      _dbus_string_free (&str);
373      goto nomem;
374    }
375  _dbus_string_free (&str);
376
377  real->name = _dbus_strdup (name);
378  if (real->name == NULL)
379    {
380      dbus_free (real->message);
381      real->message = NULL;
382      goto nomem;
383    }
384  real->const_message = FALSE;
385
386  return;
387
388 nomem:
389  _DBUS_SET_OOM (error);
390}
391
392/** @} */ /* End public API */
393