provider.h 10.8 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 38 39 40 41
/*! 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.
 *  The settings about what data to submit (statisticsCollectionMode) and how often
 *  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
    /*! The interval in which the user accepts surveys.
46
     *  This should be configurable for the user.
47 48 49
     *  @c -1 indicates surveys are disabled.
     *  @see surveyInterval(), setSurveyInterval()
     */
50
    Q_PROPERTY(int surveyInterval READ surveyInterval WRITE setSurveyInterval NOTIFY surveyIntervalChanged)
51

52
    /*! The telemetry mode the user has configured.
53
     * This should be configurable for the user.
54 55
     * @see statisticsCollectionMode(), setStatisticsCollectionMode()
     */
56
    Q_PROPERTY(StatisticsCollectionMode statisticsCollectionMode READ statisticsCollectionMode WRITE setStatisticsCollectionMode NOTIFY statisticsCollectionModeChanged)
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98

    /*! 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)

    /*! Application starts before an encouragement message is shown.
     *  @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)

99
public:
100 101 102 103
    /*! Telemetry collection modes.
     *  Colleciton modes are inclusive, ie. higher modes always imply data from
     *  lower modes too.
     */
104
    enum StatisticsCollectionMode {
105
        NoStatistics, ///< Transmit no data at all.
106 107 108 109
        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.
110
    };
111
#ifndef QT4_MOC_WORKAROUND
112 113
#if QT_VERSION >= QT_VERSION_CHECK(5, 5, 0)
    Q_ENUM(StatisticsCollectionMode)
114 115 116
#else
    Q_ENUMS(StatisticsCollectionMode)
#endif
117
#else
Volker Krause's avatar
Volker Krause committed
118
    Q_ENUMS(StatisticsCollectionMode)
119
#endif
120

121 122 123
    /*! Create a new feedback provider.
     *  @param parent The parent object.
     */
124
    explicit Provider(QObject *parent = nullptr);
125
    ~Provider();
126

127 128
    /*! Returns the current product identifier. */
    QString productIdentifier() const;
129
    /*! Set the product identifier.
130
     *  This is used to distinguish independent products on the same server.
131 132
     *  If this is not specified, the product identifier is dervied from the application name
     *  organisation domain specified in QCoreApplication.
133
     *  @param productId Unique product identifier, as configured on the feedback server.
134 135 136
     */
    void setProductIdentifier(const QString &productId);

137 138
    /*! Returns the current feedback server URL. */
    QUrl feedbackServer() const;
139
    /*! Set the feedback server URL.
140
     *  This must be called with an appropriate URL for this class to be operational.
141 142
     *  @param url The URL of the feedback server.
     */
143 144
    void setFeedbackServer(const QUrl &url);

145 146 147 148 149
    /*! 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.
150 151 152
     *  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
153 154
    void setSubmissionInterval(int days);

155 156 157
    /*! Returns the current statistics collection mode.
     *  The default is NoStatistics.
     */
158 159
    StatisticsCollectionMode statisticsCollectionMode() const;

160
    /*! Set which statistics should be submitted. */
161 162
    void setStatisticsCollectionMode(StatisticsCollectionMode mode);

163
    /*! Adds a data source for statistical data collection.
Volker Krause's avatar
Volker Krause committed
164
     *  @param source The data source to add. The Provider takes ownership of @p source.
165 166 167 168 169 170
     *  @param mode The statistics collection mode this source belongs to. Data is only
     *  send to the server for this source is a sufficiently high collection mode is configured
     *  by the user. @c NoStatistics is not allowed.
     */
    void addDataSource(AbstractDataSource *source, StatisticsCollectionMode mode);

171
    /*! Returns all data sources that have been added to this provider.
Volker Krause's avatar
Volker Krause committed
172 173 174 175
     *  @see addDataSource
     */
    QVector<AbstractDataSource*> dataSources() const;

176 177 178
    /*! Returns the minimum time between two surveys in days.
     *  The default is -1 (no surveys enabled).
     */
179 180
    int surveyInterval() const;

181
    /*! Sets the minimum time in days between two surveys.
182 183 184 185
     *  @c -1 indicates no surveys should be requested.
     */
    void setSurveyInterval(int days);

186 187
    /*! Returns the amount of application starts before an encouragement message is shown. */
    int applicationStartsUntilEncouragement() const;
188 189 190 191 192
    /*! 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.
     */
193 194
    void setApplicationStartsUntilEncouragement(int starts);

195 196
    /*! Returns the amount of application usage time before an encouragement message is shown. */
    int applicationUsageTimeUntilEncouragement() const;
197
    /*! Set the amount of usage time until the encouragement message should be shown.
198
     *  The default is -1, ie. no encouragement based on application usage time.
199 200 201
     *  @param secs Amount of seconds until the encouragement should be shown.
     */
    void setApplicationUsageTimeUntilEncouragement(int secs);
202

203 204
    /*! Returns the current encouragement delay in seconds. */
    int encouragementDelay() const;
205 206 207 208 209 210 211 212 213 214
    /*! 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
     */
215 216
    void setEncouragementDelay(int secs);

217 218
    /*! Returns the current encouragement interval. */
    int encouragementInterval() const;
219
    /*! Sets the interval after the encouragement should be repeated.
220
     *  Encouragement messages are only repeated if no feedback options have been enabled.
221
     *  The default is -1, that is no repeated encouragement at all.
222 223 224 225
     *  @param days Days between encouragement messages, 0 disables repeated encouragements.
     */
    void setEncouragementInterval(int days);

226
public Q_SLOTS:
227
    /*! Manually submit currently recorded data. */
228 229
    void submit();

230 231 232
    /*! Marks the given survey as completed. This avoids getting further notification
     *  about the same survey.
     */
233
    void surveyCompleted(const KUserFeedback::SurveyInfo &info);
234

235
Q_SIGNALS:
236
    /*! Emitted whenever there is a new survey available that can be presented
237 238
     *  to the user.
     */
239
    void surveyAvailable(const KUserFeedback::SurveyInfo &survey);
240

241
    /*! Indicate that the encouragement notice should be shown. */
242 243
    void showEncouragementMessage();

244
    /*! Emitted when the survey interval changed. */
245 246
    void surveyIntervalChanged();

247
    /*! Emitted when the statistics collection mode has changed. */
248 249
    void statisticsCollectionModeChanged();

250 251 252
    /*! Emitted when any provider setting changed. */
    void providerSettingsChanged();

253 254 255
private:
    friend class ProviderPrivate;
    ProviderPrivate * const d;
256 257
    Q_PRIVATE_SLOT(d, void aboutToQuit())
    Q_PRIVATE_SLOT(d, void submitFinished())
258
    Q_PRIVATE_SLOT(d, void emitShowEncouragementMessage())
Volker Krause's avatar
Volker Krause committed
259
    // for UI
260
    Q_PRIVATE_SLOT(d, QByteArray jsonData(KUserFeedback::Provider::StatisticsCollectionMode))
261 262 263
    // for testing
    Q_PRIVATE_SLOT(d, void load())
    Q_PRIVATE_SLOT(d, void store())
264 265 266 267
};

}

268
Q_DECLARE_METATYPE(KUserFeedback::Provider::StatisticsCollectionMode)
269

270
#endif // KUSERFEEDBACK_PROVIDER_H