Issue 4657 - Add Acceptable Ads API

include/AdblockPlus/FilterEngine.h

 /*
  * This file is part of Adblock Plus <https://adblockplus.org/>,
- * Copyright (C) 2006-2016 Eyeo GmbH
+ * Copyright (C) 2006-2017 eyeo GmbH
  *
  * Adblock Plus is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as
  * published by the Free Software Foundation.
  *
  * Adblock Plus 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 General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
  * along with Adblock Plus.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef ADBLOCK_PLUS_FILTER_ENGINE_H
 #define ADBLOCK_PLUS_FILTER_ENGINE_H
 
 #include <functional>
 #include <map>
 #include <string>
 #include <vector>
 #include <AdblockPlus/JsEngine.h>
 #include <AdblockPlus/JsValue.h>
 #include <AdblockPlus/Notification.h>
 
 namespace AdblockPlus
 {
   class FilterEngine;
+  typedef std::shared_ptr<FilterEngine> FilterEnginePtr;
 
   /**
    * Wrapper for an Adblock Plus filter object.
    * There are no accessors for most
    * [filter properties](https://adblockplus.org/jsdoc/adblockpluscore/Filter.html),
    * use `GetProperty()` to retrieve them by name.
    */
   class Filter : public JsValue,
                  public std::enable_shared_from_this<Filter>
   {
   public:
     /**
      * Filter types, see https://adblockplus.org/en/filters.
      */
     enum Type {TYPE_BLOCKING, TYPE_EXCEPTION,
                TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION,
                TYPE_COMMENT, TYPE_INVALID};
 
     /**
      * Retrieves the type of this filter.
      * @return Type of this filter.
      */
-    Type GetType();
+    Type GetType() const;
 
     /**
      * Checks whether this filter has been added to the list of custom filters.
      * @return `true` if this filter has been added.
      */
-    bool IsListed();
+    bool IsListed() const;
 
     /**
      * Adds this filter to the list of custom filters.
      */
     void AddToList();
 
     /**
      * Removes this filter from the list of custom filters.
      */
     void RemoveFromList();
@@ skipping 16 matching lines @@
    * use `GetProperty()` to retrieve them by name.
    */
   class Subscription : public JsValue,
                        public std::enable_shared_from_this<Subscription>
   {
   public:
     /**
      * Checks if this subscription has been added to the list of subscriptions.
      * @return `true` if this subscription has been added.
      */
-    bool IsListed();
+    bool IsListed() const;
 
     /**
      * Adds this subscription to the list of subscriptions.
      */
     void AddToList();
 
     /**
      * Removes this subscription from the list of subscriptions.
      */
     void RemoveFromList();
 
     /**
      * Updates this subscription, i.e.\ retrieves the current filters from the
      * subscription URL.
      */
     void UpdateFilters();
 
     /**
      * Checks if the subscription is currently being updated.
      * @return `true` if the subscription is currently being updated.
      */
-    bool IsUpdating();
-
-    /**
-      * Indicates whether the subscription is acceptable ads subscription.
-      * @return `true` if this subscription is acceptable ads subscription.
-      */
-    bool IsAA();
+    bool IsUpdating() const;
+
+    /**
+     * Indicates whether the subscription is acceptable ads subscription.
+     * @return `true` if this subscription is acceptable ads subscription.
+     */
+    bool IsAA() const;
 

[Eric, 2016/12/05 14:40:57]

Typo: extra column of spaces

[sergei, 2017/03/17 15:55:25]

Done.

     bool operator==(const Subscription& subscription) const;
 
     /**
      * Creates a wrapper for an existing JavaScript subscription object.
      * Normally you shouldn't call this directly, but use
      * FilterEngine::GetSubscription() instead.
      * @param value JavaScript subscription object.
      */
     Subscription(JsValue&& value);
   };
@@ skipping 75 matching lines @@
      */
     typedef std::map<std::string, AdblockPlus::JsValuePtr> Prefs;
 
     /**
      * Callback type invoked when a new notification should be shown.
      * The parameter is the Notification object to be shown.
      */
     typedef std::function<void(const NotificationPtr&)> ShowNotificationCallback;
 
     /**
-     * Constructor.
+     * Callback function returning false when current connection is not
+     * allowedConnectionType, e.g. because it is a metered connection.
+     */
+    typedef std::function<bool(const std::string* allowedConnectionType)> IsConnectionAllowedCallback;
+
+    /**
+     * FilterEngine creation parameters.
+     */
+    struct CreationParameters
+    {
+      /**
+       * `AdblockPlus::FilterEngine::Prefs` name - value list of preconfigured
+       * prefs.
+       */
+      Prefs preconfiguredPrefs;
+      /**
+       * `AdblockPlus::FilterEngine::IsConnectionAllowedCallback` a callback
+       * checking whether the request from Adblock Plus should be blocked on
+       * the current connection.
+       */
+      IsConnectionAllowedCallback isConnectionAllowedCallback;
+    };
+
+    /**
+    * Callback type invoked when FilterEngine is created.
+    */
+    typedef std::function<void(const FilterEnginePtr&)> OnCreatedCallback;
+
+    /**
+     * Asynchronously constructs FilterEngine.
      * @param jsEngine `JsEngine` instance used to run JavaScript code
      *        internally.
-     * @param preconfiguredPrefs `AdblockPlus::FilterEngine::Prefs`
-     *        name-value list of preconfigured prefs.
-     */
-    explicit FilterEngine(JsEnginePtr jsEngine, 
-        const Prefs& preconfiguredPrefs = Prefs()
-      );
+     * @param onCreated A callback which is called when FilterEngine is ready
+     *        for use.
+     * @param parameters optional creation parameters.
+     */
+    static void CreateAsync(const JsEnginePtr& jsEngine,
+      const OnCreatedCallback& onCreated,
+      const CreationParameters& parameters = CreationParameters());
+
+    /**
+     * Synchronous interface to construct FilterEngine. For details see
+     * asynchronous version CreateAsync.
+     */
+    static FilterEnginePtr Create(const JsEnginePtr& jsEngine,
+      const CreationParameters& params = CreationParameters());
 
     /**
      * Retrieves the `JsEngine` instance associated with this `FilterEngine`
      * instance.
      */
     JsEnginePtr GetJsEngine() const { return jsEngine; }
 
     /**
      * Checks if this is the first run of the application.
      * @return `true` if the application is running for the first time.
      */
     bool IsFirstRun() const;
 
     /**
      * Retrieves a filter object from its text representation.
      * @param text Text representation of the filter,
      *        see https://adblockplus.org/en/filters.
      * @return New `Filter` instance.
      */
-    FilterPtr GetFilter(const std::string& text);
+    FilterPtr GetFilter(const std::string& text) const;
 
     /**
      * Retrieves a subscription object for the supplied URL.
      * @param url Subscription URL.
      * @return New `Subscription` instance.
      */
-    SubscriptionPtr GetSubscription(const std::string& url);
+    SubscriptionPtr GetSubscription(const std::string& url) const;
 
     /**
      * Retrieves the list of custom filters.
      * @return List of custom filters.
      */
     std::vector<FilterPtr> GetListedFilters() const;
 
     /**
      * Retrieves all subscriptions.
      * @return List of subscriptions.
      */
     std::vector<SubscriptionPtr> GetListedSubscriptions() const;
 
     /**
      * Retrieves all recommended subscriptions.
      * @return List of recommended subscriptions.
      */
     std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const;
 
     /**
      * Ensures that Acceptable Ads subscription is enabled or disabled.
-     * @param enabled If the value is true, adds AA subscription in case of
-     *        necessity and enables AA subscription is disabled. If the value
-     *        is false, disables the subscription if it is present and enabled.
-     *        Otherwise has not effect.

[Eric, 2016/12/05 14:40:57]

* @param enabled
*   - if the argument is `true`
*     - ensure that the filter set includes an enabled AA subscription, adding
*       it if needed and enabling it if disabled.
*   - if the argument is `false`
*     - if an AA subscription is present, disable it.
*     - if absent, do nothing.

[sergei, 2017/03/17 15:55:25]

The proposed variant is taken mostly without changes.

+     * @param enabled
+     *   - if the value is `true`
+     *     - ensure that the filter set includes an enabled AA subscription,
+     *       adding it if needed and enabling it if disabled.
+     *   - if the value is `false`
+     *     - if an AA subscription is present, disable it.
+     *     - if absent, do nothing.
      */
     void SetAAEnabled(bool enabled);
 
     /**
-     * Checks whether Acceptable Ads subscription is enaled.

[Eric, 2016/12/05 14:40:57]

"... whether the filter set includes an Acceptable Ads subscription that is
enabled."

[sergei, 2017/03/17 15:55:25]

It cannot be enabled and not included in a filter set.

+     * Checks whether Acceptable Ads subscription is enabled.
      * @return `true` if acceptable ads subscription is present and enabled.
      */
     bool IsAAEnabled() const;
 
     /**
-     * Retrieves the URL of Acceptable Ads provisioned in configuration, what
-     * makes it available even if subscription is not add yet.

[Eric, 2016/12/05 14:40:57]

* Retrieve the URL for an Acceptable Ads subscription from the configuration.
* Use this URL to add an AA subscription if not already present.

[sergei, 2017/03/17 15:55:25]

The aim of this method is not to add the AA subscription using URL, we need this
URL only for UI, in particular to let a user to know where the subscription is
downloaded from and to take a view on the content of the subscription before the
latter is enabled.

In addition it's not supposed that this URL can be freely changed in the
configuration, if you don't like "provisioned in configuration" then I would
rather remove it, "Retrieves the URL of Acceptable Ads subscription, what makes
it available even if subscription is not add yet." It's just an internal
technical detail which may be not communicated to the user and can be changed.

+     * Retrieves the URL of Acceptable Ads subscription, what makes the URL
+     * available even if subscription is not add yet.
      * @return Returns URL of Acceptable Ads.
      */
-    std::string GetAAURL() const;

[Eric, 2016/12/05 14:40:57]

Nit: According to our style conventions, it should be "GetAAUrl()". Even
acronyms get the mixed case treatment.

[sergei, 2017/03/17 15:55:25]

Done.

+    std::string GetAAUrl() const;
 
     /**
      * Invokes the listener set via SetNotificationAvailableCallback() with the
      * next notification to be shown.
      * @param url URL to match notifications to (optional).
      */
     void ShowNextNotification(const std::string& url = std::string());
 
     /**
      * Sets the callback invoked when a notification should be shown.
@@ skipping 86 matching lines @@
      * @param pref Preference name.
      * @param value New value of the preference.
      */
     void SetPref(const std::string& pref, JsValuePtr value);
 
     /**
      * Extracts the host from a URL.
      * @param url URL to extract the host from.
      * @return Extracted host.
      */
-    std::string GetHostFromURL(const std::string& url);
+    std::string GetHostFromURL(const std::string& url) const;
 
     /**
      * Sets the callback invoked when an application update becomes available.
      * @param callback Callback to invoke.
      */
     void SetUpdateAvailableCallback(UpdateAvailableCallback callback);
 
     /**
      * Removes the callback invoked when an application update becomes
      * available.
      */
     void RemoveUpdateAvailableCallback();
 
     /**
      * Forces an immediate update check.
      * `FilterEngine` will automatically check for updates in regular intervals,
      * so applications should only call this when the user triggers an update
      * check manually.
      * @param callback Optional callback to invoke when the update check is
      *        finished. The string parameter will be empty when the update check
      *        succeeded, or contain an error message if it failed.
      *        Note that the callback will be invoked whether updates are
      *        available or not - to react to updates being available, use
      *        `FilterEngine::SetUpdateAvailableCallback()`.
      */
-    void ForceUpdateCheck(UpdateCheckDoneCallback callback);
+    void ForceUpdateCheck(const UpdateCheckDoneCallback& callback = UpdateCheckDoneCallback());
 
     /**
      * Sets the callback invoked when the filters change.
      * @param callback Callback to invoke.
      */
     void SetFilterChangeCallback(FilterChangeCallback callback);
 
     /**
      * Removes the callback invoked when the filters change.
      */
     void RemoveFilterChangeCallback();
+
+    /**
+     * Stores the value indicating what connection types are allowed, it is
+     * passed to CreateParameters::isConnectionAllowed callback.
+     * @param value Stored value. nullptr means removing of any previously
+     *        stored value.
+     */
+    void SetAllowedConnectionType(const std::string* value);
+
+    /**
+      * Retrieves previously stored allowed connection type.
+      * @return Preference value, or `nullptr` if it doesn't exist.
+      */
+    std::unique_ptr<std::string> GetAllowedConnectionType() const;
 
     /**
      * Compares two version strings in
      * [Mozilla toolkit version format](https://developer.mozilla.org/en/docs/Toolkit_version_format).
      * @param v1 First version string.
      * @param v2 Second version string.
      * @return
      *         - `0` if `v1` and `v2` are identical.
      *         - A negative number if `v1` is less than `v2`.
      *         - A positive number if `v1` is greater than `v2`.
      */
-    int CompareVersions(const std::string& v1, const std::string& v2);
+    int CompareVersions(const std::string& v1, const std::string& v2) const;
 
     /**
      * Retrieves the `ContentType` for the supplied string.
      * @param contentType Content type string.
      * @return The `ContentType` for the string.
      * @throw `std::invalid_argument`, if an invalid `contentType` was supplied.
      */
     static ContentType StringToContentType(const std::string& contentType);
 
     /**
      * Retrieves the string representation of the supplied `ContentType`.
      * @param contentType `ContentType` value.
      * @return The string representation of `contentType`.
      * @throw `std::invalid_argument`, if an invalid `contentType` was supplied.
      */
     static std::string ContentTypeToString(ContentType contentType);
 
   private:
     JsEnginePtr jsEngine;
-    bool initialized;
     bool firstRun;
     int updateCheckId;
     static const std::map<ContentType, std::string> contentTypes;
 
-    void InitDone(JsValueList& params);
+    explicit FilterEngine(const JsEnginePtr& jsEngine);
+
     FilterPtr CheckFilterMatch(const std::string& url,
                                ContentTypeMask contentTypeMask,
                                const std::string& documentUrl) const;
     void UpdateAvailable(UpdateAvailableCallback callback, JsValueList& params);
     void UpdateCheckDone(const std::string& eventName,
                          UpdateCheckDoneCallback callback, JsValueList& params);
     void FilterChanged(FilterChangeCallback callback, JsValueList& params);
     void ShowNotification(const ShowNotificationCallback& callback,
       const JsValueList& params);
     FilterPtr GetWhitelistingFilter(const std::string& url,
       ContentTypeMask contentTypeMask, const std::string& documentUrl) const;
     FilterPtr GetWhitelistingFilter(const std::string& url,
       ContentTypeMask contentTypeMask,
       const std::vector<std::string>& documentUrls) const;
   };
 }
 
 #endif