provider.h 11.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
/*
    Copyright (C) 2016 Volker Krause <vkrause@kde.org>

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public License as published by
    the Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
    License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

18 19
#ifndef KUSERFEEDBACK_PROVIDER_H
#define KUSERFEEDBACK_PROVIDER_H
20

Volker Krause's avatar
Volker Krause committed
21
#include "kuserfeedbackcore_export.h"
22

Volker Krause's avatar
Volker Krause committed
23
#include <QMetaType>
24 25 26
#include <QObject>
#include <QUrl>

27
namespace KUserFeedback {
28

29
class AbstractDataSource;
30
class ProviderPrivate;
31
class SurveyInfo;
32

33 34 35 36 37
/*! The central object managing data sources and transmitting feedback to the server.
 *
 *  The defaults for this class are very defensive, so in order to make it actually
 *  operational and submit data, there is a number of settings you need to set in
 *  code, namely submission intervals, encouragement settings and adding data sources.
38
 *  The settings about what data to submit (telemetryMode) and how often
39 40 41
 *  to bother the user with surveys (surveyInterval) should not be set to hardcoded
 *  values in code, but left as choices to the user.
 */
Volker Krause's avatar
Volker Krause committed
42
class KUSERFEEDBACKCORE_EXPORT Provider : public QObject
43 44
{
    Q_OBJECT
45 46 47 48 49
    /*! The global enabled state of the feedback functionality.
     *  If this is @c false, all feedback functionality has to be disabled completely.
     */
    Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged)

50
    /*! The interval in which the user accepts surveys.
51
     *  This should be configurable for the user.
52 53 54
     *  @c -1 indicates surveys are disabled.
     *  @see surveyInterval(), setSurveyInterval()
     */
55
    Q_PROPERTY(int surveyInterval READ surveyInterval WRITE setSurveyInterval NOTIFY surveyIntervalChanged)
56

57
    /*! The telemetry mode the user has configured.
58
     * This should be configurable for the user.
59
     * @see telemetryMode(), setTelemetryMode()
60
     */
61
    Q_PROPERTY(TelemetryMode telemetryMode READ telemetryMode WRITE setTelemetryMode NOTIFY telemetryModeChanged)
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77

    /*! Unique product id as set on the feedback server.
     *  @see setProductIdentifier
     */
    Q_PROPERTY(QString productIdentifier READ productIdentifier WRITE setProductIdentifier NOTIFY providerSettingsChanged)

    /*! URL of the feedback server.
     *  @see setFeedbackServer
     */
    Q_PROPERTY(QUrl feedbackServer READ feedbackServer WRITE setFeedbackServer NOTIFY providerSettingsChanged)

    /*! Submission interval in days.
     *  @see setSubmissionInterval
     */
    Q_PROPERTY(int submissionInterval READ submissionInterval WRITE setSubmissionInterval NOTIFY providerSettingsChanged)

Aleix Pol's avatar
Aleix Pol committed
78
    /*! Times the application has to be started before an encouragement message is shown.
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
     *  @see setApplicationStartsUntilEncouragement
     */
    Q_PROPERTY(int applicationStartsUntilEncouragement
                READ applicationStartsUntilEncouragement
                WRITE setApplicationStartsUntilEncouragement
                NOTIFY providerSettingsChanged)

    /*! Application usage time in seconds before an encouragement message is shown.
     *  @see setApplicationUsageTimeUntilEncouragement
     */
    Q_PROPERTY(int applicationUsageTimeUntilEncouragement
                READ applicationUsageTimeUntilEncouragement
                WRITE setApplicationUsageTimeUntilEncouragement
                NOTIFY providerSettingsChanged)

    /*! Encouragement delay after application start in seconds.
     *  @see setEncouragementDelay
     */
    Q_PROPERTY(int encouragementDelay READ encouragementDelay WRITE setEncouragementDelay NOTIFY providerSettingsChanged)

    /*! Encouragement interval.
     *  @see setEncouragementInterval
     */
    Q_PROPERTY(int encouragementInterval READ encouragementInterval WRITE setEncouragementInterval NOTIFY providerSettingsChanged)

104
public:
105 106 107 108
    /*! Telemetry collection modes.
     *  Colleciton modes are inclusive, ie. higher modes always imply data from
     *  lower modes too.
     */
109 110
    enum TelemetryMode {
        NoTelemetry, ///< Transmit no data at all.
111 112 113 114
        BasicSystemInformation = 0x10, ///< Transmit basic information about the system.
        BasicUsageStatistics = 0x20, ///< Transmit basic usage statistics.
        DetailedSystemInformation = 0x30, ///< Transmit detailed system information.
        DetailedUsageStatistics = 0x40, ///< Transmit detailed usage statistics.
115
    };
116
#ifndef QT4_MOC_WORKAROUND
117
#if QT_VERSION >= QT_VERSION_CHECK(5, 5, 0)
118
    Q_ENUM(TelemetryMode)
119
#else
120
    Q_ENUMS(TelemetryMode)
121
#endif
122
#else
123
    Q_ENUMS(TelemetryMode)
124
#endif
125

126 127 128
    /*! Create a new feedback provider.
     *  @param parent The parent object.
     */
129
    explicit Provider(QObject *parent = nullptr);
130
    ~Provider();
131

132 133 134 135 136 137 138 139 140 141 142
    /*! Returns whether feedback functionality is enabled on this system.
     *  This should be checked everywhere showing feedback UI to the user
     *  to respect the global "kill switch" for this. Provider does check
     *  this internally for encouragements, surveys and telemetry submission.
     */
    bool isEnabled() const;
    /*! Set the global (user-wide) activation state for feedback functionality.
     *  @see isEnabled
     */
    void setEnabled(bool enabled);

143 144
    /*! Returns the current product identifier. */
    QString productIdentifier() const;
145
    /*! Set the product identifier.
146
     *  This is used to distinguish independent products on the same server.
147 148
     *  If this is not specified, the product identifier is dervied from the application name
     *  organisation domain specified in QCoreApplication.
149
     *  @param productId Unique product identifier, as configured on the feedback server.
150 151 152
     */
    void setProductIdentifier(const QString &productId);

153 154
    /*! Returns the current feedback server URL. */
    QUrl feedbackServer() const;
155
    /*! Set the feedback server URL.
156
     *  This must be called with an appropriate URL for this class to be operational.
157 158
     *  @param url The URL of the feedback server.
     */
159 160
    void setFeedbackServer(const QUrl &url);

161 162 163 164 165
    /*! Returns the current submission interval.
     *  @return Days between telemetry submissions, or -1 if submission is off.
     */
    int submissionInterval() const;
    /*! Set the automatic submission interval in days.
166 167 168
     *  This must be called with a positive number for this class to be operational,
     *  as the default is -1 (no submission ever).
     */
Volker Krause's avatar
Volker Krause committed
169 170
    void setSubmissionInterval(int days);

171 172
    /*! Returns the current telemetry collection mode.
     *  The default is NoTelemetry.
173
     */
174
    TelemetryMode telemetryMode() const;
175

176 177
    /*! Set which telemetry data should be submitted. */
    void setTelemetryMode(TelemetryMode mode);
178

179
    /*! Adds a data source for telemetry data collection.
Volker Krause's avatar
Volker Krause committed
180
     *  @param source The data source to add. The Provider takes ownership of @p source.
181
     */
182
    void addDataSource(AbstractDataSource *source);
183

184
    /*! Returns all data sources that have been added to this provider.
Volker Krause's avatar
Volker Krause committed
185 186 187 188
     *  @see addDataSource
     */
    QVector<AbstractDataSource*> dataSources() const;

189 190 191
    /*! Returns the minimum time between two surveys in days.
     *  The default is -1 (no surveys enabled).
     */
192 193
    int surveyInterval() const;

194
    /*! Sets the minimum time in days between two surveys.
195 196 197 198
     *  @c -1 indicates no surveys should be requested.
     */
    void setSurveyInterval(int days);

199 200
    /*! Returns the amount of application starts before an encouragement message is shown. */
    int applicationStartsUntilEncouragement() const;
201 202 203 204 205
    /*! Set the amount of application starts until the encouragement message should be shown.
     *  The default is -1, ie. no encouragement based on application starts.
     *  @param starts The amount of application starts after which an encouragement
     *  message should be displayed.
     */
206 207
    void setApplicationStartsUntilEncouragement(int starts);

208 209
    /*! Returns the amount of application usage time before an encouragement message is shown. */
    int applicationUsageTimeUntilEncouragement() const;
210
    /*! Set the amount of usage time until the encouragement message should be shown.
211
     *  The default is -1, ie. no encouragement based on application usage time.
212 213 214
     *  @param secs Amount of seconds until the encouragement should be shown.
     */
    void setApplicationUsageTimeUntilEncouragement(int secs);
215

216 217
    /*! Returns the current encouragement delay in seconds. */
    int encouragementDelay() const;
218 219 220 221 222 223 224 225 226 227
    /*! Set the delay after application start for the earliest display of the encouragement message.
     *  The default is 300, ie. 5 minutes after the application start.
     *  @note This only adds an additional contraint on usage time and startup count based
     *  encouragement messages, it does not actually trigger encouragement messages itself.
     *
     *  @param secs Amount of seconds after the application start for the earliest display
     *  of an encouragement message.
     *
     *  @see setApplicationStartsUntilEncouragement, setApplicationUsageTimeUntilEncouragement
     */
228 229
    void setEncouragementDelay(int secs);

230 231
    /*! Returns the current encouragement interval. */
    int encouragementInterval() const;
232
    /*! Sets the interval after the encouragement should be repeated.
233
     *  Encouragement messages are only repeated if no feedback options have been enabled.
234
     *  The default is -1, that is no repeated encouragement at all.
235 236 237 238
     *  @param days Days between encouragement messages, 0 disables repeated encouragements.
     */
    void setEncouragementInterval(int days);

239
public Q_SLOTS:
240
    /*! Manually submit currently recorded data. */
241 242
    void submit();

243 244 245
    /*! Marks the given survey as completed. This avoids getting further notification
     *  about the same survey.
     */
246
    void surveyCompleted(const KUserFeedback::SurveyInfo &info);
247

248
Q_SIGNALS:
249
    /*! Emitted whenever there is a new survey available that can be presented
250 251
     *  to the user.
     */
252
    void surveyAvailable(const KUserFeedback::SurveyInfo &survey);
253

254
    /*! Indicate that the encouragement notice should be shown. */
255 256
    void showEncouragementMessage();

257
    /*! Emitted when the survey interval changed. */
258 259
    void surveyIntervalChanged();

260 261
    /*! Emitted when the telemetry collection mode has changed. */
    void telemetryModeChanged();
262

263 264 265
    /*! Emitted when any provider setting changed. */
    void providerSettingsChanged();

266 267 268
    /*! Emitted when the global enabled state changed. */
    void enabledChanged();

269 270 271
private:
    friend class ProviderPrivate;
    ProviderPrivate * const d;
272 273
    Q_PRIVATE_SLOT(d, void aboutToQuit())
    Q_PRIVATE_SLOT(d, void submitFinished())
274
    Q_PRIVATE_SLOT(d, void submitProbeFinished())
275
    Q_PRIVATE_SLOT(d, void emitShowEncouragementMessage())
Volker Krause's avatar
Volker Krause committed
276
    // for UI
277
    Q_PRIVATE_SLOT(d, QByteArray jsonData(KUserFeedback::Provider::TelemetryMode))
278 279 280
    // for testing
    Q_PRIVATE_SLOT(d, void load())
    Q_PRIVATE_SLOT(d, void store())
Volker Krause's avatar
Volker Krause committed
281
    Q_PRIVATE_SLOT(d, bool selectSurvey(const KUserFeedback::SurveyInfo&))
282 283 284 285
};

}

286
Q_DECLARE_METATYPE(KUserFeedback::Provider::TelemetryMode)
287

288
#endif // KUSERFEEDBACK_PROVIDER_H