Issue 4657 - Add Acceptable Ads API

include/AdblockPlus/FilterEngine.h

Index: include/AdblockPlus/FilterEngine.h
diff --git a/include/AdblockPlus/FilterEngine.h b/include/AdblockPlus/FilterEngine.h
index 94b376eb8caadee35db2d4b96893ee5b0702b16d..bf5d4de9db7c5dfd8451071bddfae333f46692a0 100644
--- a/include/AdblockPlus/FilterEngine.h
+++ b/include/AdblockPlus/FilterEngine.h
@@ -118,6 +118,12 @@ namespace AdblockPlus
      */
     bool IsUpdating();
 
+    /**
+      * Indicates whether the subscription is acceptable ads subscription.
+      * @return `true` if this subscription is acceptable ads subscription.
+      */
+    bool IsAA();
+

[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;
 
     /**
@@ -269,6 +275,28 @@ namespace AdblockPlus
     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.

+     */
+    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.

+     * @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.

+     * @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.

+
+    /**
      * Invokes the listener set via SetNotificationAvailableCallback() with the
      * next notification to be shown.
      * @param url URL to match notifications to (optional).