diff options
Diffstat (limited to 'tqdbusconnection.h')
| -rw-r--r-- | tqdbusconnection.h | 662 |
1 files changed, 662 insertions, 0 deletions
diff --git a/tqdbusconnection.h b/tqdbusconnection.h new file mode 100644 index 0000000..f9ae547 --- /dev/null +++ b/tqdbusconnection.h @@ -0,0 +1,662 @@ +/* qdbusconnection.h TQT_DBusConnection 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 TQDBUSCONNECTION_H +#define TQDBUSCONNECTION_H + +/** + * @mainpage TQt3 Bindings for D-Bus + * + * D-Bus is an IPC (inter process communication) technology designed to allow + * applications to interoperate without requiring tight coupling. + * + * For more information about D-Bus itself see its website: + * http://www.freedesktop.org/wiki/Software_2fdbus + * + * The TQt3 D-Bus bindings described here are a TQt3 style API around the base + * implementation to enable TQt3 developers to use D-Bus in their applications + * without requiring them to know about the details of the C based D-Bus API. + * + * The two main use cases are: + * - using the API to access service implemented in other applications. + * See section @ref dbusclient for an introduction on this + * + * - using the API to provide access to services implemented in your application + * See section @ref dbusservice for an introduction on this + * + * Of course an application can do both at the same time. + */ + +/** + * @page dbusconventions Naming and syntax conventions in D-Bus + * + * @section dbusconventions-servicename Service names + * + * The service name is D-Bus application identifier, i.e. either + * the unique name handed out to the peer application by the bus on connect + * (see TQT_DBusConnection::uniqueName()) or, more likely, a well known name the + * peer application has requested, see TQT_DBusConnection::requestName() + * + * Such well known names have the form of word separated by dots, like + * Internet domain names but in reverse order. + * + * For example the name for the bus itself (the D-Bus daemon) would be + * @code + * "org.freedesktop.DBus" + * @endcode + * + * @section dbusconventions-objectpath Object paths + * + * The object path is like an address within the peer host application. + * The path format looks like a Unix file path, i.e. words separated by + * slash @c '/' characters. + * + * For example the path for the bus itself (the D-Bus daemon's main object) + * would be + * @code + * "/org/freedesktop/DBus" + * @endcode + * + * @section dbusconventions-interfacename Interface names + * + * The interface name specifies which group of methods and signals + * implemented by the peer service object is used in proxy operations. + * + * Interface names have the form of word separated by dots, like Internet + * domain names but in reverse order or like a fully qualified Java class name. + * + * For example the interface for the bus itself (the D-Bus daemon's main + * interface) would be + * @code + * "org.freedesktop.DBus" + * @endcode + * + * @section dbusconventions-errorname Error names + * + * A D-Bus error name is a sequence of words separated by dots, similar + * to D-Bus service names or interface names, or like a fully qualified + * Java class name. + * + * For example if a D-Bus service does not handle a method invocation sent + * to it because it doesn't know about the method it will return a D-Bus + * error named + * @code + * "org.freedesktop.DBus.Error.UnknownMethod" + * @endcode + * TQT_DBusError can create some of the more common errors based on a type value + * and decode their names into the type respectively. See TQT_DBusError#ErrorType + * + * @section dbusconventions-membername Method and signal names + * + * There is no mandatory convention for member names, neither for methods nor + * for signals. + * + * However, using the standard interfaces of D-Bus as a hint, it is recommended + * to use "camel case" names starting with an uppercase letter, for example + * @code + * "GetConnectionUnixUser" + * @endcode + */ + +#include "tqdbusmacros.h" +#include <tqstring.h> + +class TQT_DBusConnectionPrivate; +class TQT_DBusError; +class TQT_DBusMessage; +class TQT_DBusObjectBase; +class TQObject; + +/** + * @brief Provides access to a specific D-Bus bus + * + * In order to access a D-Bus message bus an application has to connect to it. + * This is very similar to connecting to an FTP server using TQFtp, where any + * number of commands can be sent in sequence over the same connection. + * + * Additionally to the asynchronous command execution provided by TQFtp a + * TQT_DBusConnection can also execute synchronous (blocking) calls so the + * code around those calls stays closer to in-process method incovations. + * + * However it is recommended to only perform blocking calls on D-Bus service + * methods that are likely to be processed fast. + * + * TQT_DBusConnection implements a shared resource, i.e. if you create a + * connection with a specific name in one part of your code and then + * create one with the same name somewhere else, the second creation will + * actually return the same shared connection object the first caller created. + * + * The application can be connected to more than one message bus simultaniously + * using one or more connections per bus, however the most common case is to + * have one connection per bus. + * + * The two main bus types are: + * - System bus: a bus connecting applications on one system across user + * or session boundaries, for example allowing to communicate + * with system services like printer spoolers, etc + * + * - Session bus: a bus connecting applications within one user session, for + * example started at login or by a session manager. Use cases + * or this kind of bus would be accessing user specific + * resources like addressbooks, retrieving user settings or + * controlling session services (e.g. disabling screensaver + * in a video player application during playback) + * + * While TQT_DBusConnection provides the basic API to access D-Bus services + * it is more convenient to use TQT_DBusProxy on top of the connection. + * + * See sections @ref dbusclient and @ref dbusservice for examples + */ +class TQDBUS_EXPORT TQT_DBusConnection +{ +public: + /** + * DBus bus types + */ + enum BusType + { + /** + * The session bus is a user and user session specific message + * channel. It will usually be started by a login script or a + * session manager. + */ + SessionBus, + + /** + * The system bus is a message channel bridging user level and + * system level process boundaries, e.g. it can allow a user process + * with normal user access restrictions to perform a limited subset + * of operations on a process running with elevated rights. + * + * @warning if an applications exposed services on the system bus, i.e. + * registers objects using registerObject(), it should be + * carefully examined on potential security issues + */ + SystemBus, + + // TODO tqfind out about ActivationBus purpose + ActivationBus + }; + + /** + * @brief Creates an empty/disconnected connection handle + * + * This is mainly used for initializing variables of this type, i.e. like + * the default TQString constructor. + * + * A variable set to such an empty connection can be assigned a working + * connection at any time. + */ + TQT_DBusConnection(); + + /** + * @brief Creates a connection handle to a named connection + * + * This will result in an disconnected connection handle if no + * connection with that name has been created by addConnection before. + * + * Therefore it is recommended to use addConnection() instead to get a + * connection handle. + * + * @param name identifier of the shared connection object + */ + TQT_DBusConnection(const TQString &name); + + /** + * @brief Creates a shallow copy of the given connection + * + * Allows to pass connection handles around by value, similar to TQString + * thus avoiding problems like dangling pointers in application code + * + * @param other the connection to copy from + */ + TQT_DBusConnection(const TQT_DBusConnection &other); + + /** + * @brief Destroys the connection handle + * + * If this handle is the last one referencing the shared connection object + * it will delete it, disconnecting it from any objects it was + * collaborating with + */ + ~TQT_DBusConnection(); + + /** + * @brief Creates a shallow copy of the given connection + * + * Allows to pass connection handles around by value, similar to TQString + * thus avoiding problems like dangling pointers in application code + * + * @param other the connection to copy from + * + * @return a reference to this instance as required by assigment operator + * semantics + */ + TQT_DBusConnection &operator=(const TQT_DBusConnection &other); + + /** + * @brief Returns whether the connection is connected to a bus + * + * @return @c true if the connection can be used, @c false if the handle + * does not have access to a shared connection object or if the + * connection to the bus could not be established or broke + */ + bool isConnected() const; + + /** + * @brief Returns the last error seen by the connection + * + * This can be a connection error, e.g. attempt to connect failed, or a + * transmission error or an error reported by a method call + * + * @return the last error seen by the connection + */ + TQT_DBusError lastError() const; + + /** + * @brief Flags for controlling the behavior name collision handling + * + * @see requestName() + */ + enum NameRequestMode + { + /** + * Do not allow others to take over a name requested by this + * application + */ + NoReplace = 0, + + /** + * Allow other applications that request the same name to get it, + * i.e. allow the bus to transfer the name from this application + * to the one requesting it + */ + AllowReplace = 1, + + /** + * Try to get the name transferred from the current owner to this + * application. This will only work if the other application as + * requested the name using the AllowReplace flag + */ + ReplaceExisting = 2 + }; + + /** + * @brief Requests to be addressable on the bus by a given name + * + * Each connection to a bus gets a unique name once the connection is + * established. This is similar to getting an IP address when connecting + * to the Internet. + * + * If an application's purpose is to provide services to other applications + * the other applications require to know how to address the service + * provider. Similar to a domain name on the Internet D-Bus allows to + * register names on the bus and be addressed through those names instead + * of the connection identifier. + * + * @note this is not required if the application only needs to acccess + * services or only implements generic service APIs + * + * If more than one application request the same name, D-Bus will try + * to resolve this conflict as good as possible. + * The #NameRequestMode flags allow to control how an application prefers + * to be treated in such a conflict. + * + * @param name the name the connection should be addressable with. See + * section @ref dbusconventions-servicename + * @param modeFlags an OR'ed combination of #NameRequestMode flags + * + * @return @c true if the name request was successfull, @c false if + * the connection is not connected to a bus or the name is already + * taken and cannot be tranferred + * + * @see uniqueName() + */ + bool requestName(const TQString &name, int modeFlags = NoReplace); + + /** + * @brief Returns the connection identifier assigned at connect + * + * The unique name is the connection address or identifier the bus assigned + * to this connection when it got established. + * + * @return the connection's unique bus identifier + * + * @see requestName() + */ + TQString uniqueName() const; + + /** + * @brief Sends a message over the bus + * + * Sends a message composed through the TQT_DBusMessage API to the bus. + * This is the main method for service objects (see TQT_DBusObjectBase) to + * send replies and errors for method calls they accepted or for sending + * D-Bus signals. + * + * @note for doing method calls it is more convenient to use TQT_DBusProxy, + * see TQT_DBusProxy::send() + * + * @param message the message to send + * + * @return @c true if sending succeeded, @c false if the connection is not + * connected, if the message lacks information about the recepient + * or if sending fails a at a lower level in the communication + * stack + * + * @see lastError() + */ + bool send(const TQT_DBusMessage &message) const; + + /** + * @brief Sends a message over the bus and waits for the reply + * + * Sends a message composed through the TQT_DBusMessage API to the bus. + * It then blocks and waits until the associated reply is received. + * Any message received in between is stored and can be processed + * by calling dispatch() or scheduleDispatch() + * + * @note for doing method calls it is more convenient to use TQT_DBusProxy, + * see TQT_DBusProxy::sendWithReply() + * + * @param message the message to send + * @param error an optional parameter to directly get any error that might + * occur during processing of the call + * + * @return a message containing either the call's reply or an invalid + * message in case the call failed + * + * @see lastError() + */ + TQT_DBusMessage sendWithReply(const TQT_DBusMessage &message, TQT_DBusError *error = 0) const; + + /** + * @brief Sends a message over the bus, specifying a receiver object for + * replies + * + * Sends a message composed through the TQT_DBusMessage API to the bus and + * returns an identifier number to associate with the reply once it is + * received by the given receiver. + * See TQT_DBusMessage::replySerialNumber() + * + * The required slot signature is + * @code + * void slotname(const TQT_DBusMessage&); + * @endcode + * + * @note for doing method calls it is more convenient to use TQT_DBusProxy, + * see TQT_DBusProxy::sendWithAsyncReply() + * + * @param message the message to send + * @param receiver the TQObject to relay the reply to + * @param slot the slot to invoke for the reply + * + * @return a numeric identifier for association with the reply or @c 0 if + * sending failed + * + * @see lastError() + */ + int sendWithAsyncReply(const TQT_DBusMessage &message, TQObject *receiver, + const char *slot) const; + + /** + * @brief Flushes buffered outgoing message + * + * Attempts to send all enqueued outgoing messages before returning. + */ + void flush() const; + + /** + * @brief Processes buffered inbound messages + * + * Attempts to process all enqueued inbound messages, e.g. replies to + * method calls or received signals. + * + * @warning dispatching message can result in TQt signals being emitted + * before this method returns. In case you just want to make sure + * no inbound message is forgotten, call scheduleDispatch() which + * will execute the dispatch delayed through the event loop. + */ + void dispatch() const; + + /** + * @brief Request a delayed check for inbound buffer processing + * + * Similar to dispatch() but delayed by a single shot timer to ensure + * the method has returned before the processing is started. + * + * If a asynchronous method call is followed by a synchronous call without + * returning to the event loop in between, a call to scheduleDispatch() + * ensures that a pending reply to the asynchronous call is processed + * as soon as possible + */ + void scheduleDispatch() const; + + /** + * @brief Connects an object to receive D-Bus signals + * + * This provides a basic access to all D-Bus signals received on this + * connection. + * For every D-Bus signal processed by the connection object a TQt signal + * is emitted and thus delivered to all receiver objects connected + * through this method. + * + * The required slot signature is + * @code + * void slotname(const TQT_DBusMessage&); + * @endcode + * + * so a suitable receiver could look like this + * @code + * class DBusSignalReceiver : public TQObject + * { + * TQ_OBJECT + * public slots: + * void dbusSignal(const TQT_DBusMessage&); + * }; + * @endcode + * + * and would be connected like this + * @code + * // assuming the following variables + * TQT_DBusConnection connection; + * DBusSignalReceiver* receiver; + * + * connection.connect(receiver, TQT_SLOT(dbusSignal(const TQT_DBusMessage&))); + * @endcode + * + * See TQT_DBusProxy::dbusSignal() for a more obvious way of connecting slots. + * + * @param object the receiver object + * @param slot the receiver slot (or signal for signal->signal connections) + * + * @return @c true if the connection was successfull, otherwise @c false + * + * @see disconnect() + */ + bool connect(TQObject* object, const char* slot); + + /** + * @brief Disconnects a given receiver from the D-Bus signal handling + * + * @param object the receiver object to disconnect from + * @param slot the receiver slot (or signal for signal->signal connections) + * + * @return @c true if the disconnect was successfull, otherwise @c false + * + * @see connect() + */ + bool disconnect(TQObject* object, const char* slot); + + /** + * @brief Registers a service object for a given path + * + * In order to receive method calls over the D-Bus connection the service + * objects path within its host application has to be registered with the + * connection. See section @ref dbusconventions-objectpath for details. + * + * Only one objects can be registered for a single object path, i.e. + * the path -> object mapping is unambiguous, similar to mapping of + * filesystem paths to files. + * + * If a service object offers more than one interface it is up to the + * service implementation if all are implemented in the object path to this + * method or if the passed object is just another demultiplexer which + * relays the message to the interface implementor. + * + * @param path the object path to register the object for + * @param object the service implementation object for that path + * + * @return @c true if the given object is now registered for the given path + * or @c false if path is empty, object is null or another object + * is already registered for this path + * + * @see unregisterObject() + */ + bool registerObject(const TQString& path, TQT_DBusObjectBase* object); + + /** + * @brief Unregister a service object on a given path + * + * Removes any mapping of object path to service object previously + * registered by registerObject(). + * See section @ref dbusconventions-objectpath for details. + * + * @warning always(!) unregister a service object before deleting it + * + * @param path the object path of the object to unregister + * + * @see registerObject() + */ + void unregisterObject(const TQString &path); + + /** + * @brief Gets a connection to the session bus + * + * Convenience overload for creating the default shared connection to the + * D-Bus session bus. + * + * Equivalent to calling addConnection(SessionBus); + * + * @return a connection handle. Check isConnected() to tqfind out if the + * connection attempt has been successfull + * + * @see addConnection(BusType,const TQString&); + */ + static TQT_DBusConnection sessionBus(); + + /** + * @brief Gets a connection to the system bus + * + * Convenience overload for creating the default shared connection to the + * D-Bus system bus. + * + * Equivalent to calling addConnection(SystemBus); + * + * @return a connection handle. Check isConnected() to tqfind out if the + * connection attempt has been successfull + * + * @see addConnection(BusType,const TQString&); + */ + static TQT_DBusConnection systemBus(); + + /** + * @brief Add a connection to a bus with a specific bus type + * + * This is a factory method as it will create a connection for the given + * name if its not available yet, but return a previously created + * connection for that name if available. + * + * Depending on the #BusType the D-Bus library will connect to the address + * configured for that type, so this is the recommended way to create + * connection to D-Bus. + * + * @code + * // Associate the default connection name with a connection to the user's + * // session bus + * TQT_DBusConnection con = TQT_DBusConnection::addConnection(TQT_DBusConnection::SessionBus); + * + * // check if we are connected and which uniqueName we got + * if (con.isConnected()) + * { + * qDebug("Connected to session bus. We got uniqueName %s", + * con.uniqueName().local8Bit().data()); + * } + * @endcode + * For the common use cases see also sessionBus() and systemBus() + * + * @param type the #BusType of the bus to connect to + * @param name the name to use for TQT_DBusConnection's connection sharing + * + * @return a connection handle. Check isConnected() to tqfind out if the + * connection attempt has been successfull + * + * @see closeConnection() + */ + static TQT_DBusConnection addConnection(BusType type, + const TQString &name = default_connection_name); + + /** + * @brief Add a connection to a bus at a specific address + * + * This is a factory method as it will create a connection for the given + * name if its not available yet, but return a previously created + * connection for that name if available. + * + * @note this requires to know the address of a D-Bus daemon to connect to + * + * @param address the address of the D-Bus daemon. Usually a Unix domain + * socket address + * @param name the name to use for TQT_DBusConnection's connection sharing + * + * @return a connection handle. Check isConnected() to tqfind out if the + * connection attempt has been successfull + * + * @see closeConnection() + */ + static TQT_DBusConnection addConnection(const TQString &address, + const TQString &name = default_connection_name); + + // TODO check why this doesn't close the D-Bus connection + /** + * @brief Closes a connection with a given name + * + * Removes the name from the pool of shared connections, i.e. a call to + * addConnection() with the same name afterwards will create a new + * connection. + * + * @param name the connection name as used in addConnection() + */ + static void closeConnection(const TQString &name = default_connection_name); + + /** + * String used as the default parameter for connection names + */ + QT_STATIC_CONST char *default_connection_name; + +private: + TQT_DBusConnectionPrivate *d; +}; + +#endif |