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
  *
  * 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
@@ skipping 100 matching lines @@
      * 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();
+

[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 131 matching lines @@
      */
     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.

+     */
+    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).
      */
     void ShowNextNotification(const std::string& url = std::string());
 
     /**
      * Sets the callback invoked when a notification should be shown.
      * @param callback Callback to invoke.
      */
@@ skipping 177 matching lines @@
       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