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.
515 lines
16 KiB
515 lines
16 KiB
/* qdbusmessage.h TQT_DBusMessage object
|
|
*
|
|
* Copyright (C) 2005 Harald Fernengel <harry@kdevelop.org>
|
|
* Copyright (C) 2005-2007 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 TQDBUSMESSAGE_H
|
|
#define TQDBUSMESSAGE_H
|
|
|
|
#include "tqdbusmacros.h"
|
|
#include "tqdbusdata.h"
|
|
|
|
#include <tqvaluelist.h>
|
|
|
|
#include <limits.h>
|
|
|
|
class TQT_DBusError;
|
|
class TQT_DBusMessagePrivate;
|
|
struct DBusMessage;
|
|
|
|
/**
|
|
* @brief A message converts and transports data over D-Bus
|
|
*
|
|
* A TQT_DBusMessage is implicitly shared, similar to a TQString, i.e. copying
|
|
* a message creates just a shallow copy.
|
|
*
|
|
* The TQT_DBusMessage is the TQt3 bindings means of encapsulating data for a
|
|
* method call, a method reply or an error.
|
|
*
|
|
* Data specifying the sender and receipient is directly accessible through
|
|
* getter methods, while data, e.g. method parameters or return values, are
|
|
* managed as a list of TQT_DBusData.
|
|
*
|
|
* To create a message suitable for sending use one of the static factory
|
|
* methods:
|
|
* - signal() for creating a D-Bus signal message
|
|
*
|
|
* - methodCall() for creating a D-Bus method calls to a service object
|
|
*
|
|
* - methodReply() for creating a method reply on success
|
|
*
|
|
* - methodError() for creating a method reply on error
|
|
*
|
|
* @note for applications that just want to perform method calls and/or receive
|
|
* signals, it is usually more convenient to use TQT_DBusProxy instead.
|
|
*
|
|
* Message sending is achieved through TQT_DBusConnection
|
|
*
|
|
* Example:
|
|
* @code
|
|
* TQT_DBusConnection con = TQT_DBusConnection::sessionBus();
|
|
*
|
|
* // receipient service is the bus' main interface
|
|
*
|
|
* TQString service = "org.freedesktop.DBus";
|
|
* TQString path = "/org/freedesktop/DBus";
|
|
* TQString interface = "org.freedesktop.DBus";
|
|
*
|
|
* TQT_DBusMessage msg = TQBusMessage::methodCall(service, path, interface, "ListNames");
|
|
*
|
|
* TQT_DBusMessage reply = con.sendWithReply(msg);
|
|
*
|
|
* // awaiting for a message list
|
|
*
|
|
* if (reply.type() != TQT_DBusMessage::ReplyMessage || reply.count() != 2 ||
|
|
* reply[0].type() != TQT_DBusData::List)
|
|
* {
|
|
* // error handling here
|
|
* }
|
|
* else
|
|
* {
|
|
* TQStringList list = reply[0].toTQStringList();
|
|
*
|
|
* // reply handling here
|
|
* }
|
|
* @endcode
|
|
*
|
|
* A service returning such a reply would do something like this
|
|
* @code
|
|
* bool Service::handleMethodCall(const TQT_DBusMessage& call)
|
|
* {
|
|
* // checks for correctness, i.e. correct interface, member,
|
|
* // would usually haven been placed here
|
|
*
|
|
* TQStringList result;
|
|
* result << "Foo" << "Bar";
|
|
*
|
|
* TQT_DBusMessage reply = TQT_DBusMessage::methodReply(call);
|
|
* reply << TQT_DBusData::fromList(result);
|
|
*
|
|
* connection.send(reply);
|
|
*
|
|
* return true;
|
|
* }
|
|
* @endcode
|
|
*/
|
|
class TQDBUS_EXPORT TQT_DBusMessage: public TQValueList<TQT_DBusData>
|
|
{
|
|
friend class TQT_DBusConnection;
|
|
public:
|
|
/**
|
|
* @brief Anonymous enum for timeout constants
|
|
*
|
|
* @see timeout()
|
|
* @see setTimeout()
|
|
*/
|
|
enum
|
|
{
|
|
/**
|
|
* Use whatever D-Bus has as default timeout
|
|
*/
|
|
DefaultTimeout = -1,
|
|
|
|
/**
|
|
* Use no timeout at all, i.e. wait as long as necessary
|
|
*/
|
|
NoTimeout = INT_MAX
|
|
};
|
|
|
|
/**
|
|
* @brief D-Bus message types
|
|
*
|
|
* A message of a specific type can be created using the respective factory
|
|
* method. A message created by the default constructor becomes an
|
|
* InvalidMessage
|
|
*
|
|
* @see type()
|
|
* @see signal()
|
|
* @see methodCall()
|
|
* @see methodReply()
|
|
* @see methodError()
|
|
*/
|
|
enum MessageType
|
|
{
|
|
/**
|
|
* An invalid message cannot be sent over D-Bus. This type serves for
|
|
* initializing message variables without requiring a "real" message
|
|
*/
|
|
InvalidMessage,
|
|
|
|
/**
|
|
* A message for doing method calls on remote service objects
|
|
*
|
|
* @see methodCall()
|
|
*/
|
|
MethodCallMessage,
|
|
|
|
/**
|
|
* A message for replying to a method call in case of success
|
|
*
|
|
* @see methodReply()
|
|
*/
|
|
ReplyMessage,
|
|
|
|
/**
|
|
* A message for replying to a method call in case of failure
|
|
*
|
|
* @see methodError()
|
|
*/
|
|
ErrorMessage,
|
|
|
|
/**
|
|
* A message for emitting D-Bus signals
|
|
*
|
|
* @see signal()
|
|
*/
|
|
SignalMessage
|
|
};
|
|
|
|
/**
|
|
* @brief Creates an empty and invalid message
|
|
*
|
|
* To create a message suitable for sending through D-Bus see the factory
|
|
* methods signal(), methodCall(), methodReply() and methodError()
|
|
*
|
|
* @see #InvalidMessage
|
|
*/
|
|
TQT_DBusMessage();
|
|
|
|
|
|
/**
|
|
* @brief Creates a shallow copy of the given message
|
|
*
|
|
* This instance will become a handle to the same message data the other
|
|
* message is using, including #MessageType
|
|
*
|
|
* @param other the message to copy
|
|
*/
|
|
TQT_DBusMessage(const TQT_DBusMessage &other);
|
|
|
|
/**
|
|
* @brief Destroys a message
|
|
*
|
|
* If this message handle is the last one using this respective message
|
|
* content, the message content will be deleted as well
|
|
*/
|
|
~TQT_DBusMessage();
|
|
|
|
/**
|
|
* @brief Creates a shallow copy of the given message
|
|
*
|
|
* This instance will become a handle to the same message data the other
|
|
* message is usingm including #MessageType
|
|
*
|
|
* Any content used in this instance will be deleted if this instance was
|
|
* the last handle using that content
|
|
*
|
|
* @param other the message to copy
|
|
*
|
|
* @return a reference to this instance as required by assignment operator
|
|
* semantics
|
|
*/
|
|
TQT_DBusMessage &operator=(const TQT_DBusMessage &other);
|
|
|
|
/**
|
|
* @brief Creates a message for sending a D-Bus signal
|
|
*
|
|
* Sending/emitting a signal over D-Bus requires a message of type
|
|
* #SignalMessage as well as the information where it is coming from, i.e.
|
|
* which interface of which object is sending it.
|
|
* See @ref dbusconventions for recommendations on those parameters.
|
|
*
|
|
* @param path the object path of the service object
|
|
* @param interface the object's interface to which the signal belongs
|
|
* @param member the signal's name
|
|
*
|
|
* @return a message suitable for appending arguments and for sending
|
|
*
|
|
* @see TQT_DBusConnection::send()
|
|
*/
|
|
static TQT_DBusMessage signal(const TQString &path, const TQString &interface,
|
|
const TQString &member);
|
|
|
|
/**
|
|
* @brief Creates a message for sending a D-Bus method call
|
|
*
|
|
* Invoking a method over D-Bus requires a message of type
|
|
* #MethodCallMessage as well as the information where it should be sent
|
|
* to, e.g which interface of which object in which service.
|
|
* See @ref dbusconventions for recommendations on those parameters.
|
|
*
|
|
* @param service the D-Bus name of the application hosting the service
|
|
* object
|
|
* @param path the object path of the service object
|
|
* @param interface the object's interface to which the method belongs
|
|
* @param method the method's name
|
|
*
|
|
* @return a message suitable for appending arguments and for sending
|
|
*
|
|
* @see methodReply()
|
|
* @see methodError()
|
|
* @see TQT_DBusConnection::send()
|
|
*/
|
|
static TQT_DBusMessage methodCall(const TQString &service, const TQString &path,
|
|
const TQString &interface, const TQString &method);
|
|
|
|
/**
|
|
* @brief Creates a message for replying to a D-Bus method call
|
|
*
|
|
* Replying to a D-Bus method call in the case of success requires a message
|
|
* of type #ReplyMessage as well as the information to which method call it
|
|
* is replying to.
|
|
*
|
|
* @param other the method call message it is replying to
|
|
*
|
|
* @return a message suitable for appending arguments and for sending
|
|
*
|
|
* @see methodCall()
|
|
* @see methodError()
|
|
* @see TQT_DBusConnection::send()
|
|
*/
|
|
static TQT_DBusMessage methodReply(const TQT_DBusMessage &other);
|
|
|
|
/**
|
|
* @brief Creates a message for replying to a D-Bus method call
|
|
*
|
|
* Replying to a D-Bus method call in the case of failure requires a message
|
|
* of type #ErrorMessage as well as the information to which method call it
|
|
* is replying to and which error occured.
|
|
*
|
|
* @param other the method call message it is replying to
|
|
* @param error the error which occured during during the method call
|
|
*
|
|
* @return a message suitable for appending arguments and for sending
|
|
*
|
|
* @see methodCall()
|
|
* @see methodReply()
|
|
* @see TQT_DBusConnection::send()
|
|
*/
|
|
static TQT_DBusMessage methodError(const TQT_DBusMessage &other, const TQT_DBusError& error);
|
|
|
|
/**
|
|
* @brief Returns the message's object path
|
|
*
|
|
* See section @ref dbusconventions-objectpath for details.
|
|
*
|
|
* The context of the object path depends on the message type:
|
|
* - #SignalMessage: the path of the service object which emits the signal
|
|
* - #MethodCallMessage: the path of the service object the call is sent to
|
|
* - #ReplyMessage: the path of the object which is replying
|
|
* - #ErrorMessage: the path of the object which is replying
|
|
*
|
|
* @return a non-empty object path or @c TQString()
|
|
*
|
|
* @see interface()
|
|
* @see member()
|
|
* @see sender()
|
|
*/
|
|
TQString path() const;
|
|
|
|
/**
|
|
* @brief Returns the message's interface name
|
|
*
|
|
* See section @ref dbusconventions-interfacename for details.
|
|
*
|
|
* The context of the interface name depends on the message type:
|
|
* - #SignalMessage: the name of the interface which emits the signal
|
|
* - #MethodCallMessage: the name of the interface the call is sent to
|
|
* - #ReplyMessage: the name of the interface to which the method belonged
|
|
* - #ErrorMessage: the name of the interface to which the method belonged
|
|
*
|
|
* @return a non-empty interface name or @c TQString()
|
|
*
|
|
* @see path()
|
|
* @see member()
|
|
* @see sender()
|
|
*/
|
|
TQString interface() const;
|
|
|
|
/**
|
|
* @brief Returns the message's member name
|
|
*
|
|
* See section @ref dbusconventions-membername for details.
|
|
*
|
|
* The context of the member name depends on the message type:
|
|
* - #SignalMessage: the name of the emitted signal
|
|
* - #MethodCallMessage: the name of the method to call
|
|
* - #ReplyMessage: the name of the method which replies
|
|
* - #ErrorMessage: the name of the method which replies
|
|
*
|
|
* @return a non-empty member name or @c TQString()
|
|
*
|
|
* @see path()
|
|
* @see interface()
|
|
* @see sender()
|
|
*/
|
|
TQString member() const;
|
|
|
|
/**
|
|
* @brief Returns the name of the message sender
|
|
*
|
|
* The message sender name or address used on the D-Bus message bus
|
|
* to refer to the application which sent this message.
|
|
*
|
|
* See section @ref dbusconventions-servicename for details.
|
|
*
|
|
* This can either be a unique name as handed out by the bus, see
|
|
* TQT_DBusConnection::uniqueName() or a name registered with
|
|
* TQT_DBusConnection::requestName()
|
|
*
|
|
* @return a non-empty D-Bus sender name or @c TQString()
|
|
*
|
|
* @see path()
|
|
* @see interface()
|
|
* @see member()
|
|
*/
|
|
TQString sender() const;
|
|
|
|
/**
|
|
* @brief Returns the error of an error message
|
|
*
|
|
* If this message is of type #ErrorMessage, this method can be used
|
|
* to retrieve the respective error object
|
|
*
|
|
* @return the transported error object. Will be empty if this is not an
|
|
* error message
|
|
*
|
|
* @see type()
|
|
*/
|
|
TQT_DBusError error() const;
|
|
|
|
/**
|
|
* @brief Returns which kind of message this is
|
|
*
|
|
* @return the message's type
|
|
*/
|
|
MessageType type() const;
|
|
|
|
/**
|
|
* @brief Returns the message's timeout
|
|
*
|
|
* @return the asynchronous wait timeout in milliseconds
|
|
*
|
|
* @see setTimeout()
|
|
*/
|
|
int timeout() const;
|
|
|
|
/**
|
|
* @brief Sets the message's timeout
|
|
*
|
|
* The timeout is the number of milliseconds the D-Bus connection will
|
|
* wait for the reply of an asynchronous call.
|
|
*
|
|
* If no reply is received in time, an error message will be delivered to
|
|
* the asynchronous reply receiver.
|
|
*
|
|
* If no timeout is set explicitly, #DefaultTimeout is assumed, which is
|
|
* usually the best option
|
|
*
|
|
* @return the asynchronous wait timeout in milliseconds
|
|
*
|
|
* @param ms timeout in milliseconds
|
|
*
|
|
* @see timeout()
|
|
* @see #DefaultTimeout
|
|
* @see #NoTimeout
|
|
*/
|
|
void setTimeout(int ms);
|
|
|
|
/**
|
|
* @brief Returns the message's serial number
|
|
*
|
|
* The serial number is some kind of short term identifier for messages
|
|
* travelling the same connection.
|
|
*
|
|
* It can be used to associate a reply or error message with a method
|
|
* call message.
|
|
*
|
|
* @return the message's serial number or @c 0 if the message hasn't been
|
|
* send yets
|
|
*
|
|
* @see replySerialNumber()
|
|
*/
|
|
int serialNumber() const;
|
|
|
|
/**
|
|
* @brief Returns the message's reply serial number
|
|
*
|
|
* The reply serial number is the serial number of the method call message
|
|
* this message is a reply to.
|
|
*
|
|
* If this is neither a message of type #ReplyMessage or #ErrorMessage, the
|
|
* returned value will be @c 0
|
|
*
|
|
* It can be used to associate a reply or error message with a method
|
|
* call message.
|
|
*
|
|
* @return the serial number of the associated method call message or @c 0
|
|
* if this message is not a reply message
|
|
*
|
|
* @see serialNumber()
|
|
* @see methodReply()
|
|
* @see methodError()
|
|
* @see TQT_DBusConnection::sendWithAsyncReply()
|
|
* @see TQT_DBusProxy::sendWithAsyncReply()
|
|
*/
|
|
int replySerialNumber() const;
|
|
|
|
//protected:
|
|
/**
|
|
* @brief Creates a raw D-Bus message from this TQt3-bindings message
|
|
*
|
|
* Marshalls data contained in the message's value list into D-Bus data
|
|
* format and creates a low level API D-Bus message for it.
|
|
*
|
|
* @note ownership of the returned message is transferred to the caller,
|
|
* i.e. it has to be deleted using dbus_message_unref()
|
|
*
|
|
* @return a C API D-Bus message or @c 0 if this is an #InvalidMessage
|
|
* or marshalling failed
|
|
*/
|
|
DBusMessage *toDBusMessage() const;
|
|
|
|
/**
|
|
* @brief Creates a TQt3-bindings message from the given raw D-Bus message
|
|
*
|
|
* De-marshalls data contained in the message to a list of TQT_DBusData.
|
|
*
|
|
* @note ownership of the given message is shared between the caller and
|
|
* the returned message, i.e. the message as increased the reference
|
|
* counter and will still have access to the raw message even if the
|
|
* caller "deleted" it using dbus_message_unref()
|
|
*
|
|
* @param dmsg a C API D-Bus message
|
|
*
|
|
* @return a TQt3 bindings message. Can be an #InvalidMessage if the given
|
|
* message was @c 0 or if de-marshalling failed
|
|
*/
|
|
static TQT_DBusMessage fromDBusMessage(DBusMessage *dmsg);
|
|
|
|
private:
|
|
TQT_DBusMessagePrivate *d;
|
|
};
|
|
|
|
#endif
|
|
|