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.
dbus-1-tqt/tqdbusmessage.h

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