A Service object is a proxy representing a service on D-Bus that implements the ContextKit interface. The lifespan of the Service object is not tied to the real service lifespan. This way a service can be accessed and controlled from different parts of the code. More...
#include <service.h>
Public Member Functions | |
Service (QDBusConnection connection, QObject *parent=0) | |
Creates a Service proxy object which shares the connection with the provider program. | |
Service (QDBusConnection::BusType busType, const QString &busName, QObject *parent=0) | |
A convenient constructor, where autoStart is always true. | |
Service (QDBusConnection::BusType busType, const QString &busName, bool autoStart, QObject *parent=0) | |
Creates a Service proxy object for busName on the bus indicated by busType. | |
virtual | ~Service () |
Destroys this Service instance. | |
bool | start () |
Start the Service again after it has been stopped. | |
void | stop () |
Stop the service. | |
void | restart () |
Stop and start the service. | |
void | setAsDefault () |
Sets the Service object as the default one to use when constructing Property objects. | |
void | setValue (const QString &key, const QVariant &val) |
Set the value of key to val. | |
void | setConnection (const QDBusConnection &connection) |
Set (override) the QDBusConnection used by the Service. | |
Friends | |
class | Property |
class | ::ServiceUnitTest |
A Service object is a proxy representing a service on D-Bus that implements the ContextKit interface. The lifespan of the Service object is not tied to the real service lifespan. This way a service can be accessed and controlled from different parts of the code.
When you first create a Service object with given bus type / bus name parameters the real D-Bus service instance is actually created and started. Future references to this bus type / bus name will give you a Service instance that points to the very same service as the first Service initialization that started it. In other words, we can say that the Service class represents a proxy interface to the real D-Bus service.
When the last instance of Service is destroyed, the real service is automatically stopped and it disappears from D-Bus (there is a simple ref counting mechanism involved to guarantee that).
Consider the following examples:
Service *s1 = new Service(QDBusConnection::SessionBus, "com.example.simple"); Service *s2 = new Service(QDBusConnection::SessionBus, "com.example.simple"); // s1 and s2 represent the same service s2->stop(); // Both s1 and s2 are now stopped s1->start(); // Both s1 and s2 are now started delete s1; // s2 is still valid, service is present delete s2; // the "com.example.simple" just disappeared from D-Bus
Every Property object is associated with a Service object. If you delete the Service object, the associated Property objects will turn invalid and you should not use them.
A Service can be running or stopped. When it is running, it is visible via D-Bus and clients can subscribe to its properties.
It is undefined what happens when you add a Property object to a running service. Likewise, it is undefined what happens when you add a Property to a Group while the Service of that Property object is running.
Thus, it is best to create a Service object, add all Property objects to it immediately, create the Group objects for them, and then enter the main loop.
Libcontextprovider can share the same QDBusConnection that is used in the provider program. In that case, the Service must be created by passing the QDBusConnection. The Service will not register any service name on the connection. It is advisable to register the service name as late as possible, after initializing all Services and Properties and after registering other objects the provider declares on D-Bus.
int main(int argc, char** argv) { QCoreApplication app(argc, argv); QDBusConnection systemBus = QDBusConnection::SystemBus(); // D-Bus registrations can happen before or after initializing // the Services and Properties connection.registerObject(...); // Now myService will share the connection and won't register // any service name Service *myService = new Service(systemBus); Property* myProperty = new Property(myService, "My.Property"); // Important: registering the service name should be done as // late as possible, to prevent clients from connecting to us // before all objects have been registered. connection.registerService("my.service.name"); return app.exec(); }
ContextProvider::Service::Service | ( | QDBusConnection | connection, | |
QObject * | parent = 0 | |||
) | [explicit] |
Creates a Service proxy object which shares the connection with the provider program.
The Service will not register any service name on the conneciton. If the service is accessed for the first time it'll be created and set up. If the service with the given parameters already exists the created object represents a controller to a previously-created service. A new Service will be started when it is constructed.
ContextProvider::Service::Service | ( | QDBusConnection::BusType | busType, | |
const QString & | busName, | |||
QObject * | parent = 0 | |||
) |
A convenient constructor, where autoStart is always true.
ContextProvider::Service::Service | ( | QDBusConnection::BusType | busType, | |
const QString & | busName, | |||
bool | autoStart, | |||
QObject * | parent = 0 | |||
) |
Creates a Service proxy object for busName on the bus indicated by busType.
The Service will register the given busName on D-Bus. If the service is accessed for the first time it'll be created and set up. If the service with the given parameters already exists the created object represents a controller to a previously-created service. A new Service will be started when it is constructed if autoStart is true (which is the default).
ContextProvider::Service::~Service | ( | ) | [virtual] |
Destroys this Service instance.
The actual service on D-Bus is stopped if this object is a last instance pointing at the actual service with the given constructor parameters (QDBusConnection or bus type and bus name).
void ContextProvider::Service::restart | ( | ) |
Stop and start the service.
This function cannot be used when the Service shares a QDBusConnection with the provider program. When that is the case, you must stop the service, unregister the D-Bus bus name, register it again (to force clients of context properties to resubscribe), and finally start the service again.
void ContextProvider::Service::setAsDefault | ( | ) |
void ContextProvider::Service::setConnection | ( | const QDBusConnection & | connection | ) |
Set (override) the QDBusConnection used by the Service.
Deprecated; use constructor with QDBusConnection parameter instead.
void ContextProvider::Service::setValue | ( | const QString & | key, | |
const QVariant & | val | |||
) |
Set the value of key to val.
A property named key must have been registered already, by creating a Property object for it.
bool ContextProvider::Service::start | ( | ) |
Start the Service again after it has been stopped.
In the case of shared connection, the objects will be registered to D-Bus. In the case of non-shared connection, also the service name will be registered on D-Bus. Returns true on success, false otherwise.
void ContextProvider::Service::stop | ( | ) |
Stop the service.
In the case of shared connection, this will cause the related objects to be unregistered, but the bus name will still be on D-Bus. In the case of non-shared connection, this will cause the service to disappear from D-Bus completely.
friend class ::ServiceUnitTest [friend] |
friend class Property [friend] |