diff options
Diffstat (limited to 'tqdbusmessage.h')
| -rw-r--r-- | tqdbusmessage.h | 514 |
1 files changed, 0 insertions, 514 deletions
diff --git a/tqdbusmessage.h b/tqdbusmessage.h deleted file mode 100644 index 665a83f..0000000 --- a/tqdbusmessage.h +++ /dev/null @@ -1,514 +0,0 @@ -/* qdbusmessage.h TQT_DBusMessage object - * - * Copyright (C) 2005 Harald Fernengel <[email protected]> - * Copyright (C) 2005-2007 Kevin Krammer <[email protected]> - * - * 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 - |