Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Unified Diff: include/AdblockPlus/FilterEngine.h

Issue 5728380594946048: Issue 116 - Document the libadblockplus API (Closed)
Patch Set: Documented the remaining relevant files Created Aug. 29, 2014, 4:36 p.m.
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
Index: include/AdblockPlus/FilterEngine.h
===================================================================
--- a/include/AdblockPlus/FilterEngine.h
+++ b/include/AdblockPlus/FilterEngine.h
@@ -31,67 +31,266 @@
{
class FilterEngine;
+ /**
+ * Wrapper for a filter object.
+ */
class Filter : public JsValue,
public std::tr1::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};
Type GetType();
+
+ /**
+ * Checks whether this filter has been added to its subscription.
+ * @return `true` if this filter has been added to its subscription.
+ */
bool IsListed();
+
+ /**
+ * Adds this filter to its subscription.
+ */
void AddToList();
+
+ /**
+ * Removes this filter from its subscription.
+ */
void RemoveFromList();
+
bool operator==(const Filter& filter) const;
Filter(JsValuePtr value);
};
+ /**
+ * Wrapper for a subscription object.
+ */
class Subscription : public JsValue,
public std::tr1::enable_shared_from_this<Subscription>
{
public:
+ /**
+ * Checks if this subscription has been added to the known subscriptions.
+ * @return `true` if this subscription has been added to the known
+ * subscriptions.
+ */
bool IsListed();
+
+ /**
+ * Adds this subscription to the known subscriptions.
+ */
void AddToList();
+
+ /**
+ * Removes this subscription from the known subscriptions.
+ */
void RemoveFromList();
+
+ /**
+ * Updates this subscription, i.e.\ retrieves the latest version from the
+ * subscription URL.
+ */
void UpdateFilters();
+
+ /**
+ * Checks if this subscriptions is currently being updated.
+ * @return `true` if this subscriptions is currently being updated.
+ */
bool IsUpdating();
+
bool operator==(const Subscription& subscription) const;
Subscription(JsValuePtr value);
};
+ /**
+ * Shared smart pointer to a `Filter` instance.
+ */
typedef std::tr1::shared_ptr<Filter> FilterPtr;
+
+ /**
+ * Shared smart pointer to a `Subscription` instance.
+ */
typedef std::tr1::shared_ptr<Subscription> SubscriptionPtr;
+ /**
+ * Main component of Libadblockplus.
+ * It handles:
+ * - Filter management and matching.
+ * - Subscription management and synchronization.
+ * - Update checks for the application.
+ */
class FilterEngine
{
public:
+ /**
+ * Callback invoked when an update is available.
+ */
typedef std::tr1::function<void(const std::string&)> UpdaterCallback;
+
+ /**
+ * Callback invoked when the filters change.
+ */
typedef std::tr1::function<void(const std::string&, const JsValuePtr)> FilterChangeCallback;
explicit FilterEngine(JsEnginePtr jsEngine);
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 object if the filter wasn't known, otherwise the
+ * existing one.
+ */
FilterPtr GetFilter(const std::string& text);
+
+ /**
+ * Retrieves a subscription object for the supplied URL.
+ * @param url Subscription URL.
+ * @return New subscription object if the subscription wasn't known,
+ * otherwise the existing one.
+ */
SubscriptionPtr GetSubscription(const std::string& url);
+
+ /**
+ * Retrieves all known filters.
+ * @return List of known filters.
+ */
std::vector<FilterPtr> GetListedFilters() const;
+
+ /**
+ * Retrieves all known subscriptions.
+ * @return List of known subscriptions.
+ */
std::vector<SubscriptionPtr> GetListedSubscriptions() const;
+
+ /**
+ * Retrieves all recommended subscriptions.
+ * This will parse all subscriptions listed in `subscriptions.xml`.
+ * @return List of recommended subscriptions.
+ */
std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const;
+
+ /**
+ * Checks if any active filter matches the supplied URL.
+ * @param url URL to match.
+ * @param contentType Content type of the requested resource, possible
+ * values are:
+ * - OTHER
+ * - SCRIPT
+ * - IMAGE
+ * - STYLESHEET
+ * - OBJECT
+ * - SUBDOCUMENT
+ * - DOCUMENT
+ * - XMLHTTPREQUEST
+ * - OBJECT_SUBREQUEST
+ * - FONT
+ * - MEDIA
+ * @param documentUrl URL of the document requesting the resource.
+ * Note that there will be more than one document if frames are
+ * involved, see
+ * Matches(const std::string&, const std::string&, const std::vector<std::string>&) const.
+ * @return Matching filter, or `null` if there was no match.
+ */
FilterPtr Matches(const std::string& url,
const std::string& contentType,
const std::string& documentUrl) const;
+
+ /**
+ * Checks if any active filter matches the supplied URL.
+ * @param url URL to match.
+ * @param contentType Content type of the requested resource, possible
+ * values are:
+ * - OTHER
+ * - SCRIPT
+ * - IMAGE
+ * - STYLESHEET
+ * - OBJECT
+ * - SUBDOCUMENT
+ * - DOCUMENT
+ * - XMLHTTPREQUEST
+ * - OBJECT_SUBREQUEST
+ * - FONT
+ * - MEDIA
+ * @param documentUrls Chain of documents requesting the resource.
+ * This will typically be the frame structure. If the application is
+ * not capable of identifying the frame structure, e.g. because it is
+ * a proxy, it can be approximated using `ReferrerMapping`.
+ * @return Matching filter, or `null` if there was no match.
+ */
FilterPtr Matches(const std::string& url,
const std::string& contentType,
const std::vector<std::string>& documentUrls) const;
+
+ /**
+ * Retrieves CSS selectors for all active element hiding filters.
+ * @param domain Domain to retrieve CSS selectors for.
+ * @return List of CSS selectors.
+ */
std::vector<std::string> GetElementHidingSelectors(const std::string& domain) const;
+
+ /**
+ * Retrieves a preference value.
+ * @param pref Preference name.
+ * @return Preference value, or `null` if it doesn't exist.
+ */
JsValuePtr GetPref(const std::string& pref) const;
+
+ /**
+ * Sets a preference value.
+ * @param pref Preference name.
+ * @param value New value of the preference.
+ */
void SetPref(const std::string& pref, JsValuePtr value);
+
+ /**
+ * Extracts the host from an URL.
+ * @param url URL to extract the host from.
+ * @return Extracted host.
+ */
std::string GetHostFromURL(const std::string& url);
+
+ /**
+ * Forces an immediate update check.
+ * @param Optional callback to invoke when updates are available.
+ */
void ForceUpdateCheck(UpdaterCallback callback = 0);
+
+ /**
+ * Sets the callback invoked when the filters change.
+ * @param The callback to invoke.
+ */
void SetFilterChangeCallback(FilterChangeCallback callback);
+
+ /**
+ * Removes the callback invoked when the filters change.
+ */
void RemoveFilterChangeCallback();
+
+ /**
+ * 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);
private:

Powered by Google App Engine
This is Rietveld