File indexing completed on 2024-12-15 03:45:03

 /*
     SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>
 
     SPDX-License-Identifier: MIT
 */
 
 #ifndef KUSERFEEDBACK_ABSTRACTDATASOURCE_H
 #define KUSERFEEDBACK_ABSTRACTDATASOURCE_H
 
 #include "kuserfeedbackcore_export.h"
 #include "provider.h"
 
 #include <QCoreApplication>
 
 QT_BEGIN_NAMESPACE
 class QSettings;
 QT_END_NAMESPACE
 
 namespace KUserFeedback {
 
 class AbstractDataSourcePrivate;
 
 /*! Base class for data sources for telemetry data. */
 class KUSERFEEDBACKCORE_EXPORT AbstractDataSource
 {
 public:
     virtual ~AbstractDataSource();
 
     /*! Returns the ID of this data source.
      *  This is used as identifier towards the server and should
      *  not be shown to the user.
      *  @see description()
      *  @returns The data source identifier configured on the feedback server.
      */
     QString id() const;
 
     /*! Returns a short name of this data source.
      *  Can be empty if short name is meaningless for this data source.
      *  @returns A translated, human-readable string.
      */
     virtual QString name() const;
 
     /*! Returns a human-readable, translated description of what
      *  this source provides.
      *  @see id()
      *  @returns A translated, human-readable string.
      */
     virtual QString description() const = 0;
 
     /*!
      * Returns the data gathered by this source.
      *
      * Implement this to return the data provided by this source.
      * One of the three following formats are expected:
      *  - scalar entries: QAssociativeIterable
      *  - list entries: QSequentialIterable containing QAssociativeIterable
      *  - map entries: QAssociativeIterable containing QAssociativeIterable
      *
      * The innermost QAssociativeIterable must only contain one of the following
      * base types (which has to match the corresponding schema entry element):
      *  - QString
      *  - int
      *  - double
      *  - bool
      *
      * All keys must be strings.
      *
      * @returns A variant complying with the above requirements.
      */
     virtual QVariant data() = 0;
 
     /*! Load persistent state for this data source.
      *  @param settings A QSettings object opened in a dedicated group for loading
      *  persistent data.
      */
     void load(QSettings *settings);
 
     /*! Store persistent state for this data source.
      *  @param settings A QSettings object opened in a dedicated group for storing
      *  persistent data.
      */
     void store(QSettings *settings);
 
     /*! Reset the persistent state of this data source.
      *  This is called after a successful submission of data, and can be used
      *  by sources that track differential rather than absolute data to reset
      *  their counters.
      *  @param settings A QSettings object opened in the dedicated group of this
      *  data source.
      */
     void reset(QSettings *settings);
 
     /*! Returns which telemetry colleciton mode this data source belongs to.
      *  @return The telemetry collection category this source belongs to.
      */
     Provider::TelemetryMode telemetryMode() const;
 
     /*! Sets which telemetry colleciton mode this data source belongs to.
      * @param mode The data collection mode of this source.
      * Provider::NoTelemetry is not allowed here.
      */
     void setTelemetryMode(Provider::TelemetryMode mode);
 
     /*! Checks whether this data source is active or not
      *  If the data source is not active, then collected
      *  data neither will be sent to a server nor appeared
      *  in the audit log.
      *  Data source is active by default.
      *  @return true if active, false otherwise
      */
     bool isActive() const;
 
     /*! Changes active state of the data source
      *  @param active The new active state for this data source
      */
     void setActive(bool active);
 
 protected:
     /*! Create a new data source named @p name.
      *  The name of the data source must match the corresponding
      *  product schema entry.
      *  @param id Must not be empty.
      *  @param mode The default telemetry mode.
      */
     explicit AbstractDataSource(const QString &id,
                                 Provider::TelemetryMode mode = Provider::DetailedUsageStatistics);
 
     ///@cond internal
     explicit AbstractDataSource(const QString &id,
                                 Provider::TelemetryMode mode,
                                 AbstractDataSourcePrivate *dd);
     ///@endcond
 
     /*! Set the ID of this data source.
      *  The ID should not change at runtime, this is only provided
      *  for enabling QML API for generic sources.
      *  @see id()
      */
     void setId(const QString &id);
 
     /*! Invoked by @p load() in order to load individual settings of this data source.
      *  @see load() description for further details.
      *  @param settings A QSettings object opened in a dedicated group for loading
      *  persistent data.
      */
     virtual void loadImpl(QSettings *settings);
 
     /*! Invoked by @p store() in order to store individual settings of this data source.
      *  @see store() description for further details.
      *  @param settings A QSettings object opened in a dedicated group for loading
      *  persistent data.
      */
     virtual void storeImpl(QSettings *settings);
 
     /*! Invoked by @p reset() in order to reset individual settings of this data source.
      *  @see reset() description for further details.
      *  @param settings A QSettings object opened in a dedicated group for loading
      *  persistent data.
      */
     virtual void resetImpl(QSettings *settings);
 
     ///@cond internal
     class AbstractDataSourcePrivate* const d_ptr;
     ///@endcond
 
 private:
     Q_DECLARE_PRIVATE(AbstractDataSource)
     Q_DISABLE_COPY(AbstractDataSource)
 };
 }
 
 #endif // KUSERFEEDBACK_ABSTRACTDATASOURCE_H