DBus-1-TQt
1.0
|
#include <tqdbusconnection.h>
Public Types | |
enum | BusType { SessionBus , SystemBus , ActivationBus } |
enum | NameRequestMode { NoReplace = 0 , AllowReplace = 1 , ReplaceExisting = 2 } |
Public Member Functions | |
TQT_DBusConnection () | |
TQT_DBusConnection (const TQString &name) | |
TQT_DBusConnection (const TQT_DBusConnection &other) | |
~TQT_DBusConnection () | |
TQT_DBusConnection & | operator= (const TQT_DBusConnection &other) |
bool | isConnected () const |
TQT_DBusError | lastError () const |
bool | requestName (const TQString &name, int modeFlags=NoReplace) |
TQString | uniqueName () const |
bool | send (const TQT_DBusMessage &message) const |
TQT_DBusMessage | sendWithReply (const TQT_DBusMessage &message, TQT_DBusError *error=0) const |
int | sendWithAsyncReply (const TQT_DBusMessage &message, TQObject *receiver, const char *slot) const |
void | flush () const |
void | dispatch () const |
void | scheduleDispatch () const |
bool | connect (TQObject *object, const char *slot) |
bool | disconnect (TQObject *object, const char *slot) |
bool | registerObject (const TQString &path, TQT_DBusObjectBase *object) |
void | unregisterObject (const TQString &path) |
Static Public Member Functions | |
static TQT_DBusConnection | sessionBus () |
static TQT_DBusConnection | systemBus () |
static TQT_DBusConnection | addConnection (BusType type, const TQString &name=default_connection_name) |
static TQT_DBusConnection | addConnection (const TQString &address, const TQString &name=default_connection_name) |
static void | closeConnection (const TQString &name=default_connection_name) |
Public Attributes | |
QT_STATIC_CONST char * | default_connection_name = "qt_dbus_default_connection" |
Private Attributes | |
TQT_DBusConnectionPrivate * | d |
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:
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 Using D-Bus as a client and Providing services over D-Bus for examples
Definition at line 171 of file tqdbusconnection.h.
DBus bus types
Enumerator | |
---|---|
SessionBus | 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. |
SystemBus | 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.
|
ActivationBus |
Definition at line 177 of file tqdbusconnection.h.
Flags for controlling the behavior name collision handling.
Definition at line 282 of file tqdbusconnection.h.
TQT_DBusConnection::TQT_DBusConnection | ( | ) |
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.
Definition at line 144 of file tqdbusconnection.cpp.
TQT_DBusConnection::TQT_DBusConnection | ( | const TQString & | name | ) |
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.
name | identifier of the shared connection object |
Definition at line 148 of file tqdbusconnection.cpp.
References TQT_DBusConnectionManager::connection(), d, manager(), Atomic::ref(), and TQT_DBusConnectionPrivate::ref.
TQT_DBusConnection::TQT_DBusConnection | ( | const TQT_DBusConnection & | other | ) |
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
other | the connection to copy from |
Definition at line 155 of file tqdbusconnection.cpp.
References d, Atomic::ref(), and TQT_DBusConnectionPrivate::ref.
TQT_DBusConnection::~TQT_DBusConnection | ( | ) |
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
Definition at line 162 of file tqdbusconnection.cpp.
References d, Atomic::deref(), and TQT_DBusConnectionPrivate::ref.
|
static |
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.
For the common use cases see also sessionBus() and systemBus()
type | the BusType of the bus to connect to |
name | the name to use for TQT_DBusConnection's connection sharing |
Definition at line 193 of file tqdbusconnection.cpp.
References ActivationBus, TQT_DBusConnectionManager::connection(), d, TQT_DBusConnectionPrivate::error, manager(), SessionBus, TQT_DBusConnectionManager::setConnection(), TQT_DBusConnectionPrivate::setConnection(), SystemBus, and TQT_DBusConnection().
|
static |
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.
address | the address of the D-Bus daemon. Usually a Unix domain socket address |
name | the name to use for TQT_DBusConnection's connection sharing |
Definition at line 222 of file tqdbusconnection.cpp.
References TQT_DBusConnectionManager::connection(), d, TQT_DBusConnectionPrivate::error, manager(), TQT_DBusConnectionManager::setConnection(), TQT_DBusConnectionPrivate::setConnection(), and TQT_DBusConnection().
|
static |
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.
name | the connection name as used in addConnection() |
Definition at line 241 of file tqdbusconnection.cpp.
References manager(), and TQT_DBusConnectionManager::removeConnection().
bool TQT_DBusConnection::connect | ( | TQObject * | object, |
const char * | slot | ||
) |
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
so a suitable receiver could look like this
and would be connected like this
See TQT_DBusProxy::dbusSignal() for a more obvious way of connecting slots.
object | the receiver object |
slot | the receiver slot (or signal for signal->signal connections) |
true
if the connection was successfull, otherwise false
Definition at line 324 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, and d.
bool TQT_DBusConnection::disconnect | ( | TQObject * | object, |
const char * | slot | ||
) |
Disconnects a given receiver from the D-Bus signal handling.
object | the receiver object to disconnect from |
slot | the receiver slot (or signal for signal->signal connections) |
true
if the disconnect was successfull, otherwise false
Definition at line 334 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, and d.
void TQT_DBusConnection::dispatch | ( | ) | const |
Processes buffered inbound messages.
Attempts to process all enqueued inbound messages, e.g. replies to method calls or received signals.
Definition at line 310 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusConnectionPrivate::dispatch().
void TQT_DBusConnection::flush | ( | ) | const |
Flushes buffered outgoing message.
Attempts to send all enqueued outgoing messages before returning.
Definition at line 303 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusConnectionPrivate::flush().
bool TQT_DBusConnection::isConnected | ( | ) | const |
Returns whether the connection is connected to a bus.
true
if the connection can be used, 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 Definition at line 370 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, and d.
TQT_DBusError TQT_DBusConnection::lastError | ( | ) | const |
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
Definition at line 375 of file tqdbusconnection.cpp.
References d, and TQT_DBusConnectionPrivate::lastError.
TQT_DBusConnection & TQT_DBusConnection::operator= | ( | const TQT_DBusConnection & | other | ) |
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
other | the connection to copy from |
Definition at line 168 of file tqdbusconnection.cpp.
References d, Atomic::deref(), Atomic::ref(), and TQT_DBusConnectionPrivate::ref.
bool TQT_DBusConnection::registerObject | ( | const TQString & | path, |
TQT_DBusObjectBase * | object | ||
) |
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 Object paths 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.
path | the object path to register the object for |
object | the service implementation object for that path |
true
if the given object is now registered for the given path or false
if path is empty, object is null or another object is already registered for this pathDefinition at line 344 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusConnectionPrivate::registeredObjects.
bool TQT_DBusConnection::requestName | ( | const TQString & | name, |
int | modeFlags = NoReplace |
||
) |
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.
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.
name | the name the connection should be addressable with. See section Service names |
modeFlags | an OR'ed combination of NameRequestMode flags |
true
if the name request was successfull, false
if the connection is not connected to a bus or the name is already taken and cannot be tranferredDefinition at line 387 of file tqdbusconnection.cpp.
References AllowReplace, TQT_DBusConnectionPrivate::connection, d, TQT_DBusConnectionPrivate::error, TQT_DBusConnectionPrivate::handleError(), TQT_DBusConnectionPrivate::handleUnreadMessages(), and ReplaceExisting.
void TQT_DBusConnection::scheduleDispatch | ( | ) | const |
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
Definition at line 317 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusConnectionPrivate::scheduleDispatch().
bool TQT_DBusConnection::send | ( | const TQT_DBusMessage & | message | ) | const |
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.
message | the message to send |
true
if sending succeeded, 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 stackDefinition at line 252 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusMessage::toDBusMessage().
int TQT_DBusConnection::sendWithAsyncReply | ( | const TQT_DBusMessage & | message, |
TQObject * | receiver, | ||
const char * | slot | ||
) | const |
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
message | the message to send |
receiver | the TQObject to relay the reply to |
slot | the slot to invoke for the reply |
0
if sending failedDefinition at line 266 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusConnectionPrivate::sendWithReplyAsync().
TQT_DBusMessage TQT_DBusConnection::sendWithReply | ( | const TQT_DBusMessage & | message, |
TQT_DBusError * | error = 0 |
||
) | const |
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()
message | the message to send |
error | an optional parameter to directly get any error that might occur during processing of the call |
Definition at line 275 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, TQT_DBusMessage::d, TQT_DBusConnectionPrivate::error, TQT_DBusMessagePrivate::error, TQT_DBusMessage::fromDBusMessage(), TQT_DBusConnectionPrivate::handleError(), TQT_DBusConnectionPrivate::lastError, TQT_DBusError::setDBUSError(), and TQT_DBusMessage::toDBusMessage().
|
static |
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);
Definition at line 183 of file tqdbusconnection.cpp.
References addConnection(), and SessionBus.
|
static |
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);
Definition at line 188 of file tqdbusconnection.cpp.
References addConnection(), and SystemBus.
TQString TQT_DBusConnection::uniqueName | ( | ) | const |
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.
Definition at line 380 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, and d.
void TQT_DBusConnection::unregisterObject | ( | const TQString & | path | ) |
Unregister a service object on a given path.
Removes any mapping of object path to service object previously registered by registerObject(). See section Object paths for details.
path | the object path of the object to unregister |
Definition at line 358 of file tqdbusconnection.cpp.
References TQT_DBusConnectionPrivate::connection, d, and TQT_DBusConnectionPrivate::registeredObjects.
|
private |
Definition at line 660 of file tqdbusconnection.h.
QT_STATIC_CONST_IMPL char * TQT_DBusConnection::default_connection_name = "qt_dbus_default_connection" |
String used as the default parameter for connection names
Definition at line 657 of file tqdbusconnection.h.