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"
30 * @defgroup DBusErrors Error reporting
32 * @brief Error reporting
34 * Types and functions related to reporting errors.
37 * In essence D-BUS error reporting works as follows:
40 * DBusResultCode result = DBUS_RESULT_SUCCESS;
41 * dbus_some_function (arg1, arg2, &result);
42 * if (result != DBUS_RESULT_SUCCESS)
43 * printf ("an error occurred\n");
46 * @todo add docs with DBusError
48 * @todo add dbus_error_is_set() to check
49 * whether an error is set.
56 const char *name; /**< error name */
57 char *message; /**< error message */
59 unsigned int const_message : 1; /** Message is not owned by DBusError */
61 unsigned int dummy2 : 1; /**< placeholder */
62 unsigned int dummy3 : 1; /**< placeholder */
63 unsigned int dummy4 : 1; /**< placeholder */
64 unsigned int dummy5 : 1; /**< placeholder */
66 void *padding1; /**< placeholder */
71 * Set a result code at a result code location,
72 * if code_address is not #NULL.
74 * @param code_address place to store the result code.
75 * @param code the result code itself.
78 dbus_set_result (DBusResultCode *code_address,
86 * Returns a string describing the given result code.
88 * @param code the result code to describe.
89 * @returns a constant string describing the code.
92 dbus_result_to_string (DBusResultCode code)
94 /* This is a switch to the compiler will complain if we
95 * aren't handling some codes
99 case DBUS_RESULT_SUCCESS:
101 case DBUS_RESULT_FAILED:
102 return "Unknown error";
103 case DBUS_RESULT_NO_MEMORY:
104 return "Not enough memory available";
105 case DBUS_RESULT_IO_ERROR:
106 return "Error reading or writing data";
107 case DBUS_RESULT_BAD_ADDRESS:
108 return "Could not parse address";
109 case DBUS_RESULT_NOT_SUPPORTED:
110 return "Feature not supported";
111 case DBUS_RESULT_LIMITS_EXCEEDED:
112 return "Resource limits exceeded";
113 case DBUS_RESULT_ACCESS_DENIED:
114 return "Permission denied";
115 case DBUS_RESULT_AUTH_FAILED:
116 return "Could not authenticate to server";
117 case DBUS_RESULT_NO_SERVER:
119 case DBUS_RESULT_TIMEOUT:
120 return "Connection timed out";
121 case DBUS_RESULT_NO_NETWORK:
122 return "Network unavailable";
123 case DBUS_RESULT_ADDRESS_IN_USE:
124 return "Address already in use";
125 case DBUS_RESULT_DISCONNECTED:
126 return "Disconnected.";
127 case DBUS_RESULT_INVALID_ARGS:
128 return "Invalid argumemts.";
129 case DBUS_RESULT_NO_REPLY:
130 return "Did not get a reply message.";
131 case DBUS_RESULT_FILE_NOT_FOUND:
132 return "File doesn't exist.";
134 /* no default, it would break our compiler warnings */
137 return "Invalid error code";
141 * Initializes a DBusError structure.
143 * @todo calling dbus_error_init() in here is no good,
144 * for the same reason a GError* has to be set to NULL
145 * before you pass it in.
147 * @param error the DBusError.
150 dbus_error_init (DBusError *error)
154 _dbus_assert (error != NULL);
156 _dbus_assert (sizeof (DBusError) == sizeof (DBusRealError));
158 real = (DBusRealError *)error;
161 real->message = NULL;
163 real->const_message = TRUE;
167 * Frees an error created by dbus_error_init().
169 * @param error memory where the error is stored.
172 dbus_error_free (DBusError *error)
176 real = (DBusRealError *)error;
178 if (!real->const_message)
179 dbus_free (real->message);
183 * Assigns an error name and message to a DBusError.
184 * Does nothing if error is #NULL.
186 * @param error the error.
187 * @param name the error name (not copied!!!)
188 * @param message the error message (not copied!!!)
191 dbus_set_error_const (DBusError *error,
200 /* it's a bug to pile up errors */
201 _dbus_assert (error->name == NULL);
202 _dbus_assert (error->message == NULL);
203 _dbus_assert (name != NULL);
204 _dbus_assert (message != NULL);
206 real = (DBusRealError *)error;
209 real->message = (char *)message;
210 real->const_message = TRUE;
214 * Checks whether the error is set and has the given
216 * @param error the error
217 * @param name the name
218 * @returns #TRUE if the given named error occurred
221 dbus_error_has_name (const DBusError *error,
224 _dbus_assert (error != NULL);
225 _dbus_assert (name != NULL);
226 _dbus_assert ((error->name != NULL && error->message != NULL) ||
227 (error->name == NULL && error->message == NULL));
229 if (error->name != NULL)
231 DBusString str1, str2;
232 _dbus_string_init_const (&str1, error->name);
233 _dbus_string_init_const (&str2, name);
234 return _dbus_string_equal (&str1, &str2);
241 * Checks whether an error occurred (the error is set).
243 * @param error the error object
244 * @returns #TRUE if an error occurred
247 dbus_error_is_set (const DBusError *error)
249 _dbus_assert (error != NULL);
250 _dbus_assert ((error->name != NULL && error->message != NULL) ||
251 (error->name == NULL && error->message == NULL));
252 return error->name != NULL;
256 * Assigns an error name and message to a DBusError.
257 * Does nothing if error is #NULL.
259 * If no memory can be allocated for the error message,
260 * an out-of-memory error message will be set instead.
262 * @todo stdio.h shouldn't be included in this file,
263 * should write _dbus_string_append_printf instead
265 * @param error the error.
266 * @param name the error name (not copied!!!)
267 * @param format printf-style format string.
270 dbus_set_error (DBusError *error,
284 /* it's a bug to pile up errors */
285 _dbus_assert (error->name == NULL);
286 _dbus_assert (error->message == NULL);
287 _dbus_assert (name != NULL);
288 _dbus_assert (format != NULL);
290 va_start (args, format);
291 /* Measure the message length */
292 message_length = vsnprintf (&c, 1, format, args) + 1;
295 message = dbus_malloc (message_length);
299 dbus_set_error_const (error, DBUS_ERROR_NO_MEMORY,
300 "Failed to allocate memory for error message.");
304 va_start (args, format);
305 vsprintf (message, format, args);
308 real = (DBusRealError *)error;
311 real->message = message;
312 real->const_message = FALSE;