diff options
Diffstat (limited to 'qt/qdbusmessage.cpp')
| -rw-r--r-- | qt/qdbusmessage.cpp | 254 |
1 files changed, 239 insertions, 15 deletions
diff --git a/qt/qdbusmessage.cpp b/qt/qdbusmessage.cpp index a77c22f0..5c604c13 100644 --- a/qt/qdbusmessage.cpp +++ b/qt/qdbusmessage.cpp @@ -1,6 +1,8 @@ /* qdbusmessage.cpp * * Copyright (C) 2005 Harald Fernengel <harry@kdevelop.org> + * Copyright (C) 2006 Trolltech AS. All rights reserved. + * Author: Thiago Macieira <thiago.macieira@trolltech.com> * * Licensed under the Academic Free License version 2.1 * @@ -15,19 +17,20 @@ * 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * along with this program; if not, write to the Free Software Foundation + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * */ #include "qdbusmessage.h" -#include <QtCore/qdebug.h> -#include <QtCore/qstringlist.h> +#include <qdebug.h> +#include <qstringlist.h> #include <dbus/dbus.h> #include "qdbusmarshall.h" +#include "qdbuserror.h" #include "qdbusmessage_p.h" QDBusMessagePrivate::QDBusMessagePrivate(QDBusMessage *qq) @@ -44,8 +47,31 @@ QDBusMessagePrivate::~QDBusMessagePrivate() } /////////////// +/*! + \class QDBusMessage + \brief Represents one message sent or received over the DBus bus. + + This object can represent any of four different types of messages possible on the bus + (see MessageType) + - Method calls + - Method return values + - Signal emissions + - Error codes + Objects of this type are created with the four static functions signal, methodCall, + methodReply and error. +*/ +/*! + Constructs a new DBus message representing a signal emission. A DBus signal is emitted + from one application and is received by all applications that are listening for that signal + from that interface. + + \param path the path of the object that is emitting the signal + \param interface the interface that is emitting the signal + \param name the name of the signal (a.k.a. method name) + \returns a QDBusMessage object that can be sent with with QDBusConnection::send +*/ QDBusMessage QDBusMessage::signal(const QString &path, const QString &interface, const QString &name) { @@ -58,19 +84,58 @@ QDBusMessage QDBusMessage::signal(const QString &path, const QString &interface, return message; } +/*! + Constructs a new DBus message representing a method call. A method call always informs + its destination address (service, path, interface and method). + + The DBus bus allows calling a method on a given remote object without specifying the + destination interface, if the method name is unique. However, if two interfaces on the + remote object export the same method name, the result is undefined (one of the two may be + called or an error may be returned). + + When using DBus in a peer-to-peer context (i.e., not on a bus), the service parameter is + optional. + + Optionally, a signature parameter can be passed, indicating the type of the parameters to + be marshalled over the bus. If there are more arguments thanentries in the signature, the + tailing arguments will be silently dropped and not sent. If there are less arguments, + default values will be inserted (default values are those created by QVariant::convert + when a variant of type QVariant::Invalid is converted to the type). + + The QDBusObject and QDBusInterface classes provide a simpler abstraction to synchronous + method calling. + + \param service the remote service to be called (can be a well-known name, a bus + address or null) + \param path the path of the object on the remote service to be called + \param interface the remote interface that is wanted (can be null) + \param method the remote method to be called (a.k.a., name) + \param sig the DBus signature (set to null to discard processing and guess the + method signature from the arguments; empty means no arguments) + \returns a QDBusMessage object that can be sent with QDBusConnection::send, + QDBusConnection::sendWithReply, or QDBusConnection::sendWithReplyAsync +*/ QDBusMessage QDBusMessage::methodCall(const QString &service, const QString &path, - const QString &interface, const QString &method) + const QString &interface, const QString &method, + const QString &sig) { QDBusMessage message; message.d->type = DBUS_MESSAGE_TYPE_METHOD_CALL; message.d->service = service; message.d->path = path; message.d->interface = interface; - message.d->method = method; + message.d->name = method; + message.d->signature = sig; return message; } +/*! + Constructs a new DBus message representing the return values from a called method. + + \param other the method call DBus message that this is a reply to + \returns a QDBusMessage object that can be sent with QDBusConnection::send +*/ QDBusMessage QDBusMessage::methodReply(const QDBusMessage &other) { Q_ASSERT(other.d->msg); @@ -82,11 +147,63 @@ QDBusMessage QDBusMessage::methodReply(const QDBusMessage &other) return message; } +/*! + Constructs a DBus message representing an error condition. + + \param other the QDBusMessage object that generated this error + \param name the DBus error name (error names must follow the same convention that + interface names do) + \param msg the error message + \return a QDBusMessage object that can be sent with QDBusMessage::send +*/ +QDBusMessage QDBusMessage::error(const QDBusMessage &other, const QString &name, + const QString &msg) +{ + Q_ASSERT(other.d->msg); + + QDBusMessage message; + message.d->type = DBUS_MESSAGE_TYPE_ERROR; + message.d->name = name; + message.d->message = msg; + message.d->reply = dbus_message_ref(other.d->msg); + + return message; +} + +/*! + \overload + Constructs a DBus message representing an error condition. + + \param other the QDBusMessage object that generated this error + \param error the QDBusError object representing this error + \return a QDBusMessage object that can be sent with QDBusMessage::send +*/ +QDBusMessage QDBusMessage::error(const QDBusMessage &other, const QDBusError &error) +{ + Q_ASSERT(other.d->msg); + + QDBusMessage message; + message.d->type = DBUS_MESSAGE_TYPE_ERROR; + message.d->name = error.name(); + message.d->message = error.message(); + message.d->reply = dbus_message_ref(other.d->msg); + + return message; +} + +/*! + Constructs an empty, invalid QDBusMessage object. + + \sa methodCall, methodReply, signal, error +*/ QDBusMessage::QDBusMessage() { d = new QDBusMessagePrivate(this); } +/*! + Constructs a copy of the other object. +*/ QDBusMessage::QDBusMessage(const QDBusMessage &other) : QList<QVariant>(other) { @@ -94,12 +211,18 @@ QDBusMessage::QDBusMessage(const QDBusMessage &other) d->ref.ref(); } +/*! + Disposes of the object and frees any resources that were being held. +*/ QDBusMessage::~QDBusMessage() { if (!d->ref.deref()) delete d; } +/*! + Copies the contents of the other object. +*/ QDBusMessage &QDBusMessage::operator=(const QDBusMessage &other) { QList<QVariant>::operator=(other); @@ -107,14 +230,20 @@ QDBusMessage &QDBusMessage::operator=(const QDBusMessage &other) return *this; } +/*! + \internal + Constructs a DBusMessage object from this object. The returned value must be de-referenced + with dbus_message_unref. +*/ DBusMessage *QDBusMessage::toDBusMessage() const { DBusMessage *msg = 0; + switch (d->type) { case DBUS_MESSAGE_TYPE_METHOD_CALL: msg = dbus_message_new_method_call(d->service.toUtf8().constData(), d->path.toUtf8().constData(), d->interface.toUtf8().constData(), - d->method.toUtf8().constData()); + d->name.toUtf8().constData()); break; case DBUS_MESSAGE_TYPE_SIGNAL: msg = dbus_message_new_signal(d->path.toUtf8().constData(), @@ -123,14 +252,22 @@ DBusMessage *QDBusMessage::toDBusMessage() const case DBUS_MESSAGE_TYPE_METHOD_RETURN: msg = dbus_message_new_method_return(d->reply); break; + case DBUS_MESSAGE_TYPE_ERROR: + msg = dbus_message_new_error(d->reply, d->name.toUtf8().constData(), + d->message.toUtf8().constData()); + break; } if (!msg) return 0; - QDBusMarshall::listToMessage(*this, msg); + QDBusMarshall::listToMessage(*this, msg, d->signature); return msg; } +/*! + \internal + Constructs a QDBusMessage by parsing the given DBusMessage object. +*/ QDBusMessage QDBusMessage::fromDBusMessage(DBusMessage *dmsg) { QDBusMessage message; @@ -140,40 +277,94 @@ QDBusMessage QDBusMessage::fromDBusMessage(DBusMessage *dmsg) message.d->type = dbus_message_get_type(dmsg); message.d->path = QString::fromUtf8(dbus_message_get_path(dmsg)); message.d->interface = QString::fromUtf8(dbus_message_get_interface(dmsg)); - message.d->name = QString::fromUtf8(dbus_message_get_member(dmsg)); - message.d->sender = QString::fromUtf8(dbus_message_get_sender(dmsg)); + message.d->name = message.d->type == DBUS_MESSAGE_TYPE_ERROR ? + QString::fromUtf8(dbus_message_get_error_name(dmsg)) : + QString::fromUtf8(dbus_message_get_member(dmsg)); + message.d->service = QString::fromUtf8(dbus_message_get_sender(dmsg)); + message.d->signature = QString::fromUtf8(dbus_message_get_signature(dmsg)); message.d->msg = dbus_message_ref(dmsg); QDBusMarshall::messageToList(message, dmsg); + return message; +} +/*! + Creates a QDBusMessage that represents the same error as the QDBusError object. +*/ +QDBusMessage QDBusMessage::fromError(const QDBusError &error) +{ + QDBusMessage message; + message.d->type = DBUS_MESSAGE_TYPE_ERROR; + message.d->name = error.name(); + message << error.message(); return message; } +/*! + Returns the path of the object that this message is being sent to (in the case of a + method call) or being received from (for a signal). +*/ QString QDBusMessage::path() const { return d->path; } +/*! + Returns the interface of the method being called (in the case of a method call) or of + the signal being received from. +*/ QString QDBusMessage::interface() const { return d->interface; } +/*! + Returns the name of the signal that was emitted or the name of the error that was + received. + \sa member +*/ QString QDBusMessage::name() const { return d->name; } -QString QDBusMessage::sender() const +/*! + \fn QDBusMessage::member + Returns the name of the method being called. +*/ + +/*! + \fn QDBusMessage::method + \overload + Returns the name of the method being called. +*/ + +/*! + Returns the name of the service or the bus address of the remote method call. +*/ +QString QDBusMessage::service() const { - return d->sender; + return d->service; } +/*! + \fn QDBusMessage::sender + Returns the unique name of the remote sender. +*/ + +/*! + Returns the timeout (in milliseconds) for this message to be processed. +*/ int QDBusMessage::timeout() const { return d->timeout; } +/*! + Sets the timeout for this message to be processed. + + \param ms the time, in milliseconds +*/ void QDBusMessage::setTimeout(int ms) { d->timeout = ms; @@ -205,6 +396,18 @@ int QDBusMessage::replySerialNumber() const return dbus_message_get_reply_serial(d->msg); } +/*! + Returns the signature of the signal that was received or for the output arguments + of a method call. +*/ +QString QDBusMessage::signature() const +{ + return d->signature; +} + +/*! + Returns the message type. +*/ QDBusMessage::MessageType QDBusMessage::type() const { switch (d->type) { @@ -222,11 +425,32 @@ QDBusMessage::MessageType QDBusMessage::type() const } #ifndef QT_NO_DEBUG +QDebug operator<<(QDebug dbg, QDBusMessage::MessageType t) +{ + switch (t) + { + case QDBusMessage::MethodCallMessage: + return dbg << "MethodCall"; + case QDBusMessage::ReplyMessage: + return dbg << "MethodReturn"; + case QDBusMessage::SignalMessage: + return dbg << "Signal"; + case QDBusMessage::ErrorMessage: + return dbg << "Error"; + default: + return dbg << "Invalid"; + } +} + QDebug operator<<(QDebug dbg, const QDBusMessage &msg) { - dbg.nospace() << "QDBusMessage(" << msg.path() << ", " << msg.interface() << ", " - << msg.name() << ", " << msg.sender() << ", " - << static_cast<QList<QVariant> >(msg) << ")"; + dbg.nospace() << "QDBusMessage(type=" << msg.type() + << ", service=" << msg.service() + << ", path=" << msg.path() + << ", interface=" << msg.interface() + << ", name=" << msg.name() + << ", signature=" << msg.signature() + << ", contents=" << static_cast<QList<QVariant> >(msg) << ")"; return dbg.space(); } #endif |