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

Delta Between Two Patch Sets: include/AdblockPlus/FilterEngine.h

Issue 5728380594946048: Issue 116 - Document the libadblockplus API (Closed)
Left Patch Set: Documented the remaining relevant files Created Aug. 29, 2014, 4:36 p.m.
Right Patch Set: Write libadblockplus in lower case consistently Created Sept. 2, 2014, 2:18 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « include/AdblockPlus/FileSystem.h ('k') | include/AdblockPlus/JsEngine.h » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
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 14 matching lines...) Expand all
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 /** 34 /**
35 * Wrapper for a filter object. 35 * Wrapper for an Adblock Plus filter object.
36 */ 36 */
37 class Filter : public JsValue, 37 class Filter : public JsValue,
38 public std::tr1::enable_shared_from_this<Filter> 38 public std::tr1::enable_shared_from_this<Filter>
39 { 39 {
40 public: 40 public:
41 /** 41 /**
42 * Filter types, see https://adblockplus.org/en/filters. 42 * Filter types, see https://adblockplus.org/en/filters.
43 */ 43 */
44 enum Type {TYPE_BLOCKING, TYPE_EXCEPTION, 44 enum Type {TYPE_BLOCKING, TYPE_EXCEPTION,
45 TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION, 45 TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION,
46 TYPE_COMMENT, TYPE_INVALID}; 46 TYPE_COMMENT, TYPE_INVALID};
47 47
48 /**
49 * Retrieves the type of this filter.
50 * @return Type of this filter.
51 */
48 Type GetType(); 52 Type GetType();
49 53
50 /** 54 /**
51 * Checks whether this filter has been added to its subscription. 55 * Checks whether this filter has been added to the list of custom filters.
52 * @return `true` if this filter has been added to its subscription. 56 * @return `true` if this filter has been added.
53 */ 57 */
54 bool IsListed(); 58 bool IsListed();
55 59
56 /** 60 /**
57 * Adds this filter to its subscription. 61 * Adds this filter to the list of custom filters.
58 */ 62 */
59 void AddToList(); 63 void AddToList();
60 64
61 /** 65 /**
62 * Removes this filter from its subscription. 66 * Removes this filter from the list of custom filters.
63 */ 67 */
64 void RemoveFromList(); 68 void RemoveFromList();
65 69
66 bool operator==(const Filter& filter) const; 70 bool operator==(const Filter& filter) const;
67 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 */
68 Filter(JsValuePtr value); 78 Filter(JsValuePtr value);
69 }; 79 };
70 80
71 /** 81 /**
72 * Wrapper for a subscription object. 82 * Wrapper for a subscription object.
73 */ 83 */
74 class Subscription : public JsValue, 84 class Subscription : public JsValue,
75 public std::tr1::enable_shared_from_this<Subscription> 85 public std::tr1::enable_shared_from_this<Subscription>
76 { 86 {
77 public: 87 public:
78 /** 88 /**
79 * Checks if this subscription has been added to the known subscriptions. 89 * Checks if this subscription has been added to the list of subscriptions.
80 * @return `true` if this subscription has been added to the known 90 * @return `true` if this subscription has been added.
81 * subscriptions.
82 */ 91 */
83 bool IsListed(); 92 bool IsListed();
84 93
85 /** 94 /**
86 * Adds this subscription to the known subscriptions. 95 * Adds this subscription to the list of subscriptions.
87 */ 96 */
88 void AddToList(); 97 void AddToList();
89 98
90 /** 99 /**
91 * Removes this subscription from the known subscriptions. 100 * Removes this subscription from the list of subscriptions.
92 */ 101 */
93 void RemoveFromList(); 102 void RemoveFromList();
94 103
95 /** 104 /**
96 * Updates this subscription, i.e.\ retrieves the latest version from the 105 * Updates this subscription, i.e.\ retrieves the current filters from the
97 * subscription URL. 106 * subscription URL.
98 */ 107 */
99 void UpdateFilters(); 108 void UpdateFilters();
100 109
101 /** 110 /**
102 * Checks if this subscriptions is currently being updated. 111 * Checks if the subscription is currently being updated.
103 * @return `true` if this subscriptions is currently being updated. 112 * @return `true` if the subscription is currently being updated.
104 */ 113 */
105 bool IsUpdating(); 114 bool IsUpdating();
106 115
107 bool operator==(const Subscription& subscription) const; 116 bool operator==(const Subscription& subscription) const;
108 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 */
109 Subscription(JsValuePtr value); 124 Subscription(JsValuePtr value);
110 }; 125 };
111 126
112 /** 127 /**
113 * Shared smart pointer to a `Filter` instance. 128 * Shared smart pointer to a `Filter` instance.
114 */ 129 */
115 typedef std::tr1::shared_ptr<Filter> FilterPtr; 130 typedef std::tr1::shared_ptr<Filter> FilterPtr;
116 131
117 /** 132 /**
118 * Shared smart pointer to a `Subscription` instance. 133 * Shared smart pointer to a `Subscription` instance.
119 */ 134 */
120 typedef std::tr1::shared_ptr<Subscription> SubscriptionPtr; 135 typedef std::tr1::shared_ptr<Subscription> SubscriptionPtr;
121 136
122 /** 137 /**
123 * Main component of Libadblockplus. 138 * Main component of libadblockplus.
124 * It handles: 139 * It handles:
125 * - Filter management and matching. 140 * - Filter management and matching.
126 * - Subscription management and synchronization. 141 * - Subscription management and synchronization.
127 * - Update checks for the application. 142 * - Update checks for the application.
128 */ 143 */
129 class FilterEngine 144 class FilterEngine
130 { 145 {
131 public: 146 public:
132 /** 147 /**
133 * Callback invoked when an update is available. 148 * Callback type invoked when an update is available.
149 * The parameter is optional error message.
134 */ 150 */
135 typedef std::tr1::function<void(const std::string&)> UpdaterCallback; 151 typedef std::tr1::function<void(const std::string&)> UpdaterCallback;
136 152
137 /** 153 /**
138 * Callback invoked when the filters change. 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.
139 */ 159 */
140 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;
141 161
162 /**
163 * Constructor.
164 * @param jsEngine `JsEngine` instance used to run JavaScript code
165 * internally.
166 */
142 explicit FilterEngine(JsEnginePtr jsEngine); 167 explicit FilterEngine(JsEnginePtr jsEngine);
168
169 /**
170 * Retrieves the `JsEngine` instance associated with this `FilterEngine`
171 * instance.
172 */
143 JsEnginePtr GetJsEngine() const { return jsEngine; } 173 JsEnginePtr GetJsEngine() const { return jsEngine; }
144 174
145 /** 175 /**
146 * Checks if this is the first run of the application. 176 * Checks if this is the first run of the application.
147 * @return `true` if the application is running for the first time. 177 * @return `true` if the application is running for the first time.
148 */ 178 */
149 bool IsFirstRun() const; 179 bool IsFirstRun() const;
150 180
151 /** 181 /**
152 * Retrieves a filter object from its text representation. 182 * Retrieves a filter object from its text representation.
153 * @param text Text representation of the filter, 183 * @param text Text representation of the filter,
154 * see https://adblockplus.org/en/filters. 184 * see https://adblockplus.org/en/filters.
155 * @return New filter object if the filter wasn't known, otherwise the 185 * @return New `Filter` instance.
156 * existing one.
157 */ 186 */
158 FilterPtr GetFilter(const std::string& text); 187 FilterPtr GetFilter(const std::string& text);
159 188
160 /** 189 /**
161 * Retrieves a subscription object for the supplied URL. 190 * Retrieves a subscription object for the supplied URL.
162 * @param url Subscription URL. 191 * @param url Subscription URL.
163 * @return New subscription object if the subscription wasn't known, 192 * @return New `Subscription` instance.
164 * otherwise the existing one.
165 */ 193 */
166 SubscriptionPtr GetSubscription(const std::string& url); 194 SubscriptionPtr GetSubscription(const std::string& url);
167 195
168 /** 196 /**
169 * Retrieves all known filters. 197 * Retrieves the list of custom filters.
170 * @return List of known filters. 198 * @return List of custom filters.
171 */ 199 */
172 std::vector<FilterPtr> GetListedFilters() const; 200 std::vector<FilterPtr> GetListedFilters() const;
173 201
174 /** 202 /**
175 * Retrieves all known subscriptions. 203 * Retrieves all subscriptions.
176 * @return List of known subscriptions. 204 * @return List of subscriptions.
177 */ 205 */
178 std::vector<SubscriptionPtr> GetListedSubscriptions() const; 206 std::vector<SubscriptionPtr> GetListedSubscriptions() const;
179 207
180 /** 208 /**
181 * Retrieves all recommended subscriptions. 209 * Retrieves all recommended subscriptions.
182 * This will parse all subscriptions listed in `subscriptions.xml`.
183 * @return List of recommended subscriptions. 210 * @return List of recommended subscriptions.
184 */ 211 */
185 std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const; 212 std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const;
186 213
187 /** 214 /**
188 * Checks if any active filter matches the supplied URL. 215 * Checks if any active filter matches the supplied URL.
189 * @param url URL to match. 216 * @param url URL to match.
190 * @param contentType Content type of the requested resource, possible 217 * @param contentType Content type of the requested resource, possible
191 * values are: 218 * values are:
192 * - OTHER 219 * - OTHER
(...skipping 26 matching lines...) Expand all
219 * - SCRIPT 246 * - SCRIPT
220 * - IMAGE 247 * - IMAGE
221 * - STYLESHEET 248 * - STYLESHEET
222 * - OBJECT 249 * - OBJECT
223 * - SUBDOCUMENT 250 * - SUBDOCUMENT
224 * - DOCUMENT 251 * - DOCUMENT
225 * - XMLHTTPREQUEST 252 * - XMLHTTPREQUEST
226 * - OBJECT_SUBREQUEST 253 * - OBJECT_SUBREQUEST
227 * - FONT 254 * - FONT
228 * - MEDIA 255 * - MEDIA
229 * @param documentUrls Chain of documents requesting the resource. 256 * @param documentUrls Chain of documents requesting the resource, starting
230 * This will typically be the frame structure. If the application is 257 * with the current resource's parent frame, ending with the
231 * not capable of identifying the frame structure, e.g. because it is 258 * top-level frame.
232 * a proxy, it can be approximated using `ReferrerMapping`. 259 * If the application is not capable of identifying the frame
233 * @return Matching filter, or `null` if there was no match. 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.
234 */ 263 */
235 FilterPtr Matches(const std::string& url, 264 FilterPtr Matches(const std::string& url,
236 const std::string& contentType, 265 const std::string& contentType,
237 const std::vector<std::string>& documentUrls) const; 266 const std::vector<std::string>& documentUrls) const;
238 267
239 /** 268 /**
240 * Retrieves CSS selectors for all active element hiding filters. 269 * Retrieves CSS selectors for all element hiding filters active on the
270 * supplied domain.
241 * @param domain Domain to retrieve CSS selectors for. 271 * @param domain Domain to retrieve CSS selectors for.
242 * @return List of CSS selectors. 272 * @return List of CSS selectors.
243 */ 273 */
244 std::vector<std::string> GetElementHidingSelectors(const std::string& domain ) const; 274 std::vector<std::string> GetElementHidingSelectors(const std::string& domain ) const;
245 275
246 /** 276 /**
247 * Retrieves a preference value. 277 * Retrieves a preference value.
248 * @param pref Preference name. 278 * @param pref Preference name.
249 * @return Preference value, or `null` if it doesn't exist. 279 * @return Preference value, or `null` if it doesn't exist.
250 */ 280 */
251 JsValuePtr GetPref(const std::string& pref) const; 281 JsValuePtr GetPref(const std::string& pref) const;
252 282
253 /** 283 /**
254 * Sets a preference value. 284 * Sets a preference value.
255 * @param pref Preference name. 285 * @param pref Preference name.
256 * @param value New value of the preference. 286 * @param value New value of the preference.
257 */ 287 */
258 void SetPref(const std::string& pref, JsValuePtr value); 288 void SetPref(const std::string& pref, JsValuePtr value);
259 289
260 /** 290 /**
261 * Extracts the host from an URL. 291 * Extracts the host from a URL.
262 * @param url URL to extract the host from. 292 * @param url URL to extract the host from.
263 * @return Extracted host. 293 * @return Extracted host.
264 */ 294 */
265 std::string GetHostFromURL(const std::string& url); 295 std::string GetHostFromURL(const std::string& url);
266 296
267 /** 297 /**
268 * Forces an immediate update check. 298 * Forces an immediate update check.
269 * @param Optional callback to invoke when updates are available. 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()).
270 */ 308 */
271 void ForceUpdateCheck(UpdaterCallback callback = 0); 309 void ForceUpdateCheck(UpdaterCallback callback = 0);
272 310
273 /** 311 /**
274 * Sets the callback invoked when the filters change. 312 * Sets the callback invoked when the filters change.
275 * @param The callback to invoke. 313 * @param callback Callback to invoke.
276 */ 314 */
277 void SetFilterChangeCallback(FilterChangeCallback callback); 315 void SetFilterChangeCallback(FilterChangeCallback callback);
278 316
279 /** 317 /**
280 * Removes the callback invoked when the filters change. 318 * Removes the callback invoked when the filters change.
281 */ 319 */
282 void RemoveFilterChangeCallback(); 320 void RemoveFilterChangeCallback();
283 321
284 /** 322 /**
285 * Compares two version strings in 323 * Compares two version strings in
(...skipping 16 matching lines...) Expand all
302 void InitDone(JsValueList& params); 340 void InitDone(JsValueList& params);
303 FilterPtr CheckFilterMatch(const std::string& url, 341 FilterPtr CheckFilterMatch(const std::string& url,
304 const std::string& contentType, 342 const std::string& contentType,
305 const std::string& documentUrl) const; 343 const std::string& documentUrl) const;
306 void UpdateCheckDone(const std::string& eventName, UpdaterCallback callback, JsValueList& params); 344 void UpdateCheckDone(const std::string& eventName, UpdaterCallback callback, JsValueList& params);
307 void FilterChanged(FilterChangeCallback callback, JsValueList& params); 345 void FilterChanged(FilterChangeCallback callback, JsValueList& params);
308 }; 346 };
309 } 347 }
310 348
311 #endif 349 #endif
LEFTRIGHT

Powered by Google App Engine
This is Rietveld