Plasma5Support

service.h
1/*
2 SPDX-FileCopyrightText: 2008 Aaron Seigo <aseigo@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef PLASMA5SUPPORT_SERVICE_H
8#define PLASMA5SUPPORT_SERVICE_H
9
10#include <QHash>
11#include <QObject>
12#include <QVariant>
13
14#include <KConfigGroup>
15
16#include <plasma5support/plasma5support.h>
17#include <plasma5support/plasma5support_export.h>
18
19class QIODevice;
20class QWidget;
21class QUrl;
22class QQuickItem;
23
24namespace Plasma5Support
25{
26class ServiceJob;
27class ServicePrivate;
28
29/**
30 * @class Service plasma5support/service.h <Plasma5Support/Service>
31 *
32 * @short This class provides a generic API for write access to settings or services.
33 *
34 * Plasma5Support::Service allows interaction with a "destination", the definition of which
35 * depends on the Service itself. For a network settings Service this might be a
36 * profile name ("Home", "Office", "Road Warrior") while a web based Service this
37 * might be a username ("aseigo", "stranger65").
38 *
39 * A Service provides one or more operations, each of which provides some sort
40 * of interaction with the destination. Operations are described using config
41 * XML which is used to create a KConfig object with one group per operation.
42 * The group names are used as the operation names, and the defined items in
43 * the group are the parameters available to be set when using that operation.
44 *
45 * A service is started with a KConfigGroup (representing a ready to be serviced
46 * operation) and automatically deletes itself after completion and signaling
47 * success or failure. See KJob for more information on this part of the process.
48 *
49 * Services may either be loaded "stand alone" from plugins, or from a DataEngine
50 * by passing in a source name to be used as the destination.
51 *
52 * Sample use might look like:
53 *
54 * @code
55 * Plasma5Support::DataEngine *twitter = dataEngine("twitter");
56 * Plasma5Support::Service *service = twitter.serviceForSource("aseigo");
57 * QVariantMap op = service->operationDescription("update");
58 * op.insert("tweet", "Hacking on plasma!");
59 * Plasma5Support::ServiceJob *job = service->startOperationCall(op);
60 * connect(job, SIGNAL(finished(KJob*)), this, SLOT(jobCompeted()));
61 * @endcode
62 *
63 * Please remember, the service needs to be deleted when it will no longer be
64 * used. This can be done manually or by these (perhaps easier) alternatives:
65 *
66 * If it is needed throughout the lifetime of the object:
67 * @code
68 * service->setParent(this);
69 * @endcode
70 *
71 * If the service will not be used after just one operation call, use:
72 * @code
73 * connect(job, SIGNAL(finished(KJob*)), service, SLOT(deleteLater()));
74 * @endcode
75 *
76 */
77class PLASMA5SUPPORT_EXPORT Service : public QObject
78{
79 Q_OBJECT
80 Q_DECLARE_PRIVATE(Service)
81 Q_PROPERTY(QString destination READ destination WRITE setDestination)
82 Q_PROPERTY(QStringList operationNames READ operationNames)
83 Q_PROPERTY(QString name READ name)
84
85public:
86 /**
87 * Destructor
88 */
89 ~Service();
90
91 /**
92 * Sets the destination for this Service to operate on
93 *
94 * @param destination specific to each Service, this sets which
95 * target or address for ServiceJobs to operate on
96 */
97 Q_INVOKABLE void setDestination(const QString &destination);
98
99 /**
100 * @return the target destination, if any, that this service is associated with
101 */
102 Q_INVOKABLE QString destination() const;
103
104 /**
105 * @return the possible operations for this profile
106 */
107 Q_INVOKABLE QStringList operationNames() const;
108
109 /**
110 * Retrieves the parameters for a given operation
111 *
112 * @param operationName the operation to retrieve parameters for
113 * @return QVariantMap containing the parameters
114 */
115 Q_INVOKABLE QVariantMap operationDescription(const QString &operationName);
116
117 /**
118 * Called to create a ServiceJob which is associated with a given
119 * operation and parameter set.
120 *
121 * @return a started ServiceJob; the consumer may connect to relevant
122 * signals before returning to the event loop
123 */
124 Q_INVOKABLE ServiceJob *startOperationCall(const QVariantMap &description, QObject *parent = nullptr);
125
126 /**
127 * Query to find if an operation is enabled or not.
128 *
129 * @param operation the name of the operation to check
130 * @return true if the operation is enabled, false otherwise
131 */
132 Q_INVOKABLE bool isOperationEnabled(const QString &operation) const;
133
134 /**
135 * The name of this service
136 */
137 Q_INVOKABLE QString name() const;
138
139Q_SIGNALS:
140 /**
141 * Emitted when this service is ready for use
142 */
144
145 /**
146 * Emitted when an operation got enabled or disabled
147 */
148 void operationEnabledChanged(const QString &operation, bool enabled);
149
150protected:
151 /**
152 * @param parent the parent object for this service
153 */
154 explicit Service(QObject *parent = nullptr);
155
156 /**
157 * Called when a job should be created by the Service.
158 *
159 * @param operation which operation to work on
160 * @param parameters the parameters set by the user for the operation
161 * @return a ServiceJob that can be started and monitored by the consumer
162 */
163 virtual ServiceJob *createJob(const QString &operation, QVariantMap &parameters) = 0;
164
165 /**
166 * By default this is based on the file in plasma5support/services/name.operations, but can be
167 * reimplemented to use a different mechanism.
168 *
169 * It should result in a call to setOperationsScheme(QIODevice *);
170 */
171 virtual void registerOperationsScheme();
172
173 /**
174 * Sets the XML used to define the operation schema for
175 * this Service.
176 */
177 void setOperationsScheme(QIODevice *xml);
178
179 /**
180 * Sets the name of the Service; useful for Services not loaded from plugins,
181 * which use the plugin name for this.
182 *
183 * @param name the name to use for this service
184 */
185 void setName(const QString &name);
186
187 /**
188 * Enables a given service by name
189 *
190 * @param operation the name of the operation to enable or disable
191 * @param enable true if the operation should be enabled, false if disabled
192 */
193 void setOperationEnabled(const QString &operation, bool enable);
194
195private:
196 ServicePrivate *const d;
197
198 friend class DataEnginePrivate;
199 friend class PluginLoader;
200};
201
202} // namespace Plasma5Support
203
204#endif // multiple inclusion guard
This is an abstract base class which defines an interface to which Plasma's DataEngine and Service Lo...
This class provides jobs for use with Plasma5Support::Service.
Definition servicejob.h:39
This class provides a generic API for write access to settings or services.
Definition service.h:78
virtual ServiceJob * createJob(const QString &operation, QVariantMap &parameters)=0
Called when a job should be created by the Service.
void operationEnabledChanged(const QString &operation, bool enabled)
Emitted when an operation got enabled or disabled.
void serviceReady(Plasma5Support::Service *service)
Emitted when this service is ready for use.
Namespace for everything in libplasma.
Definition datamodel.cpp:15
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:59:38 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.