-/* -*- 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 <string.h>
* @brief Error reporting internals
* @{
*/
-
+
+/**
+ * @def DBUS_ERROR_INIT
+ *
+ * Expands to a suitable initializer for a DBusError on the stack.
+ * Declaring a DBusError with:
+ *
+ * @code
+ * DBusError error = DBUS_ERROR_INIT;
+ *
+ * do_things_with (&error);
+ * @endcode
+ *
+ * is a more concise form of:
+ *
+ * @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 */
} DBusRealError;
+_DBUS_STATIC_ASSERT (sizeof (DBusRealError) == sizeof (DBusError));
+
/**
* Returns a longer message describing an error name.
* If the error name is unknown, returns the name
else if (strcmp (error, DBUS_ERROR_DISCONNECTED) == 0)
return "Disconnected.";
else if (strcmp (error, DBUS_ERROR_INVALID_ARGS) == 0)
- return "Invalid argumemts.";
+ 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;
}
* Types and functions related to reporting errors.
*
*
- * In essence D-BUS error reporting works as follows:
+ * In essence D-Bus error reporting works as follows:
*
* @code
* DBusError error;
* }
* @endcode
*
- * There are some rules. An error passed to a D-BUS function must
+ * 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
* 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).
+ *
* @{
*/
/**
- * Initializes a DBusError structure. Does not allocate
- * any memory; the error only needs to be freed
- * if it is set at some point.
+ * 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.
*/
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. The message may be NULL, which means a default
- * message will be deduced from the name. If the error name is unknown
- * to D-BUS the default message will be totally useless, though.
+ * 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.
*
- * @todo should be called dbus_error_set_const()
+ * 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.
+ * @param error the error or #NULL
* @param name the error name (not copied!!!)
* @param message the error message (not copied!!!)
*/
real = (DBusRealError *)error;
- real->name = name;
+ real->name = (char*) name;
real->message = (char *)message;
real->const_message = TRUE;
}
* Assigns an error name and message to a DBusError.
* Does nothing if error is #NULL.
*
- * The format may be NULL, which means a default message will be
- * deduced from the name. If the error name is unknown to D-BUS the
- * default message will be totally useless, though.
+ * 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 should be called dbus_error_set()
- *
- * @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
if (!_dbus_string_append_printf_valist (&str, format, args))
{
_dbus_string_free (&str);
+ va_end (args);
goto nomem;
}
va_end (args);
_dbus_string_free (&str);
goto nomem;
}
+ _dbus_string_free (&str);
- real->name = name;
+ real->name = _dbus_strdup (name);
+ if (real->name == NULL)
+ {
+ dbus_free (real->message);
+ real->message = NULL;
+ goto nomem;
+ }
real->const_message = FALSE;
- _dbus_string_free (&str);
-
return;
nomem:
- dbus_set_error_const (error, DBUS_ERROR_NO_MEMORY, NULL);
+ _DBUS_SET_OOM (error);
}
/** @} */ /* End public API */
projects / platform / upstream / dbus.git / blobdiff