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

Side by Side Diff: include/AdblockPlus/FilterEngine.h

Issue 5728380594946048: Issue 116 - Document the libadblockplus API (Closed)
Patch Set: Fix broken sentences Created Sept. 2, 2014, 5:43 a.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « include/AdblockPlus/FileSystem.h ('k') | include/AdblockPlus/JsEngine.h » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 /* 1 /*
2 * This file is part of Adblock Plus <http://adblockplus.org/>, 2 * This file is part of Adblock Plus <http://adblockplus.org/>,
3 * Copyright (C) 2006-2014 Eyeo GmbH 3 * Copyright (C) 2006-2014 Eyeo GmbH
4 * 4 *
5 * Adblock Plus is free software: you can redistribute it and/or modify 5 * Adblock Plus is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License version 3 as 6 * it under the terms of the GNU General Public License version 3 as
7 * published by the Free Software Foundation. 7 * published by the Free Software Foundation.
8 * 8 *
9 * Adblock Plus is distributed in the hope that it will be useful, 9 * Adblock Plus is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
(...skipping 13 matching lines...) Expand all
24 #include <vector> 24 #include <vector>
25 #include <AdblockPlus/JsEngine.h> 25 #include <AdblockPlus/JsEngine.h>
26 #include <AdblockPlus/JsValue.h> 26 #include <AdblockPlus/JsValue.h>
27 27
28 #include "tr1_memory.h" 28 #include "tr1_memory.h"
29 29
30 namespace AdblockPlus 30 namespace AdblockPlus
31 { 31 {
32 class FilterEngine; 32 class FilterEngine;
33 33
34 /**
35 * Wrapper for an Adblock Plus filter object.
36 */
34 class Filter : public JsValue, 37 class Filter : public JsValue,
35 public std::tr1::enable_shared_from_this<Filter> 38 public std::tr1::enable_shared_from_this<Filter>
36 { 39 {
37 public: 40 public:
41 /**
42 * Filter types, see https://adblockplus.org/en/filters.
43 */
38 enum Type {TYPE_BLOCKING, TYPE_EXCEPTION, 44 enum Type {TYPE_BLOCKING, TYPE_EXCEPTION,
39 TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION, 45 TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION,
40 TYPE_COMMENT, TYPE_INVALID}; 46 TYPE_COMMENT, TYPE_INVALID};
41 47
48 /**
49 * Retrieves the type of this filter.
50 * @return Type of this filter.
51 */
42 Type GetType(); 52 Type GetType();
53
54 /**
55 * Checks whether this filter has been added to the list of custom filters.
56 * @return `true` if this filter has been added.
57 */
43 bool IsListed(); 58 bool IsListed();
59
60 /**
61 * Adds this filter to the list of custom filters.
62 */
44 void AddToList(); 63 void AddToList();
64
65 /**
66 * Removes this filter from the list of custom filters.
67 */
45 void RemoveFromList(); 68 void RemoveFromList();
69
46 bool operator==(const Filter& filter) const; 70 bool operator==(const Filter& filter) const;
47 71
72 /**
73 * Creates a wrapper for an existing JavaScript filter object.
74 * Normally you shouldn't call this directly, but use
75 * FilterEngine::GetFilter() instead.
76 * @param value JavaScript filter object.
77 */
48 Filter(JsValuePtr value); 78 Filter(JsValuePtr value);
49 }; 79 };
50 80
81 /**
82 * Wrapper for a subscription object.
83 */
51 class Subscription : public JsValue, 84 class Subscription : public JsValue,
52 public std::tr1::enable_shared_from_this<Subscription> 85 public std::tr1::enable_shared_from_this<Subscription>
53 { 86 {
54 public: 87 public:
88 /**
89 * Checks if this subscription has been added to the list of subscriptions.
90 * @return `true` if this subscription has been added.
91 */
55 bool IsListed(); 92 bool IsListed();
93
94 /**
95 * Adds this subscription to the list of subscriptions.
96 */
56 void AddToList(); 97 void AddToList();
98
99 /**
100 * Removes this subscription from the list of subscriptions.
101 */
57 void RemoveFromList(); 102 void RemoveFromList();
103
104 /**
105 * Updates this subscription, i.e.\ retrieves the current filters from the
106 * subscription URL.
107 */
58 void UpdateFilters(); 108 void UpdateFilters();
109
110 /**
111 * Checks if subscriptions are currently being updated.
112 * @return `true` if subscriptions are currently being updated.
113 */
59 bool IsUpdating(); 114 bool IsUpdating();
115
60 bool operator==(const Subscription& subscription) const; 116 bool operator==(const Subscription& subscription) const;
61 117
118 /**
119 * Creates a wrapper for an existing JavaScript subscription object.
120 * Normally you shouldn't call this directly, but use
121 * FilterEngine::GetSubscription() instead.
122 * @param value JavaScript subscription object.
123 */
62 Subscription(JsValuePtr value); 124 Subscription(JsValuePtr value);
63 }; 125 };
64 126
127 /**
128 * Shared smart pointer to a `Filter` instance.
129 */
65 typedef std::tr1::shared_ptr<Filter> FilterPtr; 130 typedef std::tr1::shared_ptr<Filter> FilterPtr;
131
132 /**
133 * Shared smart pointer to a `Subscription` instance.
134 */
66 typedef std::tr1::shared_ptr<Subscription> SubscriptionPtr; 135 typedef std::tr1::shared_ptr<Subscription> SubscriptionPtr;
67 136
137 /**
138 * Main component of Libadblockplus.
139 * It handles:
140 * - Filter management and matching.
141 * - Subscription management and synchronization.
142 * - Update checks for the application.
143 */
68 class FilterEngine 144 class FilterEngine
69 { 145 {
70 public: 146 public:
147 /**
148 * Callback type invoked when an update is available.
149 * The parameter is optional error message.
150 */
71 typedef std::tr1::function<void(const std::string&)> UpdaterCallback; 151 typedef std::tr1::function<void(const std::string&)> UpdaterCallback;
152
153 /**
154 * Callback type invoked when the filters change.
155 * The first parameter is the action event code (see
156 * [FilterNotifier.triggerListeners](https://adblockplus.org/jsdoc/adblockpl us/symbols/FilterNotifier.html#.triggerListeners)
157 * for the full list).
158 * The second parameter is the filter/subscription object affected, if any.
159 */
72 typedef std::tr1::function<void(const std::string&, const JsValuePtr)> Filte rChangeCallback; 160 typedef std::tr1::function<void(const std::string&, const JsValuePtr)> Filte rChangeCallback;
73 161
162 /**
163 * Constructor.
164 * @param jsEngine `JsEngine` instance used to run JavaScript code
165 * internally.
166 */
74 explicit FilterEngine(JsEnginePtr jsEngine); 167 explicit FilterEngine(JsEnginePtr jsEngine);
168
169 /**
170 * Retrieves the `JsEngine` instance associated with this `FilterEngine`
171 * instance.
172 */
75 JsEnginePtr GetJsEngine() const { return jsEngine; } 173 JsEnginePtr GetJsEngine() const { return jsEngine; }
174
175 /**
176 * Checks if this is the first run of the application.
177 * @return `true` if the application is running for the first time.
178 */
76 bool IsFirstRun() const; 179 bool IsFirstRun() const;
180
181 /**
182 * Retrieves a filter object from its text representation.
183 * @param text Text representation of the filter,
184 * see https://adblockplus.org/en/filters.
185 * @return New `Filter` instance.
186 */
77 FilterPtr GetFilter(const std::string& text); 187 FilterPtr GetFilter(const std::string& text);
188
189 /**
190 * Retrieves a subscription object for the supplied URL.
191 * @param url Subscription URL.
192 * @return New `Subscription` instance.
193 */
78 SubscriptionPtr GetSubscription(const std::string& url); 194 SubscriptionPtr GetSubscription(const std::string& url);
195
196 /**
197 * Retrieves the list of custom filters.
198 * @return List of custom filters.
199 */
79 std::vector<FilterPtr> GetListedFilters() const; 200 std::vector<FilterPtr> GetListedFilters() const;
201
202 /**
203 * Retrieves all subscriptions.
204 * @return List of subscriptions.
205 */
80 std::vector<SubscriptionPtr> GetListedSubscriptions() const; 206 std::vector<SubscriptionPtr> GetListedSubscriptions() const;
207
208 /**
209 * Retrieves all recommended subscriptions.
210 * @return List of recommended subscriptions.
211 */
81 std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const; 212 std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const;
213
214 /**
215 * Checks if any active filter matches the supplied URL.
216 * @param url URL to match.
217 * @param contentType Content type of the requested resource, possible
218 * values are:
219 * - OTHER
220 * - SCRIPT
221 * - IMAGE
222 * - STYLESHEET
223 * - OBJECT
224 * - SUBDOCUMENT
225 * - DOCUMENT
226 * - XMLHTTPREQUEST
227 * - OBJECT_SUBREQUEST
228 * - FONT
229 * - MEDIA
230 * @param documentUrl URL of the document requesting the resource.
231 * Note that there will be more than one document if frames are
232 * involved, see
233 * Matches(const std::string&, const std::string&, const std::vector< std::string>&) const.
234 * @return Matching filter, or `null` if there was no match.
235 */
82 FilterPtr Matches(const std::string& url, 236 FilterPtr Matches(const std::string& url,
83 const std::string& contentType, 237 const std::string& contentType,
84 const std::string& documentUrl) const; 238 const std::string& documentUrl) const;
239
240 /**
241 * Checks if any active filter matches the supplied URL.
242 * @param url URL to match.
243 * @param contentType Content type of the requested resource, possible
244 * values are:
245 * - OTHER
246 * - SCRIPT
247 * - IMAGE
248 * - STYLESHEET
249 * - OBJECT
250 * - SUBDOCUMENT
251 * - DOCUMENT
252 * - XMLHTTPREQUEST
253 * - OBJECT_SUBREQUEST
254 * - FONT
255 * - MEDIA
256 * @param documentUrls Chain of documents requesting the resource, starting
257 * with the current resource's parent frame, ending with the
258 * top-level frame.
259 * If the application is not capable of identifying the frame
260 * structure, e.g. because it is a proxy, it can be approximated
261 * using `ReferrerMapping`.
262 * @return Matching filter, or a `null` if there was no match.
263 */
85 FilterPtr Matches(const std::string& url, 264 FilterPtr Matches(const std::string& url,
86 const std::string& contentType, 265 const std::string& contentType,
87 const std::vector<std::string>& documentUrls) const; 266 const std::vector<std::string>& documentUrls) const;
267
268 /**
269 * Retrieves CSS selectors for all element hiding filters active on the
270 * supplied domain.
271 * @param domain Domain to retrieve CSS selectors for.
272 * @return List of CSS selectors.
273 */
88 std::vector<std::string> GetElementHidingSelectors(const std::string& domain ) const; 274 std::vector<std::string> GetElementHidingSelectors(const std::string& domain ) const;
275
276 /**
277 * Retrieves a preference value.
278 * @param pref Preference name.
279 * @return Preference value, or `null` if it doesn't exist.
280 */
89 JsValuePtr GetPref(const std::string& pref) const; 281 JsValuePtr GetPref(const std::string& pref) const;
282
283 /**
284 * Sets a preference value.
285 * @param pref Preference name.
286 * @param value New value of the preference.
287 */
90 void SetPref(const std::string& pref, JsValuePtr value); 288 void SetPref(const std::string& pref, JsValuePtr value);
289
290 /**
291 * Extracts the host from a URL.
292 * @param url URL to extract the host from.
293 * @return Extracted host.
294 */
91 std::string GetHostFromURL(const std::string& url); 295 std::string GetHostFromURL(const std::string& url);
296
297 /**
298 * Forces an immediate update check.
299 * `FilterEngine` will automatically check for updates in regular intervals,
300 * so applications should only call this when the user triggers an update
301 * check manually.
302 * @param callback Optional callback to invoke when the update check is
303 * finished. The string parameter will be empty when the update check
304 * succeeded, or contain an error message if it failed.
305 * Note that the callback will be invoked after every update check -
306 * to react to updates being available, register a callback for the
307 * "updateAvailable" event (see JsEngine::SetEventCallback()).
308 */
92 void ForceUpdateCheck(UpdaterCallback callback = 0); 309 void ForceUpdateCheck(UpdaterCallback callback = 0);
310
311 /**
312 * Sets the callback invoked when the filters change.
313 * @param callback Callback to invoke.
314 */
93 void SetFilterChangeCallback(FilterChangeCallback callback); 315 void SetFilterChangeCallback(FilterChangeCallback callback);
316
317 /**
318 * Removes the callback invoked when the filters change.
319 */
94 void RemoveFilterChangeCallback(); 320 void RemoveFilterChangeCallback();
321
322 /**
323 * Compares two version strings in
324 * [Mozilla toolkit version format](https://developer.mozilla.org/en/docs/To olkit_version_format).
325 * @param v1 First version string.
326 * @param v2 Second version string.
327 * @return
328 * - `0` if `v1` and `v2` are identical.
329 * - A negative number if `v1` is less than `v2`.
330 * - A positive number if `v1` is greater than `v2`.
331 */
95 int CompareVersions(const std::string& v1, const std::string& v2); 332 int CompareVersions(const std::string& v1, const std::string& v2);
96 333
97 private: 334 private:
98 JsEnginePtr jsEngine; 335 JsEnginePtr jsEngine;
99 bool initialized; 336 bool initialized;
100 bool firstRun; 337 bool firstRun;
101 int updateCheckId; 338 int updateCheckId;
102 339
103 void InitDone(JsValueList& params); 340 void InitDone(JsValueList& params);
104 FilterPtr CheckFilterMatch(const std::string& url, 341 FilterPtr CheckFilterMatch(const std::string& url,
105 const std::string& contentType, 342 const std::string& contentType,
106 const std::string& documentUrl) const; 343 const std::string& documentUrl) const;
107 void UpdateCheckDone(const std::string& eventName, UpdaterCallback callback, JsValueList& params); 344 void UpdateCheckDone(const std::string& eventName, UpdaterCallback callback, JsValueList& params);
108 void FilterChanged(FilterChangeCallback callback, JsValueList& params); 345 void FilterChanged(FilterChangeCallback callback, JsValueList& params);
109 }; 346 };
110 } 347 }
111 348
112 #endif 349 #endif
OLDNEW
« no previous file with comments | « include/AdblockPlus/FileSystem.h ('k') | include/AdblockPlus/JsEngine.h » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld