Plasma

service.h
1 /*
2  SPDX-FileCopyrightText: 2008 Aaron Seigo <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef PLASMA_SERVICE_H
8 #define PLASMA_SERVICE_H
9 
10 #include <QHash>
11 #include <QObject>
12 #include <QVariant>
13 
14 #include <KConfigGroup>
15 
16 #include <plasma/plasma.h>
17 #include <plasma/plasma_export.h>
18 
19 class QIODevice;
20 class QWidget;
21 class QUrl;
22 class QQuickItem;
23 
24 namespace Plasma
25 {
26 class ServiceJob;
27 class ServicePrivate;
28 
29 /**
30  * @class Service plasma/service.h <Plasma/Service>
31  *
32  * @short This class provides a generic API for write access to settings or services.
33  *
34  * Plasma::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  * Plasma::DataEngine *twitter = dataEngine("twitter");
56  * Plasma::Service *service = twitter.serviceForSource("aseigo");
57  * QVariantMap op = service->operationDescription("update");
58  * op.insert("tweet", "Hacking on plasma!");
59  * Plasma::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  */
77 class PLASMA_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 
85 public:
86  /**
87  * Destructor
88  */
89  ~Service() override;
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 
139 Q_SIGNALS:
140  /**
141  * Emitted when this service is ready for use
142  */
143  void serviceReady(Plasma::Service *service);
144 
145  /**
146  * Emitted when an operation got enabled or disabled
147  */
148  void operationEnabledChanged(const QString &operation, bool enabled);
149 
150 protected:
151  /**
152  * Default constructor
153  *
154  * @param parent the parent object for this service
155  */
156  explicit Service(QObject *parent = nullptr);
157 
158  /**
159  * Constructor for plugin loading
160  */
161  Service(QObject *parent, const QVariantList &args);
162 
163  /**
164  * Called when a job should be created by the Service.
165  *
166  * @param operation which operation to work on
167  * @param parameters the parameters set by the user for the operation
168  * @return a ServiceJob that can be started and monitored by the consumer
169  */
170  virtual ServiceJob *createJob(const QString &operation, QVariantMap &parameters) = 0;
171 
172  /**
173  * By default this is based on the file in plasma/services/name.operations, but can be
174  * reimplemented to use a different mechanism.
175  *
176  * It should result in a call to setOperationsScheme(QIODevice *);
177  */
178  virtual void registerOperationsScheme();
179 
180  /**
181  * Sets the XML used to define the operation schema for
182  * this Service.
183  */
184  void setOperationsScheme(QIODevice *xml);
185 
186  /**
187  * Sets the name of the Service; useful for Services not loaded from plugins,
188  * which use the plugin name for this.
189  *
190  * @param name the name to use for this service
191  */
192  void setName(const QString &name);
193 
194  /**
195  * Enables a given service by name
196  *
197  * @param operation the name of the operation to enable or disable
198  * @param enable true if the operation should be enabled, false if disabled
199  */
200  void setOperationEnabled(const QString &operation, bool enable);
201 
202 private:
203  ServicePrivate *const d;
204 
205  friend class DataEnginePrivate;
206  friend class PluginLoader;
207 };
208 
209 } // namespace Plasma
210 
211 /**
212  * Register a service when it is contained in a loadable module
213  * @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
214  */
215 #define K_EXPORT_PLASMA_SERVICE(libname, classname) K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
216 
217 /// @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
218 #define K_EXPORT_PLASMA_SERVICE_WITH_JSON(libname, classname, jsonFile) K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin<classname>();)
219 
220 #endif // multiple inclusion guard
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
This class provides jobs for use with Plasma::Service.
Definition: servicejob.h:38
This class provides a generic API for write access to settings or services.
Definition: service.h:77
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:14:15 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.