-/* -*- mode: C; c-file-style: "gnu" -*- */
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
/* dbus-errors.c Error reporting
*
- * Copyright (C) 2002 Red Hat Inc.
+ * Copyright (C) 2002, 2004 Red Hat Inc.
* Copyright (C) 2003 CodeFactory AB
*
- * Licensed under the Academic Free License version 1.2
+ * Licensed under the Academic Free License version 2.1
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
*/
+
+#include <config.h>
#include "dbus-errors.h"
#include "dbus-internals.h"
+#include "dbus-string.h"
+#include "dbus-protocol.h"
#include <stdarg.h>
-#include <stdio.h>
+#include <string.h>
/**
- * @defgroup DBusErrors Error reporting
- * @ingroup DBus
- * @brief Error reporting
- *
- * Types and functions related to reporting errors.
- *
+ * @defgroup DBusErrorInternals Error reporting internals
+ * @ingroup DBusInternals
+ * @brief Error reporting internals
+ * @{
+ */
+
+/**
+ * @def DBUS_ERROR_INIT
*
- * In essence D-BUS error reporting works as follows:
+ * Expands to a suitable initializer for a DBusError on the stack.
+ * Declaring a DBusError with:
*
* @code
- * DBusResultCode result = DBUS_RESULT_SUCCESS;
- * dbus_some_function (arg1, arg2, &result);
- * if (result != DBUS_RESULT_SUCCESS)
- * printf ("an error occurred\n");
+ * DBusError error = DBUS_ERROR_INIT;
+ *
+ * do_things_with (&error);
* @endcode
*
- * @todo add docs with DBusError
+ * is a more concise form of:
*
- * @todo add dbus_error_is_set() to check
- * whether an error is set.
- *
- * @{
+ * @code
+ * DBusError error;
+ *
+ * dbus_error_init (&error);
+ * do_things_with (&error);
+ * @endcode
*/
+/**
+ * Internals of DBusError
+ */
typedef struct
{
- const char *name; /**< error name */
+ char *name; /**< error name */
char *message; /**< error message */
- unsigned int const_message : 1; /** Message is not owned by DBusError */
+ unsigned int const_message : 1; /**< Message is not owned by DBusError */
unsigned int dummy2 : 1; /**< placeholder */
unsigned int dummy3 : 1; /**< placeholder */
} DBusRealError;
+_DBUS_STATIC_ASSERT (sizeof (DBusRealError) == sizeof (DBusError));
+
/**
- * Set a result code at a result code location,
- * if code_address is not #NULL.
+ * Returns a longer message describing an error name.
+ * If the error name is unknown, returns the name
+ * itself.
*
- * @param code_address place to store the result code.
- * @param code the result code itself.
+ * @param error the error to describe
+ * @returns a constant string describing the error.
*/
-void
-dbus_set_result (DBusResultCode *code_address,
- DBusResultCode code)
+static const char*
+message_from_error (const char *error)
{
- if (code_address)
- *code_address = code;
+ if (strcmp (error, DBUS_ERROR_FAILED) == 0)
+ return "Unknown error";
+ else if (strcmp (error, DBUS_ERROR_NO_MEMORY) == 0)
+ return "Not enough memory available";
+ else if (strcmp (error, DBUS_ERROR_IO_ERROR) == 0)
+ return "Error reading or writing data";
+ else if (strcmp (error, DBUS_ERROR_BAD_ADDRESS) == 0)
+ return "Could not parse address";
+ else if (strcmp (error, DBUS_ERROR_NOT_SUPPORTED) == 0)
+ return "Feature not supported";
+ else if (strcmp (error, DBUS_ERROR_LIMITS_EXCEEDED) == 0)
+ return "Resource limits exceeded";
+ else if (strcmp (error, DBUS_ERROR_ACCESS_DENIED) == 0)
+ return "Permission denied";
+ else if (strcmp (error, DBUS_ERROR_AUTH_FAILED) == 0)
+ return "Could not authenticate to server";
+ else if (strcmp (error, DBUS_ERROR_NO_SERVER) == 0)
+ return "No server available at address";
+ else if (strcmp (error, DBUS_ERROR_TIMEOUT) == 0)
+ return "Connection timed out";
+ else if (strcmp (error, DBUS_ERROR_NO_NETWORK) == 0)
+ return "Network unavailable";
+ else if (strcmp (error, DBUS_ERROR_ADDRESS_IN_USE) == 0)
+ return "Address already in use";
+ else if (strcmp (error, DBUS_ERROR_DISCONNECTED) == 0)
+ return "Disconnected.";
+ else if (strcmp (error, DBUS_ERROR_INVALID_ARGS) == 0)
+ return "Invalid arguments.";
+ else if (strcmp (error, DBUS_ERROR_NO_REPLY) == 0)
+ return "Did not get a reply message.";
+ else if (strcmp (error, DBUS_ERROR_FILE_NOT_FOUND) == 0)
+ return "File doesn't exist.";
+ else if (strcmp (error, DBUS_ERROR_OBJECT_PATH_IN_USE) == 0)
+ return "Object path already in use";
+ else
+ return error;
}
+/** @} */ /* End of internals */
+
/**
- * Returns a string describing the given result code.
+ * @defgroup DBusErrors Error reporting
+ * @ingroup DBus
+ * @brief Error reporting
*
- * @param code the result code to describe.
- * @returns a constant string describing the code.
+ * Types and functions related to reporting errors.
+ *
+ *
+ * In essence D-Bus error reporting works as follows:
+ *
+ * @code
+ * DBusError error;
+ * dbus_error_init (&error);
+ * dbus_some_function (arg1, arg2, &error);
+ * if (dbus_error_is_set (&error))
+ * {
+ * fprintf (stderr, "an error occurred: %s\n", error.message);
+ * dbus_error_free (&error);
+ * }
+ * @endcode
+ *
+ * By convention, all functions allow #NULL instead of a DBusError*,
+ * so callers who don't care about the error can ignore it.
+ *
+ * There are some rules. An error passed to a D-Bus function must
+ * always be unset; you can't pass in an error that's already set. If
+ * a function has a return code indicating whether an error occurred,
+ * and also a #DBusError parameter, then the error will always be set
+ * if and only if the return code indicates an error occurred. i.e.
+ * the return code and the error are never going to disagree.
+ *
+ * An error only needs to be freed if it's been set, not if
+ * it's merely been initialized.
+ *
+ * You can check the specific error that occurred using
+ * dbus_error_has_name().
+ *
+ * Errors will not be set for programming errors, such as passing
+ * invalid arguments to the libdbus API. Instead, libdbus will print
+ * warnings, exit on a failed assertion, or even crash in those cases
+ * (in other words, incorrect use of the API results in undefined
+ * behavior, possibly accompanied by helpful debugging output if
+ * you're lucky).
+ *
+ * @{
*/
-const char*
-dbus_result_to_string (DBusResultCode code)
-{
- /* This is a switch to the compiler will complain if we
- * aren't handling some codes
- */
- switch (code)
- {
- case DBUS_RESULT_SUCCESS:
- return "Success";
- case DBUS_RESULT_FAILED:
- return "Unknown error";
- case DBUS_RESULT_NO_MEMORY:
- return "Not enough memory available";
- case DBUS_RESULT_IO_ERROR:
- return "Error reading or writing data";
- case DBUS_RESULT_BAD_ADDRESS:
- return "Could not parse address";
- case DBUS_RESULT_NOT_SUPPORTED:
- return "Feature not supported";
- case DBUS_RESULT_LIMITS_EXCEEDED:
- return "Resource limits exceeded";
- case DBUS_RESULT_ACCESS_DENIED:
- return "Permission denied";
- case DBUS_RESULT_AUTH_FAILED:
- return "Could not authenticate to server";
- case DBUS_RESULT_NO_SERVER:
- return "No server";
- case DBUS_RESULT_TIMEOUT:
- return "Connection timed out";
- case DBUS_RESULT_NO_NETWORK:
- return "Network unavailable";
- case DBUS_RESULT_ADDRESS_IN_USE:
- return "Address already in use";
- case DBUS_RESULT_DISCONNECTED:
- return "Disconnected.";
- case DBUS_RESULT_INVALID_ARGS:
- return "Invalid argumemts.";
- case DBUS_RESULT_NO_REPLY:
- return "Did not get a reply message.";
- case DBUS_RESULT_FILE_NOT_FOUND:
- return "File doesn't exist.";
-
- /* no default, it would break our compiler warnings */
- }
-
- return "Invalid error code";
-}
/**
- * Initializes a DBusError structure.
- *
- * @todo calling dbus_error_init() in here is no good,
- * for the same reason a GError* has to be set to NULL
- * before you pass it in.
+ * Initializes a DBusError structure. Does not allocate any memory;
+ * the error only needs to be freed if it is set at some point.
*
* @param error the DBusError.
*/
{
DBusRealError *real;
- _dbus_assert (error != NULL);
+ _dbus_return_if_fail (error != NULL);
_dbus_assert (sizeof (DBusError) == sizeof (DBusRealError));
}
/**
- * Frees an error created by dbus_error_init().
+ * Frees an error that's been set (or just initialized),
+ * then reinitializes the error as in dbus_error_init().
*
* @param error memory where the error is stored.
*/
{
DBusRealError *real;
+ _dbus_return_if_fail (error != NULL);
+
real = (DBusRealError *)error;
if (!real->const_message)
- dbus_free (real->message);
+ {
+ dbus_free (real->name);
+ dbus_free (real->message);
+ }
+
+ dbus_error_init (error);
}
/**
- * Assigns an error name and message to a DBusError.
- * Does nothing if error is #NULL.
+ * Assigns an error name and message to a DBusError. Does nothing if
+ * error is #NULL. The message may be #NULL, which means a default
+ * message will be deduced from the name. The default message will be
+ * totally useless, though, so using a #NULL message is not recommended.
*
- * @param error the error.
+ * Because this function does not copy the error name or message, you
+ * must ensure the name and message are global data that won't be
+ * freed. You probably want dbus_set_error() instead, in most cases.
+ *
+ * @param error the error or #NULL
* @param name the error name (not copied!!!)
* @param message the error message (not copied!!!)
*/
{
DBusRealError *real;
+ _dbus_return_if_error_is_set (error);
+ _dbus_return_if_fail (name != NULL);
+
if (error == NULL)
return;
+
+ _dbus_assert (error->name == NULL);
+ _dbus_assert (error->message == NULL);
+
+ if (message == NULL)
+ message = message_from_error (name);
real = (DBusRealError *)error;
- real->name = name;
+ real->name = (char*) name;
real->message = (char *)message;
real->const_message = TRUE;
}
/**
+ * Moves an error src into dest, freeing src and
+ * overwriting dest. Both src and dest must be initialized.
+ * src is reinitialized to an empty error. dest may not
+ * contain an existing error. If the destination is
+ * #NULL, just frees and reinits the source error.
+ *
+ * @param src the source error
+ * @param dest the destination error or #NULL
+ */
+void
+dbus_move_error (DBusError *src,
+ DBusError *dest)
+{
+ _dbus_return_if_error_is_set (dest);
+
+ if (dest)
+ {
+ dbus_error_free (dest);
+ *dest = *src;
+ dbus_error_init (src);
+ }
+ else
+ dbus_error_free (src);
+}
+
+/**
+ * Checks whether the error is set and has the given
+ * name.
+ * @param error the error
+ * @param name the name
+ * @returns #TRUE if the given named error occurred
+ */
+dbus_bool_t
+dbus_error_has_name (const DBusError *error,
+ const char *name)
+{
+ _dbus_return_val_if_fail (error != NULL, FALSE);
+ _dbus_return_val_if_fail (name != NULL, FALSE);
+
+ _dbus_assert ((error->name != NULL && error->message != NULL) ||
+ (error->name == NULL && error->message == NULL));
+
+ if (error->name != NULL)
+ {
+ DBusString str1, str2;
+ _dbus_string_init_const (&str1, error->name);
+ _dbus_string_init_const (&str2, name);
+ return _dbus_string_equal (&str1, &str2);
+ }
+ else
+ return FALSE;
+}
+
+/**
+ * Checks whether an error occurred (the error is set).
+ *
+ * @param error the error object
+ * @returns #TRUE if an error occurred
+ */
+dbus_bool_t
+dbus_error_is_set (const DBusError *error)
+{
+ _dbus_return_val_if_fail (error != NULL, FALSE);
+ _dbus_assert ((error->name != NULL && error->message != NULL) ||
+ (error->name == NULL && error->message == NULL));
+ return error->name != NULL;
+}
+
+/**
* Assigns an error name and message to a DBusError.
* Does nothing if error is #NULL.
*
+ * The format may be #NULL, which means a (pretty much useless)
+ * default message will be deduced from the name. This is not a good
+ * idea, just go ahead and provide a useful error message. It won't
+ * hurt you.
+ *
* If no memory can be allocated for the error message,
* an out-of-memory error message will be set instead.
*
- * @todo stdio.h shouldn't be included in this file,
- * should write _dbus_string_append_printf instead
- *
- * @param error the error.
- * @param name the error name (not copied!!!)
+ * @param error the error.or #NULL
+ * @param name the error name
* @param format printf-style format string.
*/
void
...)
{
DBusRealError *real;
- va_list args, args2;
- int message_length;
- char *message;
- char c;
-
+ DBusString str;
+ va_list args;
+
if (error == NULL)
return;
+
+ /* it's a bug to pile up errors */
+ _dbus_return_if_error_is_set (error);
+ _dbus_return_if_fail (name != NULL);
- va_start (args, format);
- /* Measure the message length */
- message_length = vsnprintf (&c, 1, format, args) + 1;
- va_end (args);
-
- message = dbus_malloc (message_length);
+ _dbus_assert (error->name == NULL);
+ _dbus_assert (error->message == NULL);
+
+ if (!_dbus_string_init (&str))
+ goto nomem;
- if (!message)
+ if (format == NULL)
{
- dbus_set_error_const (error, DBUS_ERROR_NO_MEMORY,
- "Failed to allocate memory for error message.");
- return;
+ if (!_dbus_string_append (&str,
+ message_from_error (name)))
+ {
+ _dbus_string_free (&str);
+ goto nomem;
+ }
+ }
+ else
+ {
+ va_start (args, format);
+ if (!_dbus_string_append_printf_valist (&str, format, args))
+ {
+ _dbus_string_free (&str);
+ va_end (args);
+ goto nomem;
+ }
+ va_end (args);
}
-
- va_start (args, format);
- vsprintf (message, format, args2);
- va_end (args);
real = (DBusRealError *)error;
+
+ if (!_dbus_string_steal_data (&str, &real->message))
+ {
+ _dbus_string_free (&str);
+ goto nomem;
+ }
+ _dbus_string_free (&str);
- real->name = name;
- real->message = message;
+ real->name = _dbus_strdup (name);
+ if (real->name == NULL)
+ {
+ dbus_free (real->message);
+ real->message = NULL;
+ goto nomem;
+ }
real->const_message = FALSE;
+
+ return;
+
+ nomem:
+ _DBUS_SET_OOM (error);
}
-/** @} */
+/** @} */ /* End public API */
projects / platform / upstream / dbus.git / blobdiff