1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-errors.c Error reporting
4 * Copyright (C) 2002 Red Hat Inc.
5 * Copyright (C) 2003 CodeFactory AB
7 * Licensed under the Academic Free License version 1.2
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "dbus-errors.h"
25 #include "dbus-internals.h"
31 * @defgroup DBusErrors Error reporting
33 * @brief Error reporting
35 * Types and functions related to reporting errors.
38 * In essence D-BUS error reporting works as follows:
41 * DBusResultCode result = DBUS_RESULT_SUCCESS;
42 * dbus_some_function (arg1, arg2, &result);
43 * if (result != DBUS_RESULT_SUCCESS)
44 * printf ("an error occurred\n");
47 * @todo add docs with DBusError
54 const char *name; /**< error name */
55 char *message; /**< error message */
57 unsigned int const_message : 1; /** Message is not owned by DBusError */
59 unsigned int dummy2 : 1; /**< placeholder */
60 unsigned int dummy3 : 1; /**< placeholder */
61 unsigned int dummy4 : 1; /**< placeholder */
62 unsigned int dummy5 : 1; /**< placeholder */
64 void *padding1; /**< placeholder */
69 * Returns a longer message describing an error name.
70 * If the error name is unknown, returns the name
73 * @param error the error to describe
74 * @returns a constant string describing the error.
77 message_from_error (const char *error)
79 if (strcmp (error, DBUS_ERROR_FAILED) == 0)
80 return "Unknown error";
81 else if (strcmp (error, DBUS_ERROR_NO_MEMORY) == 0)
82 return "Not enough memory available";
83 else if (strcmp (error, DBUS_ERROR_IO_ERROR) == 0)
84 return "Error reading or writing data";
85 else if (strcmp (error, DBUS_ERROR_BAD_ADDRESS) == 0)
86 return "Could not parse address";
87 else if (strcmp (error, DBUS_ERROR_NOT_SUPPORTED) == 0)
88 return "Feature not supported";
89 else if (strcmp (error, DBUS_ERROR_LIMITS_EXCEEDED) == 0)
90 return "Resource limits exceeded";
91 else if (strcmp (error, DBUS_ERROR_ACCESS_DENIED) == 0)
92 return "Permission denied";
93 else if (strcmp (error, DBUS_ERROR_AUTH_FAILED) == 0)
94 return "Could not authenticate to server";
95 else if (strcmp (error, DBUS_ERROR_NO_SERVER) == 0)
96 return "No server available at address";
97 else if (strcmp (error, DBUS_ERROR_TIMEOUT) == 0)
98 return "Connection timed out";
99 else if (strcmp (error, DBUS_ERROR_NO_NETWORK) == 0)
100 return "Network unavailable";
101 else if (strcmp (error, DBUS_ERROR_ADDRESS_IN_USE) == 0)
102 return "Address already in use";
103 else if (strcmp (error, DBUS_ERROR_DISCONNECTED) == 0)
104 return "Disconnected.";
105 else if (strcmp (error, DBUS_ERROR_INVALID_ARGS) == 0)
106 return "Invalid argumemts.";
107 else if (strcmp (error, DBUS_ERROR_NO_REPLY) == 0)
108 return "Did not get a reply message.";
109 else if (strcmp (error, DBUS_ERROR_FILE_NOT_FOUND) == 0)
110 return "File doesn't exist.";
116 * Initializes a DBusError structure. Does not allocate
117 * any memory; the error only needs to be freed
118 * if it is set at some point.
120 * @param error the DBusError.
123 dbus_error_init (DBusError *error)
127 _dbus_assert (error != NULL);
129 _dbus_assert (sizeof (DBusError) == sizeof (DBusRealError));
131 real = (DBusRealError *)error;
134 real->message = NULL;
136 real->const_message = TRUE;
140 * Frees an error that's been set (or just initialized),
141 * then reinitializes the error as in dbus_error_init().
143 * @param error memory where the error is stored.
146 dbus_error_free (DBusError *error)
150 real = (DBusRealError *)error;
152 if (!real->const_message)
153 dbus_free (real->message);
155 dbus_error_init (error);
159 * Assigns an error name and message to a DBusError.
160 * Does nothing if error is #NULL. The message may
161 * be NULL only if the error is DBUS_ERROR_NO_MEMORY.
163 * @param error the error.
164 * @param name the error name (not copied!!!)
165 * @param message the error message (not copied!!!)
168 dbus_set_error_const (DBusError *error,
177 /* it's a bug to pile up errors */
178 _dbus_assert (error->name == NULL);
179 _dbus_assert (error->message == NULL);
180 _dbus_assert (name != NULL);
183 message = message_from_error (name);
185 real = (DBusRealError *)error;
188 real->message = (char *)message;
189 real->const_message = TRUE;
193 * Moves an error src into dest, freeing src and
194 * overwriting dest. Both src and dest must be initialized.
195 * src is reinitialized to an empty error. dest may not
196 * contain an existing error. If the destination is
197 * #NULL, just frees and reinits the source error.
199 * @param src the source error
200 * @param dest the destination error or #NULL
203 dbus_move_error (DBusError *src,
206 _dbus_assert (!dbus_error_is_set (dest));
210 dbus_error_free (dest);
212 dbus_error_init (src);
215 dbus_error_free (src);
219 * Checks whether the error is set and has the given
221 * @param error the error
222 * @param name the name
223 * @returns #TRUE if the given named error occurred
226 dbus_error_has_name (const DBusError *error,
229 _dbus_assert (error != NULL);
230 _dbus_assert (name != NULL);
231 _dbus_assert ((error->name != NULL && error->message != NULL) ||
232 (error->name == NULL && error->message == NULL));
234 if (error->name != NULL)
236 DBusString str1, str2;
237 _dbus_string_init_const (&str1, error->name);
238 _dbus_string_init_const (&str2, name);
239 return _dbus_string_equal (&str1, &str2);
246 * Checks whether an error occurred (the error is set).
248 * @param error the error object
249 * @returns #TRUE if an error occurred
252 dbus_error_is_set (const DBusError *error)
254 _dbus_assert (error != NULL);
255 _dbus_assert ((error->name != NULL && error->message != NULL) ||
256 (error->name == NULL && error->message == NULL));
257 return error->name != NULL;
261 * Assigns an error name and message to a DBusError.
262 * Does nothing if error is #NULL.
264 * The format may be NULL only if the error is DBUS_ERROR_NO_MEMORY.
266 * If no memory can be allocated for the error message,
267 * an out-of-memory error message will be set instead.
269 * @todo stdio.h shouldn't be included in this file,
270 * should write _dbus_string_append_printf instead
272 * @param error the error.
273 * @param name the error name (not copied!!!)
274 * @param format printf-style format string.
277 dbus_set_error (DBusError *error,
291 /* it's a bug to pile up errors */
292 _dbus_assert (error->name == NULL);
293 _dbus_assert (error->message == NULL);
294 _dbus_assert (name != NULL);
297 format = message_from_error (name);
299 va_start (args, format);
300 /* Measure the message length */
301 message_length = vsnprintf (&c, 1, format, args) + 1;
304 message = dbus_malloc (message_length);
308 dbus_set_error_const (error, DBUS_ERROR_NO_MEMORY, NULL);
312 va_start (args, format);
313 vsprintf (message, format, args);
316 real = (DBusRealError *)error;
319 real->message = message;
320 real->const_message = FALSE;