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
31namespace Plasma
32{
33
34class 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 */
54class 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
62public:
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> &parameters, 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
118protected:
119 /**
120 * Sets the result for an operation.
121 */
122 void setResult(const QVariant &result);
123
124private:
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
136Q_DECLARE_METATYPE(Plasma::ServiceJob *)
137
138#endif // multiple inclusion guard
139
140