1 | /* |
2 | * Copyright 2008 Aaron Seigo <aseigo@kde.org> |
3 | * |
4 | * This program is free software; you can redistribute it and/or modify |
5 | * it under the terms of the GNU Library General Public License as |
6 | * published by the Free Software Foundation; either version 2, or |
7 | * (at your option) any later version. |
8 | * |
9 | * This program is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
12 | * GNU General Public License for more details |
13 | * |
14 | * You should have received a copy of the GNU Library General Public |
15 | * License along with this program; if not, write to the |
16 | * Free Software Foundation, Inc., |
17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef PLASMA_SERVICEJOB_H |
21 | #define PLASMA_SERVICEJOB_H |
22 | |
23 | #include <QtCore/QVariant> |
24 | |
25 | #include <kjob.h> |
26 | #include <kservice.h> |
27 | |
28 | #include <plasma/plasma_export.h> |
29 | #include "credentials.h" |
30 | |
31 | namespace Plasma |
32 | { |
33 | |
34 | class ServiceJobPrivate; |
35 | |
36 | /** |
37 | * @class ServiceJob plasma/servicejob.h <Plasma/ServiceJob> |
38 | * |
39 | * @short This class provides jobs for use with Plasma::Service |
40 | * |
41 | * Unlike KJob, you can do the work in start(), since Plasma::Service already |
42 | * delays the call to start() until the event loop is reached. |
43 | * |
44 | * If the job is quick enough that it is not worth reporting the progress, |
45 | * you just need to implement start() to do the task, then call emitResult() |
46 | * at the end of it. If the task does not complete successfully, you should |
47 | * set a non-zero error code with setError(int) and an error message with |
48 | * setErrorText(QString). |
49 | * |
50 | * If the job is longer (involving network access, for instance), you should |
51 | * report the progress at regular intervals. See the KJob documentation for |
52 | * information on how to do this. |
53 | */ |
54 | class PLASMA_EXPORT ServiceJob : public KJob |
55 | { |
56 | Q_OBJECT |
57 | Q_PROPERTY(QString destination READ destination) |
58 | Q_PROPERTY(QString operationName READ operationName) |
59 | Q_PROPERTY(QVariant result READ result) |
60 | |
61 | |
62 | public: |
63 | /** |
64 | * Default constructor |
65 | * |
66 | * @param destination the subject that the job is acting on |
67 | * @param operation the action that the job is performing on the @p destination |
68 | * @param parameters the parameters of the @p action |
69 | * @param parent the parent object for this service |
70 | */ |
71 | ServiceJob(const QString &destination, const QString &operation, |
72 | const QMap<QString, QVariant> ¶meters, QObject *parent = 0); |
73 | |
74 | /** |
75 | * Destructor |
76 | */ |
77 | ~ServiceJob(); |
78 | |
79 | /** |
80 | * @return the subject that the job is acting on |
81 | */ |
82 | QString destination() const; |
83 | |
84 | /** |
85 | * @return the operation the job is performing on the destination |
86 | */ |
87 | QString operationName() const; |
88 | |
89 | /** |
90 | * @return the parameters for the operation |
91 | */ |
92 | QMap<QString, QVariant> parameters() const; |
93 | |
94 | /** |
95 | * @return the identity of the caller of this operation |
96 | */ |
97 | Credentials identity() const; |
98 | |
99 | /** |
100 | * Returns the result of the operation |
101 | * |
102 | * The result will be invalid if the job has not completed yet, or |
103 | * if the job does not have a meaningful result. |
104 | * |
105 | * Note that this should not be used to find out whether the operation |
106 | * was successful. Instead, you should check the value of error(). |
107 | * |
108 | * @return the result of the operation |
109 | */ |
110 | QVariant result() const; |
111 | |
112 | /** |
113 | * Default implementation of start, which simply sets the results to false. |
114 | * This makes it easy to create a "failure" job. |
115 | */ |
116 | Q_INVOKABLE virtual void start(); |
117 | |
118 | protected: |
119 | /** |
120 | * Sets the result for an operation. |
121 | */ |
122 | void setResult(const QVariant &result); |
123 | |
124 | private: |
125 | Q_PRIVATE_SLOT(d, void autoStart()) |
126 | Q_PRIVATE_SLOT(d, void preventAutoStart()) |
127 | |
128 | ServiceJobPrivate * const d; |
129 | |
130 | friend class ServiceProvider; |
131 | friend class RemoteServiceJob; |
132 | }; |
133 | |
134 | } // namespace Plasma |
135 | |
136 | Q_DECLARE_METATYPE(Plasma::ServiceJob *) |
137 | |
138 | #endif // multiple inclusion guard |
139 | |
140 | |