You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
477 lines
14 KiB
477 lines
14 KiB
/* 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
|