1 files changed, 476 insertions, 0 deletions
diff --git a/src/tqdbuserror.h b/src/tqdbuserror.h
new file mode 100644
index 0000000..ff11ffb
--- /dev/null
+++ b/src/tqdbuserror.h
@@ -0,0 +1,476 @@
+/* qdbuserror.h TQT_DBusError object
+ *
+ * Copyright (C) 2005 Harald Fernengel <harry@kdevelop.org>
+ * Copyright (C) 2005 Kevin Krammer <kevin.krammer@gmx.at>
+ *
+ * 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
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ * USA.
+ *
+ */
+
+#ifndef TQDBUSERROR_H
+#define TQDBUSERROR_H
+
+#include "tqdbusmacros.h"
+#include <tqstring.h>
+
+struct DBusError;
+
+/**
+ * @brief Class for transporting D-Bus errors
+ *
+ * A D-Bus error has two parts: an error name (see section
+ * @ref dbusconventions-errorname) and a message string detailing the error in
+ * human presentable form.
+ */
+class TQDBUS_EXPORT TQT_DBusError
+{
+public:
+    /**
+     * @brief Enum of standard D-Bus error types
+     *
+     * D-Bus defines a list of common error types and their names.
+     * The values of this enum map to those an application is likely to encounter
+     * and likely to create itself.
+     *
+     * Standard errors can either be created by specifying the D-Bus error name
+     * or, as a convenience, by using factory methods of this class for the
+     * most common ones.
+     *
+     * All D-Bus standard error names are within the @c "org.freedesktop.DBus.Error"
+     * namespace.
+     *
+     * @see name()
+     */
+    enum ErrorType
+    {
+        /**
+         * @brief TQT_DBusError specific value, to represent invalid error objects.
+         *
+         * @see isValid()
+         */
+        InvalidError,
+
+        /**
+         * @brief Generic failure cause
+         *
+         * Can be used whenever the other predefined errors do no match. Basically
+         * just meaning "something when wrong, see message() for details"
+         *
+         * @see stdFailed()
+         */
+        Failed,
+
+        /**
+         * @brief An operation could not allocate enough memory
+         *
+         * @see stdNoMemory()
+         */
+        NoMemory,
+
+        /**
+         * @brief An addressed service is neither connected nor can it be activated
+         */
+        ServiceUnknown,
+
+        /**
+         * @brief A non-unique name used in a message is not known
+         *
+         * If a message addresses a D-Bus connection through a non-unique
+         * (requested) name and the D-Bus does not have a mapping to any of the
+         * unique names.
+         */
+        NameHasNoOwner,
+
+        /**
+         * @brief An call failed to send a reply but one was expected
+         *
+         * @see stdNoReply()
+         */
+        NoReply,
+
+        /**
+         * @brief An IO error occured during an operation
+         *
+         * Generic indicator that some kind of IO operation failed, e.g.
+         * reading from a socket.
+         *
+         * @see stdIOError()
+         */
+        IOError,
+
+        /**
+         * @brief Caused by trying to connect to a malformed address
+         *
+         * Returned by TQT_DBusConnection's addConnection if the specified address
+         * isn't a valid D-Bus bus address.
+         *
+         * @see TQT_DBusConnection::addConnection(const TQString&,const TQString&);
+         */
+        BadAddress,
+
+        /**
+         * @brief An otherwise valid operation request could not be handled
+         *
+         * Primarily useful when a service implements a specific interface but
+         * does not (yet) handle all possible situations.
+         *
+         * @see stdNotSupported()
+         */
+        NotSupported,
+
+        /**
+         * @brief Use of a limited resource reached its limit
+         *
+         * @see stdLimitsExceeded()
+         */
+        LimitsExceeded,
+
+        /**
+         * @brief Caused by security restrictions denying an operation
+         *
+         * Primarily useful when a client tries to manipulate resources a service
+         * has associated with a different client and which should not be changable
+         * by anyone else.
+         *
+         * @see stdAccessDenied()
+         */
+        AccessDenied,
+
+        /**
+         * @brief An authentification mechanism failed
+         *
+         * @see stdAuthFailed()
+         */
+        AuthFailed,
+
+        /**
+         * @brief Connection to a D-Bus server failed
+         */
+        NoServer,
+
+        /**
+         * @brief An timeout occured during an operation
+         *
+         * @warning D-Bus defined to quite similar errors but does not detail
+         *          when either one can occur. See #TimedOut
+         *
+         * @see stdTimeout()
+         */
+        Timeout,
+
+        /**
+         * @brief The network intended as a transport channel is not available
+         */
+        NoNetwork,
+
+        /**
+         * @brief Caused by trying to use an unconnected D-Bus connection
+         *
+         * @see TQT_DBusConnection::isConnected()
+         */
+        Disconnected,
+
+        /**
+         * @brief Caused by invalid arguments passed to a method call
+         *
+         * Primarily usefull for service implementations when the incoming
+         * call does not transport the expected parameters, e.g. wrong types
+         * or wrong values.
+         *
+         * @see stdInvalidArgs()
+         */
+        InvalidArgs,
+
+        /**
+         * @brief A file necessary for an operation is not avaiable
+         *
+         * @see stdFileNotFound()
+         */
+        FileNotFound,
+
+        /**
+         * @brief Target file exists but operation does not allow overwriting
+         *
+         * @see stdFileExists()
+         */
+        FileExists,
+
+        /**
+         * @brief A method call addresses and unknown method
+         *
+         * @see stdUnknownMethod()
+         */
+        UnknownMethod,
+
+        /**
+         * @brief An operation timed out
+         *
+         * @warning D-Bus defined to quite similar errors but does not detail
+         *          when either one can occur. See #Timeout
+         */
+        TimedOut,
+
+        /**
+         * @brief An type signature is not valid
+         *
+         * A possible cause is a TQT_DBusVariant with an invalid signature, i.e.
+         * the transported signature is empty, contains unknown type characters
+         * or has mismatched container enclosings.
+         *
+         * @note in case a service implementation wants to indicate that a method
+         *       call did not transport the correct parameter types, use
+         *       #InvalidArgs instead
+         *
+         * @see stdInvalidSignature()
+         */
+        InvalidSignature,
+
+        /**
+         * @brief Generic type for all errors not matching on of the other predefined
+         *
+         * @see TQT_DBusError(const TQString&,const TQString&);
+         */
+        UserDefined
+    };
+
+    /**
+     * @brief Creates an empty and invalid error object
+     */
+    TQT_DBusError();
+
+    /**
+     * @brief Creates an error object from an C API D-Bus error object
+     *
+     * @param error a pointer to the C API D-Bus error
+     */
+    TQT_DBusError(const DBusError *error);
+
+    /**
+     * @brief Creates an error object for its two given components
+     *
+     * @param error a D-Bus error name
+     * @param message the potentially i18n'ed error description message
+     *
+     * @see name()
+     */
+    TQT_DBusError(const TQString& error, const TQString& message);
+
+    /**
+     * @brief Returns the D-Bus error name
+     *
+     * See section @ref dbusconventions-errorname for details.
+     *
+     * @return the D-Bus error name
+     *
+     * @see message()
+     */
+    inline TQString name() const { return nm; }
+
+    /**
+     * @brief Returns a string describing the error
+     *
+     * The message is meant to further detail or describe the error.
+     * It is usually a translated error message meant for direct
+     * presentation to the user.
+     *
+     * @return the error's message
+     *
+     * @see name()
+     */
+    inline TQString message() const { return msg; }
+
+    /**
+     * @brief Returns a type for checking of standard errors
+     *
+     * D-Bus specifies a couple of standard error names, which are mapped to
+     * TQT_DBusError types in order to make creating and checking for them easier.
+     *
+     * @return the error's type
+     *
+     * @see name()
+     */
+    inline ErrorType type() const { return errorType; }
+
+    /**
+     * @brief Returns whether the error was caused by DBUS itself
+     *
+     * A TQT_DBusError is considered valid if both name and message are set.
+     *
+     * @return @c true if dbus_error_is_set was true after DBUS call completion
+     */
+    inline bool dbusErrorSet() const { return m_dbusErrorSet; }
+
+    /**
+     * @internal
+     */
+    inline void setDBUSError(bool err) const { m_dbusErrorSet = err; }
+
+    /**
+     * @brief Returns whether the error object is valid
+     *
+     * A TQT_DBusError is considered valid if both name and message are set.
+     *
+     * @return @c true if neither name nor message is @c TQString() and the
+     *         error type is a valid type
+     */
+    bool isValid() const;
+
+    /**
+     * @brief Creates a D-Bus standard error for generic failure
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #Failed with the given @p message
+     */
+    static TQT_DBusError stdFailed(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for out of memory situations
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #NoMemory with the given @p message
+     */
+    static TQT_DBusError stdNoMemory(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for expected reply missing
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #NoReply with the given @p message
+     */
+    static TQT_DBusError stdNoReply(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for generic IO errors
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #IOError with the given @p message
+     */
+    static TQT_DBusError stdIOError(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for unsupported operations
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #NotSupported with the given @p message
+     */
+    static TQT_DBusError stdNotSupported(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for exceeding a limited resource
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #LimitsExceeded with the given @p message
+     */
+    static TQT_DBusError stdLimitsExceeded(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for access to a resource being denied
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #AccessDenied with the given @p message
+     */
+    static TQT_DBusError stdAccessDenied(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for failed authentification
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #AuthFailed with the given @p message
+     */
+    static TQT_DBusError stdAuthFailed(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for timeouts during operations
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #Timeout with the given @p message
+     */
+    static TQT_DBusError stdTimeout(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for call arguments being invalid
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #InvalidArgs with the given @p message
+     */
+    static TQT_DBusError stdInvalidArgs(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for a file not being available
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #FileNotFound with the given @p message
+     */
+    static TQT_DBusError stdFileNotFound(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for a file being in the way
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #FileExists with the given @p message
+     */
+    static TQT_DBusError stdFileExists(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for an unknown methods being called
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #UnknownMethod with the given @p message
+     */
+    static TQT_DBusError stdUnknownMethod(const TQString& message);
+
+    /**
+     * @brief Creates a D-Bus standard error for D-Bus type signature not valid
+     *
+     * @param message the message detailing the encountered problem
+     *
+     * @return an error object of type #InvalidSignature with the given @p message
+     */
+    static TQT_DBusError stdInvalidSignature(const TQString& message);
+
+private:
+    ErrorType errorType;
+    mutable bool m_dbusErrorSet;
+
+    TQString nm, msg;
+
+    /**
+     * @brief Creates an error object for one of the standard D-Bus errors
+     *
+     * @param type one of the standard error causes
+     * @param message the potentially i18n'ed error description message
+     *
+     * @see ErrorType
+     */
+    TQT_DBusError(ErrorType type, const TQString& message);
+};
+
+#endif