X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dbus%2Fdbus-errors.c;h=a0571a50e07d5828e00350e2c23887a6f661deb1;hb=0b29f8c2879ea2ace52577ddae09c8dea7d5cbdc;hp=82e480251fa9314ab561b97de08af2c0a83f01cd;hpb=1d1b0f20a467cf1cbdcaf81fbad3a111bcff6c48;p=platform%2Fupstream%2Fdbus.git diff --git a/dbus/dbus-errors.c b/dbus/dbus-errors.c index 82e4802..a0571a5 100644 --- a/dbus/dbus-errors.c +++ b/dbus/dbus-errors.c @@ -1,10 +1,10 @@ -/* -*- 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 @@ -18,58 +18,56 @@ * * 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 #include "dbus-errors.h" #include "dbus-internals.h" #include "dbus-string.h" +#include "dbus-protocol.h" #include #include /** - * @defgroup DBusErrors Error reporting - * @ingroup DBus - * @brief Error reporting + * @defgroup DBusErrorInternals Error reporting internals + * @ingroup DBusInternals + * @brief Error reporting internals + * @{ + */ + +/** + * @def DBUS_ERROR_INIT * - * Types and functions related to reporting errors. + * Expands to a suitable initializer for a DBusError on the stack. + * Declaring a DBusError with: * + * @code + * DBusError error = DBUS_ERROR_INIT; * - * In essence D-BUS error reporting works as follows: + * do_things_with (&error); + * @endcode + * + * is a more concise form of: * * @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); - * } + * do_things_with (&error); * @endcode - * - * 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(). - * - * @{ */ +/** + * 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 */ @@ -80,6 +78,8 @@ typedef struct } 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 @@ -118,19 +118,69 @@ message_from_error (const char *error) 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; } +/** @} */ /* End of internals */ + +/** + * @defgroup DBusErrors Error reporting + * @ingroup DBus + * @brief Error reporting + * + * 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). + * + * @{ + */ + /** - * 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. */ @@ -167,20 +217,25 @@ dbus_error_free (DBusError *error) 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!!!) */ @@ -205,7 +260,7 @@ dbus_set_error_const (DBusError *error, real = (DBusRealError *)error; - real->name = name; + real->name = (char*) name; real->message = (char *)message; real->const_message = TRUE; } @@ -283,17 +338,16 @@ dbus_error_is_set (const DBusError *error) * 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 @@ -334,6 +388,7 @@ dbus_set_error (DBusError *error, if (!_dbus_string_append_printf_valist (&str, format, args)) { _dbus_string_free (&str); + va_end (args); goto nomem; } va_end (args); @@ -346,16 +401,21 @@ dbus_set_error (DBusError *error, _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 */