Add dbus-1-tqt to this SVN tree

Please keep it in sync with the master at svn.trinitydesktop.org
This is revision 167 from that source


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/dependencies/dbus-1-tqt@1228687 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 514 insertions, 0 deletions

diff --git a/tqdbusmessage.h b/tqdbusmessage.h
new file mode 100644
index 0000000..665a83f
--- /dev/null
+++ b/tqdbusmessage.h
@@ -0,0 +1,514 @@
+/* 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
+