1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-errors.c Error reporting
4 * Copyright (C) 2002, 2004 Red Hat Inc.
5 * Copyright (C) 2003 CodeFactory AB
7 * Licensed under the Academic Free License version 2.1
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.
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.
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
24 #include "dbus-errors.h"
25 #include "dbus-internals.h"
26 #include "dbus-string.h"
27 #include "dbus-protocol.h"
32 * @defgroup DBusErrorInternals Error reporting internals
33 * @ingroup DBusInternals
34 * @brief Error reporting internals
39 * @def DBUS_ERROR_INIT
41 * Expands to a suitable initializer for a DBusError on the stack.
42 * Declaring a DBusError with:
45 * DBusError error = DBUS_ERROR_INIT;
47 * do_things_with (&error);
50 * is a more concise form of:
55 * dbus_error_init (&error);
56 * do_things_with (&error);
61 * Internals of DBusError
65 char *name; /**< error name */
66 char *message; /**< error message */
68 unsigned int const_message : 1; /**< Message is not owned by DBusError */
70 unsigned int dummy2 : 1; /**< placeholder */
71 unsigned int dummy3 : 1; /**< placeholder */
72 unsigned int dummy4 : 1; /**< placeholder */
73 unsigned int dummy5 : 1; /**< placeholder */
75 void *padding1; /**< placeholder */
80 * Returns a longer message describing an error name.
81 * If the error name is unknown, returns the name
84 * @param error the error to describe
85 * @returns a constant string describing the error.
88 message_from_error (const char *error)
90 if (strcmp (error, DBUS_ERROR_FAILED) == 0)
91 return "Unknown error";
92 else if (strcmp (error, DBUS_ERROR_NO_MEMORY) == 0)
93 return "Not enough memory available";
94 else if (strcmp (error, DBUS_ERROR_IO_ERROR) == 0)
95 return "Error reading or writing data";
96 else if (strcmp (error, DBUS_ERROR_BAD_ADDRESS) == 0)
97 return "Could not parse address";
98 else if (strcmp (error, DBUS_ERROR_NOT_SUPPORTED) == 0)
99 return "Feature not supported";
100 else if (strcmp (error, DBUS_ERROR_LIMITS_EXCEEDED) == 0)
101 return "Resource limits exceeded";
102 else if (strcmp (error, DBUS_ERROR_ACCESS_DENIED) == 0)
103 return "Permission denied";
104 else if (strcmp (error, DBUS_ERROR_AUTH_FAILED) == 0)
105 return "Could not authenticate to server";
106 else if (strcmp (error, DBUS_ERROR_NO_SERVER) == 0)
107 return "No server available at address";
108 else if (strcmp (error, DBUS_ERROR_TIMEOUT) == 0)
109 return "Connection timed out";
110 else if (strcmp (error, DBUS_ERROR_NO_NETWORK) == 0)
111 return "Network unavailable";
112 else if (strcmp (error, DBUS_ERROR_ADDRESS_IN_USE) == 0)
113 return "Address already in use";
114 else if (strcmp (error, DBUS_ERROR_DISCONNECTED) == 0)
115 return "Disconnected.";
116 else if (strcmp (error, DBUS_ERROR_INVALID_ARGS) == 0)
117 return "Invalid arguments.";
118 else if (strcmp (error, DBUS_ERROR_NO_REPLY) == 0)
119 return "Did not get a reply message.";
120 else if (strcmp (error, DBUS_ERROR_FILE_NOT_FOUND) == 0)
121 return "File doesn't exist.";
122 else if (strcmp (error, DBUS_ERROR_OBJECT_PATH_IN_USE) == 0)
123 return "Object path already in use";
128 /** @} */ /* End of internals */
131 * @defgroup DBusErrors Error reporting
133 * @brief Error reporting
135 * Types and functions related to reporting errors.
138 * In essence D-Bus error reporting works as follows:
142 * dbus_error_init (&error);
143 * dbus_some_function (arg1, arg2, &error);
144 * if (dbus_error_is_set (&error))
146 * fprintf (stderr, "an error occurred: %s\n", error.message);
147 * dbus_error_free (&error);
151 * By convention, all functions allow #NULL instead of a DBusError*,
152 * so callers who don't care about the error can ignore it.
154 * There are some rules. An error passed to a D-Bus function must
155 * always be unset; you can't pass in an error that's already set. If
156 * a function has a return code indicating whether an error occurred,
157 * and also a #DBusError parameter, then the error will always be set
158 * if and only if the return code indicates an error occurred. i.e.
159 * the return code and the error are never going to disagree.
161 * An error only needs to be freed if it's been set, not if
162 * it's merely been initialized.
164 * You can check the specific error that occurred using
165 * dbus_error_has_name().
167 * Errors will not be set for programming errors, such as passing
168 * invalid arguments to the libdbus API. Instead, libdbus will print
169 * warnings, exit on a failed assertion, or even crash in those cases
170 * (in other words, incorrect use of the API results in undefined
171 * behavior, possibly accompanied by helpful debugging output if
178 * Initializes a DBusError structure. Does not allocate any memory;
179 * the error only needs to be freed if it is set at some point.
181 * @param error the DBusError.
184 dbus_error_init (DBusError *error)
188 _dbus_return_if_fail (error != NULL);
190 _dbus_assert (sizeof (DBusError) == sizeof (DBusRealError));
192 real = (DBusRealError *)error;
195 real->message = NULL;
197 real->const_message = TRUE;
201 * Frees an error that's been set (or just initialized),
202 * then reinitializes the error as in dbus_error_init().
204 * @param error memory where the error is stored.
207 dbus_error_free (DBusError *error)
211 _dbus_return_if_fail (error != NULL);
213 real = (DBusRealError *)error;
215 if (!real->const_message)
217 dbus_free (real->name);
218 dbus_free (real->message);
221 dbus_error_init (error);
225 * Assigns an error name and message to a DBusError. Does nothing if
226 * error is #NULL. The message may be #NULL, which means a default
227 * message will be deduced from the name. The default message will be
228 * totally useless, though, so using a #NULL message is not recommended.
230 * Because this function does not copy the error name or message, you
231 * must ensure the name and message are global data that won't be
232 * freed. You probably want dbus_set_error() instead, in most cases.
234 * @param error the error.or #NULL
235 * @param name the error name (not copied!!!)
236 * @param message the error message (not copied!!!)
239 dbus_set_error_const (DBusError *error,
245 _dbus_return_if_error_is_set (error);
246 _dbus_return_if_fail (name != NULL);
251 _dbus_assert (error->name == NULL);
252 _dbus_assert (error->message == NULL);
255 message = message_from_error (name);
257 real = (DBusRealError *)error;
259 real->name = (char*) name;
260 real->message = (char *)message;
261 real->const_message = TRUE;
265 * Moves an error src into dest, freeing src and
266 * overwriting dest. Both src and dest must be initialized.
267 * src is reinitialized to an empty error. dest may not
268 * contain an existing error. If the destination is
269 * #NULL, just frees and reinits the source error.
271 * @param src the source error
272 * @param dest the destination error or #NULL
275 dbus_move_error (DBusError *src,
278 _dbus_return_if_error_is_set (dest);
282 dbus_error_free (dest);
284 dbus_error_init (src);
287 dbus_error_free (src);
291 * Checks whether the error is set and has the given
293 * @param error the error
294 * @param name the name
295 * @returns #TRUE if the given named error occurred
298 dbus_error_has_name (const DBusError *error,
301 _dbus_return_val_if_fail (error != NULL, FALSE);
302 _dbus_return_val_if_fail (name != NULL, FALSE);
304 _dbus_assert ((error->name != NULL && error->message != NULL) ||
305 (error->name == NULL && error->message == NULL));
307 if (error->name != NULL)
309 DBusString str1, str2;
310 _dbus_string_init_const (&str1, error->name);
311 _dbus_string_init_const (&str2, name);
312 return _dbus_string_equal (&str1, &str2);
319 * Checks whether an error occurred (the error is set).
321 * @param error the error object
322 * @returns #TRUE if an error occurred
325 dbus_error_is_set (const DBusError *error)
327 _dbus_return_val_if_fail (error != NULL, FALSE);
328 _dbus_assert ((error->name != NULL && error->message != NULL) ||
329 (error->name == NULL && error->message == NULL));
330 return error->name != NULL;
334 * Assigns an error name and message to a DBusError.
335 * Does nothing if error is #NULL.
337 * The format may be #NULL, which means a (pretty much useless)
338 * default message will be deduced from the name. This is not a good
339 * idea, just go ahead and provide a useful error message. It won't
342 * If no memory can be allocated for the error message,
343 * an out-of-memory error message will be set instead.
345 * @param error the error.or #NULL
346 * @param name the error name
347 * @param format printf-style format string.
350 dbus_set_error (DBusError *error,
362 /* it's a bug to pile up errors */
363 _dbus_return_if_error_is_set (error);
364 _dbus_return_if_fail (name != NULL);
366 _dbus_assert (error->name == NULL);
367 _dbus_assert (error->message == NULL);
369 if (!_dbus_string_init (&str))
374 if (!_dbus_string_append (&str,
375 message_from_error (name)))
377 _dbus_string_free (&str);
383 va_start (args, format);
384 if (!_dbus_string_append_printf_valist (&str, format, args))
386 _dbus_string_free (&str);
393 real = (DBusRealError *)error;
395 if (!_dbus_string_steal_data (&str, &real->message))
397 _dbus_string_free (&str);
400 _dbus_string_free (&str);
402 real->name = _dbus_strdup (name);
403 if (real->name == NULL)
405 dbus_free (real->message);
406 real->message = NULL;
409 real->const_message = FALSE;
414 _DBUS_SET_OOM (error);
417 /** @} */ /* End public API */