Plasma

servicejob.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_SERVICEJOB_H
8 #define PLASMA_SERVICEJOB_H
9 
10 #include <QVariant>
11 
12 #include <KJob>
13 
14 #include <plasma/plasma_export.h>
15 
16 namespace Plasma
17 {
18 class ServiceJobPrivate;
19 
20 /**
21  * @class ServiceJob plasma/servicejob.h <Plasma/ServiceJob>
22  *
23  * @short This class provides jobs for use with Plasma::Service
24  *
25  * Unlike KJob, you can do the work in start(), since Plasma::Service already
26  * delays the call to start() until the event loop is reached.
27  *
28  * If the job is quick enough that it is not worth reporting the progress,
29  * you just need to implement start() to do the task, then call emitResult()
30  * at the end of it. If the task does not complete successfully, you should
31  * set a non-zero error code with setError(int) and an error message with
32  * setErrorText(QString).
33  *
34  * If the job is longer (involving network access, for instance), you should
35  * report the progress at regular intervals. See the KJob documentation for
36  * information on how to do this.
37  */
38 class PLASMA_EXPORT ServiceJob : public KJob
39 {
40  Q_OBJECT
41  Q_PROPERTY(QString destination READ destination)
42  Q_PROPERTY(QString operationName READ operationName)
43  Q_PROPERTY(QVariant result READ result)
44 
45 public:
46  /**
47  * Default constructor
48  *
49  * @param destination the subject that the job is acting on
50  * @param operation the action that the job is performing on the @p destination
51  * @param parameters the parameters of the @p action
52  * @param parent the parent object for this service
53  */
54  ServiceJob(const QString &destination, const QString &operation, const QVariantMap &parameters, QObject *parent = nullptr);
55 
56  /**
57  * Destructor
58  */
59  ~ServiceJob() override;
60 
61  /**
62  * @return the subject that the job is acting on
63  */
64  QString destination() const;
65 
66  /**
67  * @return the operation the job is performing on the destination
68  */
69  QString operationName() const;
70 
71  /**
72  * @return the parameters for the operation
73  */
74  QVariantMap parameters() const;
75 
76  /**
77  * Returns the result of the operation
78  *
79  * The result will be invalid if the job has not completed yet, or
80  * if the job does not have a meaningful result.
81  *
82  * Note that this should not be used to find out whether the operation
83  * was successful. Instead, you should check the value of error().
84  *
85  * @return the result of the operation
86  */
87  QVariant result() const;
88 
89  /**
90  * Default implementation of start, which simply sets the results to false.
91  * This makes it easy to create a "failure" job.
92  */
93  Q_INVOKABLE void start() override;
94 
95 protected:
96  /**
97  * Sets the result for an operation.
98  */
99  void setResult(const QVariant &result);
100 
101 private:
102  Q_PRIVATE_SLOT(d, void autoStart())
103  Q_PRIVATE_SLOT(d, void preventAutoStart())
104 
105  ServiceJobPrivate *const d;
106 };
107 
108 } // namespace Plasma
109 
110 #endif // multiple inclusion guard
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
Q_SCRIPTABLE Q_NOREPLY void start()
This class provides jobs for use with Plasma::Service.
Definition: servicejob.h:38
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:13:44 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.