provider.h 7.89 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*
    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/>.
*/

#ifndef USERFEEDBACK_PROVIDER_H
#define USERFEEDBACK_PROVIDER_H

#include "userfeedbackcore_export.h"

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

namespace UserFeedback {

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.
 */
42 43 44
class USERFEEDBACKCORE_EXPORT Provider : public QObject
{
    Q_OBJECT
45 46 47 48
    /*! The interval in which the user accepts surveys.
     *  @c -1 indicates surveys are disabled.
     *  @see surveyInterval(), setSurveyInterval()
     */
49
    Q_PROPERTY(int surveyInterval READ surveyInterval WRITE setSurveyInterval NOTIFY surveyIntervalChanged)
50 51 52
    /*! The telemetry mode the user has configured.
     * @see statisticsCollectionMode(), setStatisticsCollectionMode()
     */
53
    Q_PROPERTY(StatisticsCollectionMode statisticsCollectionMode READ statisticsCollectionMode WRITE setStatisticsCollectionMode NOTIFY statisticsCollectionModeChanged)
54
public:
55 56 57 58
    /*! Telemetry collection modes.
     *  Colleciton modes are inclusive, ie. higher modes always imply data from
     *  lower modes too.
     */
59
    enum StatisticsCollectionMode {
60
        NoStatistics, ///< Transmit no data at all.
61 62 63 64
        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.
65
    };
Volker Krause's avatar
Volker Krause committed
66
    Q_ENUMS(StatisticsCollectionMode)
67

68 69 70
    /*! Create a new feedback provider.
     *  @param parent The parent object.
     */
71
    explicit Provider(QObject *parent = nullptr);
72
    ~Provider();
73

74
    /*! Set the product identifier.
75
     *  This is used to distinguish independent products on the same server.
76 77
     *  If this is not specified, the product identifier is dervied from the application name
     *  organisation domain specified in QCoreApplication.
78
     *  @param productId Unique product identifier, as configured on the feedback server.
79 80 81
     */
    void setProductIdentifier(const QString &productId);

82
    /*! Set the feedback server URL.
83
     *  This must be called with an appropriate URL for this class to be operational.
84 85
     *  @param url The URL of the feedback server.
     */
86 87
    void setFeedbackServer(const QUrl &url);

88 89 90 91
    /*! Set the automatic submission interval.
     *  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
92 93
    void setSubmissionInterval(int days);

94 95 96
    /*! Returns the current statistics collection mode.
     *  The default is NoStatistics.
     */
97 98
    StatisticsCollectionMode statisticsCollectionMode() const;

99
    /*! Set which statistics should be submitted. */
100 101
    void setStatisticsCollectionMode(StatisticsCollectionMode mode);

102
    /*! Adds a data source for statistical data collection.
Volker Krause's avatar
Volker Krause committed
103
     *  @param source The data source to add. The Provider takes ownership of @p source.
104 105 106 107 108 109
     *  @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);

110
    /*! Returns all data sources that have been added to this provider.
Volker Krause's avatar
Volker Krause committed
111 112 113 114
     *  @see addDataSource
     */
    QVector<AbstractDataSource*> dataSources() const;

115 116 117
    /*! Returns the minimum time between two surveys in days.
     *  The default is -1 (no surveys enabled).
     */
118 119
    int surveyInterval() const;

120
    /*! Sets the minimum time in days between two surveys.
121 122 123 124
     *  @c -1 indicates no surveys should be requested.
     */
    void setSurveyInterval(int days);

125
    /*! Marks the given survey as completed. This avoids getting further notification
126 127 128 129
     *  about the same survey.
     */
    void setSurveyCompleted(const SurveyInfo &info);

130 131 132 133 134
    /*! 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.
     */
135 136
    void setApplicationStartsUntilEncouragement(int starts);

137
    /*! Set the amount of usage time until the encouragement message should be shown.
138
     *  The default is -1, ie. no encouragement based on application usage time.
139 140 141
     *  @param secs Amount of seconds until the encouragement should be shown.
     */
    void setApplicationUsageTimeUntilEncouragement(int secs);
142

143 144 145 146 147 148 149 150 151 152
    /*! 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
     */
153 154
    void setEncouragementDelay(int secs);

155
    /*! Sets the interval after the encouragement should be repeated.
156
     *  Encouragement messages are only repeated if no feedback options have been enabled.
157
     *  The default is -1, that is no repeated encouragement at all.
158 159 160 161
     *  @param days Days between encouragement messages, 0 disables repeated encouragements.
     */
    void setEncouragementInterval(int days);

162
public Q_SLOTS:
163
    /*! Manually submit currently recorded data. */
164 165
    void submit();

166
Q_SIGNALS:
167
    /*! Emitted whenever there is a new survey available that can be presented
168 169
     *  to the user.
     */
170
    void surveyAvailable(const UserFeedback::SurveyInfo &survey);
171

172
    /*! Indicate that the encouragement notice should be shown. */
173 174
    void showEncouragementMessage();

175
    /*! Emitted when the survey interval changed. */
176 177
    void surveyIntervalChanged();

178
    /*! Emitted when the statistics collection mode has changed. */
179 180
    void statisticsCollectionModeChanged();

181 182 183
private:
    friend class ProviderPrivate;
    ProviderPrivate * const d;
184 185
    Q_PRIVATE_SLOT(d, void aboutToQuit())
    Q_PRIVATE_SLOT(d, void submitFinished())
186
    Q_PRIVATE_SLOT(d, void emitShowEncouragementMessage())
Volker Krause's avatar
Volker Krause committed
187
    // for UI
188
    Q_PRIVATE_SLOT(d, QByteArray jsonData(UserFeedback::Provider::StatisticsCollectionMode))
189 190 191
    // for testing
    Q_PRIVATE_SLOT(d, void load())
    Q_PRIVATE_SLOT(d, void store())
192 193 194 195
};

}

196 197
Q_DECLARE_METATYPE(UserFeedback::Provider::StatisticsCollectionMode)

198
#endif // USERFEEDBACK_PROVIDER_H