This class provides a generic API for write access to settings or services. More...

#include <Plasma/Service>

Inheritance diagram for Plasma::Service:

Signals
void	finished (Plasma::ServiceJob *job)
void	operationsChanged ()
void	serviceReady (Plasma::Service *service)
Public Member Functions
	~Service ()
Q_INVOKABLE void	associateWidget (QWidget *widget, const QString &operation)
Q_INVOKABLE void	associateWidget (QGraphicsWidget *widget, const QString &operation)
Q_INVOKABLE QString	destination () const
Q_INVOKABLE void	disassociateWidget (QWidget *widget)
Q_INVOKABLE void	disassociateWidget (QGraphicsWidget *widget)
Q_INVOKABLE bool	isOperationEnabled (const QString &operation) const
Q_INVOKABLE QString	name () const
Q_INVOKABLE KConfigGroup	operationDescription (const QString &operationName)
Q_INVOKABLE QStringList	operationNames () const
Q_INVOKABLE QMap< QString, QVariant >	parametersFromDescription (const KConfigGroup &description)
Q_INVOKABLE void	setDestination (const QString &destination)
Q_INVOKABLE ServiceJob *	startOperationCall (const KConfigGroup &description, QObject *parent=0)
Static Public Member Functions
static Service *	access (const KUrl &url, QObject *parent=0)
static Service *	load (const QString &name, const QVariantList &args, QObject *parent=0)
static Service *	load (const QString &name, QObject *parent=0)
Protected Member Functions
	Service (QObject *parent=0)
	Service (QObject *parent, const QVariantList &args)
virtual ServiceJob *	createJob (const QString &operation, QMap< QString, QVariant > &parameters)=0
virtual void	registerOperationsScheme ()
void	setName (const QString &name)
void	setOperationEnabled (const QString &operation, bool enable)
void	setOperationsScheme (QIODevice *xml)
Properties
QString	destination
QString	name
QStringList	operationNames

Detailed Description

This class provides a generic API for write access to settings or services.

Plasma::Service allows interaction with a "destination", the definition of which depends on the Service itself. For a network settings Service this might be a profile name ("Home", "Office", "Road Warrior") while a web based Service this might be a username ("aseigo", "stranger65").

A Service provides one or more operations, each of which provides some sort of interaction with the destination. Operations are described using config XML which is used to create a KConfig object with one group per operation. The group names are used as the operation names, and the defined items in the group are the parameters available to be set when using that operation.

A service is started with a KConfigGroup (representing a ready to be serviced operation) and automatically deletes itself after completion and signaling success or failure. See KJob for more information on this part of the process.

Services may either be loaded "stand alone" from plugins, or from a DataEngine by passing in a source name to be used as the destination.

Sample use might look like:

 Plasma::DataEngine *twitter = dataEngine("twitter");
 Plasma::Service *service = twitter.serviceForSource("aseigo");
 KConfigGroup op = service->operationDescription("update");
 op.writeEntry("tweet", "Hacking on plasma!");
 Plasma::ServiceJob *job = service->startOperationCall(op);
 connect(job, SIGNAL(finished(KJob*)), this, SLOT(jobCompeted()));

Please remember, the service needs to be deleted when it will no longer be used. This can be done manually or by these (perhaps easier) alternatives:

If it is needed throughout the lifetime of the object:

 service->setParent(this);

If the service will not be used after just one operation call, use:

 connect(job, SIGNAL(finished(KJob*)), service, SLOT(deleteLater()));

Definition at line 91 of file service.h.

Constructor & Destructor Documentation

Plasma::Service::~Service ( )

Destructor.

Definition at line 62 of file service.cpp.

builddir build BUILD kdelibs plasma service cpp Plasma::Service::Service ( QObject * parent = 0 ) [explicit, protected]

Default constructor.

parent the parent object for this service

Definition at line 49 of file service.cpp.

Plasma::Service::Service	(	QObject *	parent,
		const QVariantList &	args
	)		`[protected]`

Constructor for plugin loading.

Definition at line 55 of file service.cpp.

Member Function Documentation

Service * Plasma::Service::access	(	const KUrl &	url,
		QObject *	parent = `0`
	)		`[static]`

Used to access a service from an url.

Always check for the signal serviceReady() that fires when this service is actually ready for use.

Definition at line 79 of file service.cpp.

void Plasma::Service::associateWidget	(	QWidget *	widget,
		const QString &	operation
	)

Assoicates a widget with an operation, which allows the service to automatically manage, for example, the enabled state of a widget.

This will remove any previous associations the widget had with operations on this engine.

Parameters:

widget	the QWidget to associate with the service
operation	the operation to associate the widget with

Definition at line 252 of file service.cpp.

void Plasma::Service::associateWidget	(	QGraphicsWidget *	widget,
		const QString &	operation
	)

Assoicates a widget with an operation, which allows the service to automatically manage, for example, the enabled state of a widget.

This will remove any previous associations the widget had with operations on this engine.

Parameters:

widget	the QGraphicsItem to associate with the service
operation	the operation to associate the widget with

Definition at line 268 of file service.cpp.

virtual ServiceJob* Plasma::Service::createJob	(	const QString &	operation,
		QMap< QString, QVariant > &	parameters
	)		`[protected, pure virtual]`

Called when a job should be created by the Service.

Parameters:

operation	which operation to work on
parameters	the parameters set by the user for the operation

Returns:: a ServiceJob that can be started and monitored by the consumer

Q_INVOKABLE QString Plasma::Service::destination ( ) const

Returns:: the target destination, if any, that this service is associated with

void Plasma::Service::disassociateWidget ( QWidget * widget )

Disassociates a widget if it has been associated with an operation on this service.

This will not change the enabled state of the widget.

Parameters:

widget the QWidget to disassociate.

Definition at line 261 of file service.cpp.

void Plasma::Service::disassociateWidget ( QGraphicsWidget * widget )

Disassociates a widget if it has been associated with an operation on this service.

This will not change the enabled state of the widget.

Parameters:

widget the QGraphicsWidget to disassociate.

Definition at line 278 of file service.cpp.

void Plasma::Service::finished ( Plasma::ServiceJob * job ) [signal]

Emitted when a job associated with this Service completes its task.

bool Plasma::Service::isOperationEnabled ( const QString & operation ) const

Query to find if an operation is enabled or not.

Parameters:

operation the name of the operation to check

Returns:: true if the operation is enabled, false otherwise

Definition at line 339 of file service.cpp.

Service * Plasma::Service::load	(	const QString &	name,
		QObject *	parent = `0`
	)		`[static]`

Used to load a given service from a plugin.

Parameters:

name	the plugin name of the service to load
parent	the parent object, if any, for the service

Returns:: a Service object, guaranteed to be not null.

Definition at line 68 of file service.cpp.

Service * Plasma::Service::load	(	const QString &	name,
		const QVariantList &	args,
		QObject *	parent = `0`
	)		`[static]`

Used to load a given service from a plugin.

Parameters:

name	the plugin name of the service to load
args	a list of arguments to supply to the service plugin when loading it
parent	the parent object, if any, for the service

Returns:: a Service object, guaranteed to be not null.

Since:: 4.5

Definition at line 74 of file service.cpp.

Q_INVOKABLE QString Plasma::Service::name ( ) const

The name of this service.

KConfigGroup Plasma::Service::operationDescription ( const QString & operationName )

Retrieves the parameters for a given operation.

Parameters:

operationName the operation to retrieve parameters for

Returns:: KConfigGroup containing the parameters

Definition at line 179 of file service.cpp.

Q_INVOKABLE QStringList Plasma::Service::operationNames ( ) const

Returns:: the possible operations for this profile

void Plasma::Service::operationsChanged ( ) [signal]

Emitted when the Service's operations change.

For example, a media player service may change what operations are available in response to the state of the player.

QMap< QString, QVariant > Plasma::Service::parametersFromDescription ( const KConfigGroup & description )

Returns:

a parameter map for the given description

description the configuration values to turn into the parameter map

Since:: 4.4

Definition at line 194 of file service.cpp.

void Plasma::Service::registerOperationsScheme ( ) [protected, virtual]

By default this is based on the file in plasma/services/name.operations, but can be reimplented to use a different mechanism.

It should result in a call to setOperationsScheme(QIODevice *);

Definition at line 374 of file service.cpp.

void Plasma::Service::serviceReady ( Plasma::Service * service ) [signal]

Emitted when this service is ready for use.

void Plasma::Service::setDestination ( const QString & destination )

Sets the destination for this Service to operate on.

destination specific to each Service, this sets which target or address for ServiceJobs to operate on

Definition at line 159 of file service.cpp.

void Plasma::Service::setName ( const QString & name ) [protected]

Sets the name of the Service; useful for Services not loaded from plugins, which use the plugin name for this.

name the name to use for this service

Definition at line 290 of file service.cpp.

void Plasma::Service::setOperationEnabled	(	const QString &	operation,
		bool	enable
	)		`[protected]`

Enables a given service by name.

Parameters:

operation	the name of the operation to enable or disable
enable	true if the operation should be enabld, false if disabled

Definition at line 306 of file service.cpp.

void Plasma::Service::setOperationsScheme ( QIODevice * xml ) [protected]

Sets the XML used to define the operation schema for this Service.

Definition at line 344 of file service.cpp.

ServiceJob * Plasma::Service::startOperationCall	(	const KConfigGroup &	description,
		QObject *	parent = `0`
	)

Called to create a ServiceJob which is associated with a given operation and parameter set.

Returns:: a started ServiceJob; the consumer may connect to relevant signals before returning to the event loop

Definition at line 213 of file service.cpp.

Property Documentation

QString Plasma::Service::destination [read, write]

Definition at line 95 of file service.h.

QString Plasma::Service::name [read]

Definition at line 97 of file service.h.

QStringList Plasma::Service::operationNames [read]

Definition at line 96 of file service.h.

The documentation for this class was generated from the following files:

Plasma

Plasma::Service Class Reference

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation

Plasma

kdelibs