Index: .hgignore
===================================================================
--- a/.hgignore
+++ b/.hgignore
@@ -1,4 +1,5 @@
^build
+^docs
.pyc$
syntax: glob
Index: Doxyfile
===================================================================
new file mode 100644
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,7 @@
+PROJECT_NAME = "libadblockplus"
+OUTPUT_DIRECTORY = docs
+JAVADOC_AUTOBRIEF = YES
+TAB_SIZE = 2
+DISTRIBUTE_GROUP_DOC = YES
+INPUT = include
+RECURSIVE = YES
Index: Makefile
===================================================================
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,7 @@
TEST_EXECUTABLE = build/out/Debug/tests
-.PHONY: all test clean v8_android android
+.PHONY: all test clean v8_android android docs
all:
third_party/gyp/gyp --depth=. -f make -I common.gypi --generator-output=build -Dtarget_arch=$(ARCH) libadblockplus.gyp
@@ -19,8 +19,11 @@
$(TEST_EXECUTABLE)
endif
+docs:
+ doxygen
+
clean:
- $(RM) -r build
+ $(RM) -r build docs
v8_android:
mkdir -p third_party/v8/build/gyp
Index: include/AdblockPlus.h
===================================================================
--- a/include/AdblockPlus.h
+++ b/include/AdblockPlus.h
@@ -15,6 +15,18 @@
* along with Adblock Plus. If not, see .
*/
+/**
+ * @mainpage libadblockplus source code documentation
+ * This is the source code documentation of libadblockplus. See the
+ * README
+ * for build instructions and basic usage.
+ */
+
+/**
+ * @namespace AdblockPlus
+ * Main namespace of libadblockplus.
+ */
+
#ifndef ADBLOCK_PLUS_ADBLOCK_PLUS_H
#define ADBLOCK_PLUS_ADBLOCK_PLUS_H
Index: include/AdblockPlus/AppInfo.h
===================================================================
--- a/include/AdblockPlus/AppInfo.h
+++ b/include/AdblockPlus/AppInfo.h
@@ -22,14 +22,47 @@
namespace AdblockPlus
{
+ /**
+ * Information about the app using libadblockplus.
+ */
struct AppInfo
{
+ /**
+ * Optional unique ID of the app.
+ * @deprecated This field is not used anywhere, and will be removed.
+ */
std::string id;
+
+ /**
+ * Current version of the app, in
+ * [Mozilla toolkit version format](https://developer.mozilla.org/en/docs/Toolkit_version_format).
+ */
std::string version;
+
+ /**
+ * Technical name of the app (not user visible).
+ */
std::string name;
+
+ /**
+ * Technical name of the platform the app is running on (not user visible).
+ */
std::string application;
+
+ /**
+ * Current version of the platform the app is running on.
+ */
std::string applicationVersion;
+
+ /**
+ * Locale to use, as a
+ * [Mozilla locale code](https://wiki.mozilla.org/L10n:Locale_Codes).
+ */
std::string locale;
+
+ /**
+ * Whether the app is a development build, the default is `false`.
+ */
bool developmentBuild;
AppInfo() : developmentBuild(false) {}
Index: include/AdblockPlus/DefaultFileSystem.h
===================================================================
--- a/include/AdblockPlus/DefaultFileSystem.h
+++ b/include/AdblockPlus/DefaultFileSystem.h
@@ -28,6 +28,12 @@
namespace AdblockPlus
{
+ /**
+ * `FileSystem` implementation that interacts directly with the operating
+ * system's file system.
+ * All paths are considered relative to the base path, or to the current
+ * working directory if no base path is set (see `SetBasePath()`).
+ */
class DefaultFileSystem : public FileSystem
{
public:
@@ -39,7 +45,13 @@
void Remove(const std::string& path);
StatResult Stat(const std::string& path) const;
std::string Resolve(const std::string& path) const;
+
+ /**
+ * Sets the base path, all paths are considered relative to it.
+ * @param path Base path.
+ */
void SetBasePath(const std::string& path);
+
protected:
std::string basePath;
};
Index: include/AdblockPlus/DefaultLogSystem.h
===================================================================
--- a/include/AdblockPlus/DefaultLogSystem.h
+++ b/include/AdblockPlus/DefaultLogSystem.h
@@ -22,6 +22,9 @@
namespace AdblockPlus
{
+ /**
+ * `LogSystem` implementation that writes messages to stderr.
+ */
class DefaultLogSystem : public LogSystem
{
public:
Index: include/AdblockPlus/DefaultWebRequest.h
===================================================================
--- a/include/AdblockPlus/DefaultWebRequest.h
+++ b/include/AdblockPlus/DefaultWebRequest.h
@@ -22,6 +22,11 @@
namespace AdblockPlus
{
+ /**
+ * `WebRequest` implementation that uses `WinInet` on Windows and libcurl
+ * on other platforms. A dummy implementation that always reports failure is
+ * used if libcurl is not available.
+ */
class DefaultWebRequest : public WebRequest
{
ServerResponse GET(const std::string& url, const HeaderList& requestHeaders) const;
Index: include/AdblockPlus/FileSystem.h
===================================================================
--- a/include/AdblockPlus/FileSystem.h
+++ b/include/AdblockPlus/FileSystem.h
@@ -26,9 +26,15 @@
namespace AdblockPlus
{
+ /**
+ * File system interface.
+ */
class FileSystem
{
public:
+ /**
+ * Result of a stat operation, i.e.\ information about a file.
+ */
struct StatResult
{
StatResult()
@@ -39,24 +45,77 @@
lastModified = 0;
}
+ /**
+ * File exists.
+ */
bool exists;
+
+ /**
+ * File is a directory.
+ */
bool isDirectory;
+
+ /**
+ * File is a regular file.
+ */
bool isFile;
+
+ /**
+ * POSIX time of the last modification.
+ */
int64_t lastModified;
};
virtual ~FileSystem() {}
+
+ /**
+ * Reads from a file.
+ * @param path File path.
+ * @return Input stream with the file's contents.
+ */
virtual std::tr1::shared_ptr
Read(const std::string& path) const = 0;
+
+ /**
+ * Writes to a file.
+ * @param path File path.
+ * @param data Input stream with the data to write.
+ */
virtual void Write(const std::string& path,
std::tr1::shared_ptr data) = 0;
+
+ /**
+ * Moves a file (i.e.\ renames it).
+ * @param fromPath Current path to the file.
+ * @param toPath New path to the file.
+ */
virtual void Move(const std::string& fromPath,
const std::string& toPath) = 0;
+
+ /**
+ * Removes a file.
+ * @param path File path.
+ */
virtual void Remove(const std::string& path) = 0;
+
+ /**
+ * Retrieves information about a file.
+ * @param path File path.
+ * @return File information.
+ */
virtual StatResult Stat(const std::string& path) const = 0;
+
+ /**
+ * Returns the absolute path to a file.
+ * @param path File path (can be relative or absolute).
+ * @return Absolute file path.
+ */
virtual std::string Resolve(const std::string& path) const = 0;
};
+ /**
+ * Shared smart pointer to a `FileSystem` instance.
+ */
typedef std::tr1::shared_ptr FileSystemPtr;
}
Index: include/AdblockPlus/FilterEngine.h
===================================================================
--- a/include/AdblockPlus/FilterEngine.h
+++ b/include/AdblockPlus/FilterEngine.h
@@ -31,67 +31,304 @@
{
class FilterEngine;
+ /**
+ * Wrapper for an Adblock Plus filter object.
+ */
class Filter : public JsValue,
public std::tr1::enable_shared_from_this
{
public:
+ /**
+ * Filter types, see https://adblockplus.org/en/filters.
+ */
enum Type {TYPE_BLOCKING, TYPE_EXCEPTION,
TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION,
TYPE_COMMENT, TYPE_INVALID};
+ /**
+ * Retrieves the type of this filter.
+ * @return Type of this filter.
+ */
Type GetType();
+
+ /**
+ * Checks whether this filter has been added to the list of custom filters.
+ * @return `true` if this filter has been added.
+ */
bool IsListed();
+
+ /**
+ * Adds this filter to the list of custom filters.
+ */
void AddToList();
+
+ /**
+ * Removes this filter from the list of custom filters.
+ */
void RemoveFromList();
+
bool operator==(const Filter& filter) const;
+ /**
+ * Creates a wrapper for an existing JavaScript filter object.
+ * Normally you shouldn't call this directly, but use
+ * FilterEngine::GetFilter() instead.
+ * @param value JavaScript filter object.
+ */
Filter(JsValuePtr value);
};
+ /**
+ * Wrapper for a subscription object.
+ */
class Subscription : public JsValue,
public std::tr1::enable_shared_from_this
{
public:
+ /**
+ * Checks if this subscription has been added to the list of subscriptions.
+ * @return `true` if this subscription has been added.
+ */
bool IsListed();
+
+ /**
+ * Adds this subscription to the list of subscriptions.
+ */
void AddToList();
+
+ /**
+ * Removes this subscription from the list of subscriptions.
+ */
void RemoveFromList();
+
+ /**
+ * Updates this subscription, i.e.\ retrieves the current filters from the
+ * subscription URL.
+ */
void UpdateFilters();
+
+ /**
+ * Checks if the subscription is currently being updated.
+ * @return `true` if the subscription is currently being updated.
+ */
bool IsUpdating();
+
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(JsValuePtr value);
};
+ /**
+ * Shared smart pointer to a `Filter` instance.
+ */
typedef std::tr1::shared_ptr FilterPtr;
+
+ /**
+ * Shared smart pointer to a `Subscription` instance.
+ */
typedef std::tr1::shared_ptr SubscriptionPtr;
+ /**
+ * Main component of libadblockplus.
+ * It handles:
+ * - Filter management and matching.
+ * - Subscription management and synchronization.
+ * - Update checks for the application.
+ */
class FilterEngine
{
public:
+ /**
+ * Callback type invoked when an update is available.
+ * The parameter is optional error message.
+ */
typedef std::tr1::function UpdaterCallback;
+
+ /**
+ * Callback type invoked when the filters change.
+ * The first parameter is the action event code (see
+ * [FilterNotifier.triggerListeners](https://adblockplus.org/jsdoc/adblockplus/symbols/FilterNotifier.html#.triggerListeners)
+ * for the full list).
+ * The second parameter is the filter/subscription object affected, if any.
+ */
typedef std::tr1::function FilterChangeCallback;
+ /**
+ * Constructor.
+ * @param jsEngine `JsEngine` instance used to run JavaScript code
+ * internally.
+ */
explicit FilterEngine(JsEnginePtr jsEngine);
+
+ /**
+ * Retrieves the `JsEngine` instance associated with this `FilterEngine`
+ * instance.
+ */
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` instance.
+ */
FilterPtr GetFilter(const std::string& text);
+
+ /**
+ * Retrieves a subscription object for the supplied URL.
+ * @param url Subscription URL.
+ * @return New `Subscription` instance.
+ */
SubscriptionPtr GetSubscription(const std::string& url);
+
+ /**
+ * Retrieves the list of custom filters.
+ * @return List of custom filters.
+ */
std::vector GetListedFilters() const;
+
+ /**
+ * Retrieves all subscriptions.
+ * @return List of subscriptions.
+ */
std::vector GetListedSubscriptions() const;
+
+ /**
+ * Retrieves all recommended subscriptions.
+ * @return List of recommended subscriptions.
+ */
std::vector 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&) 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, starting
+ * with the current resource's parent frame, ending with the
+ * top-level frame.
+ * 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 a `null` if there was no match.
+ */
FilterPtr Matches(const std::string& url,
const std::string& contentType,
const std::vector& documentUrls) const;
+
+ /**
+ * Retrieves CSS selectors for all element hiding filters active on the
+ * supplied domain.
+ * @param domain Domain to retrieve CSS selectors for.
+ * @return List of CSS selectors.
+ */
std::vector 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 a URL.
+ * @param url URL to extract the host from.
+ * @return Extracted host.
+ */
std::string GetHostFromURL(const std::string& url);
+
+ /**
+ * Forces an immediate update check.
+ * `FilterEngine` will automatically check for updates in regular intervals,
+ * so applications should only call this when the user triggers an update
+ * check manually.
+ * @param callback Optional callback to invoke when the update check is
+ * finished. The string parameter will be empty when the update check
+ * succeeded, or contain an error message if it failed.
+ * Note that the callback will be invoked after every update check -
+ * to react to updates being available, register a callback for the
+ * "updateAvailable" event (see JsEngine::SetEventCallback()).
+ */
void ForceUpdateCheck(UpdaterCallback callback = 0);
+
+ /**
+ * Sets the callback invoked when the filters change.
+ * @param callback 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:
Index: include/AdblockPlus/JsEngine.h
===================================================================
--- a/include/AdblockPlus/JsEngine.h
+++ b/include/AdblockPlus/JsEngine.h
@@ -45,24 +45,80 @@
namespace AdblockPlus
{
class JsEngine;
+
+ /**
+ * Shared smart pointer to a `JsEngine` instance.
+ */
typedef std::tr1::shared_ptr JsEnginePtr;
+ /**
+ * JavaScript engine used by `FilterEngine`, wraps v8.
+ */
class JsEngine : public std::tr1::enable_shared_from_this
{
friend class JsValue;
friend class JsContext;
public:
+ /**
+ * Event callback function.
+ */
typedef std::tr1::function EventCallback;
+
+ /**
+ * Maps events to callback functions.
+ */
typedef std::map EventMap;
+ /**
+ * Creates a new JavaScript engine instance.
+ * @param appInfo Information about the app.
+ * @return New `JsEngine` instance.
+ */
static JsEnginePtr New(const AppInfo& appInfo = AppInfo());
+
+ /**
+ * Registers the callback function for an event.
+ * @param eventName Event name. Note that this can be any string - it's a
+ * general purpose event handling mechanism.
+ * @param callback Event callback function.
+ */
void SetEventCallback(const std::string& eventName, EventCallback callback);
+
+ /**
+ * Removes the callback function for an event.
+ * @param eventName Event name.
+ */
void RemoveEventCallback(const std::string& eventName);
+
+ /**
+ * Triggers an event.
+ * @param eventName Event name.
+ * @param params Event parameters.
+ */
void TriggerEvent(const std::string& eventName, JsValueList& params);
+
+ /**
+ * Evaluates a JavaScript expression.
+ * @param source JavaScript expression to evaluate.
+ * @param filename Optional file name for the expression, used in error
+ * messages.
+ * @return Result of the evaluated expression.
+ */
JsValuePtr Evaluate(const std::string& source,
const std::string& filename = "");
+
+ /**
+ * Initiates a garbage collection.
+ */
void Gc();
+
+ //@{
+ /**
+ * Creates a new JavaScript value.
+ * @param val Value to convert.
+ * @return New `JsValue` instance.
+ */
JsValuePtr NewValue(const std::string& val);
JsValuePtr NewValue(int64_t val);
JsValuePtr NewValue(bool val);
@@ -80,16 +136,79 @@
return NewValue(static_cast(val));
}
#endif
+ //@}
+
+ /**
+ * Creates a new JavaScript object.
+ * @return New `JsValue` instance.
+ */
JsValuePtr NewObject();
+
+ /**
+ * Creates a JavaScript function that invokes a C++ callback.
+ * @param callback C++ callback to invoke. The callback receives a
+ * `v8::Arguments` object and can use `FromArguments()` to retrieve
+ * the current `JsEngine`.
+ * @return New `JsValue` instance.
+ */
JsValuePtr NewCallback(v8::InvocationCallback callback);
+
+ /**
+ * Returns a `JsEngine` instance contained in a `v8::Arguments` object.
+ * Use this in callbacks created via `NewCallback()` to retrieve the current
+ * `JsEngine`.
+ * @param arguments `v8::Arguments` object containing the `JsEngine`
+ * instance.
+ * @return `JsEngine` instance from `v8::Arguments`.
+ */
static JsEnginePtr FromArguments(const v8::Arguments& arguments);
+
+ /**
+ * Converts v8 arguments to `JsValue` objects.
+ * @param arguments `v8::Arguments` object containing the arguments to
+ * convert.
+ * @return List of arguments converted to `JsValue` objects.
+ */
JsValueList ConvertArguments(const v8::Arguments& arguments);
+ /**
+ * @see `SetFileSystem()`.
+ */
FileSystemPtr GetFileSystem();
+
+ /**
+ * Sets the `FileSystem` implementation used for all file I/O.
+ * Setting this is optional, the engine will use a `DefaultFileSystem`
+ * instance by default, which might be sufficient.
+ * @param The `FileSystem` instance to use.
+ */
void SetFileSystem(FileSystemPtr val);
+
+ /**
+ * @see `SetWebRequest()`.
+ */
WebRequestPtr GetWebRequest();
+
+ /**
+ * Sets the `WebRequest` implementation used for XMLHttpRequests.
+ * Setting this is optional, the engine will use a `DefaultWebRequest`
+ * instance by default, which might be sufficient.
+ * @param The `WebRequest` instance to use.
+ */
void SetWebRequest(WebRequestPtr val);
+
+ /**
+ * @see `SetLogSystem()`.
+ */
LogSystemPtr GetLogSystem();
+
+ /**
+ * Sets the `LogSystem` implementation used for logging (e.g. to handle
+ * `console.log()` calls from JavaScript).
+ * Setting this is optional, the engine will use a `DefaultLogSystem`
+ * instance by default, which might be sufficient.
+ * @param The `LogSystem` instance to use.
+ */
void SetLogSystem(LogSystemPtr val);
private:
Index: include/AdblockPlus/JsValue.h
===================================================================
--- a/include/AdblockPlus/JsValue.h
+++ b/include/AdblockPlus/JsValue.h
@@ -35,10 +35,22 @@
class JsValue;
class JsEngine;
- typedef std::tr1::shared_ptr JsValuePtr;
- typedef std::vector JsValueList;
typedef std::tr1::shared_ptr JsEnginePtr;
+ /**
+ * Shared smart pointer to a `JsValue` instance.
+ */
+ typedef std::tr1::shared_ptr JsValuePtr;
+
+ /**
+ * List of JavaScript values.
+ */
+ typedef std::vector JsValueList;
+
+ /**
+ * Wrapper for JavaScript values.
+ * See `JsEngine` for creating `JsValue` objects.
+ */
class JsValue
{
friend class JsEngine;
@@ -58,8 +70,27 @@
int64_t AsInt() const;
bool AsBool() const;
JsValueList AsList() const;
+
+ /**
+ * Returns a list of property names if this is an object (see `IsObject()`).
+ * @return List of property names.
+ */
std::vector GetOwnPropertyNames() const;
+
+ /**
+ * Returns a property value if this is an object (see `IsObject()`).
+ * @param name Property name.
+ * @return Property value, undefined (see `IsUndefined()`) if the property
+ * does not exist.
+ */
JsValuePtr GetProperty(const std::string& name) const;
+
+ //@{
+ /**
+ * Sets a property value if this is an object (see `IsObject()`).
+ * @param name Property name.
+ * @param val Property value.
+ */
void SetProperty(const std::string& name, const std::string& val);
void SetProperty(const std::string& name, int64_t val);
void SetProperty(const std::string& name, bool val);
@@ -72,9 +103,26 @@
{
SetProperty(name, static_cast(val));
}
+ //@}
+
+ /**
+ * Returns the value's class name, e.g.\ _Array_ for arrays
+ * (see `IsArray()`).
+ * Technically, this is the name of the function that was used as a
+ * constructor.
+ * @return Class name of the value.
+ */
std::string GetClass() const;
+
+ /**
+ * Invokes the value as a function (see `IsFunction()`).
+ * @param params Optional list of parameters.
+ * @param thisPtr Optional `this` value.
+ * @return Value returned by the function.
+ */
JsValuePtr Call(const JsValueList& params = JsValueList(),
AdblockPlus::JsValuePtr thisPtr = AdblockPlus::JsValuePtr()) const;
+
protected:
JsValue(JsEnginePtr jsEngine, v8::Handle value);
void SetProperty(const std::string& name, v8::Handle val);
Index: include/AdblockPlus/LogSystem.h
===================================================================
--- a/include/AdblockPlus/LogSystem.h
+++ b/include/AdblockPlus/LogSystem.h
@@ -24,16 +24,33 @@
namespace AdblockPlus
{
+ /**
+ * Logging interface.
+ */
class LogSystem
{
public:
+ /**
+ * Log level.
+ */
enum LogLevel {LOG_LEVEL_TRACE, LOG_LEVEL_LOG, LOG_LEVEL_INFO, LOG_LEVEL_WARN, LOG_LEVEL_ERROR};
virtual ~LogSystem() {}
+
+ /**
+ * Writes a log message.
+ * @param logLevel Log level.
+ * @param message Log message.
+ * @param source Source of the message, e.g. file name and line.
+ * Ignored when empty.
+ */
virtual void operator()(LogLevel logLevel, const std::string& message,
const std::string& source) = 0;
};
+ /**
+ * Shared smart pointer to a `LogSystem` instance.
+ */
typedef std::tr1::shared_ptr LogSystemPtr;
}
Index: include/AdblockPlus/ReferrerMapping.h
===================================================================
--- a/include/AdblockPlus/ReferrerMapping.h
+++ b/include/AdblockPlus/ReferrerMapping.h
@@ -25,11 +25,36 @@
namespace AdblockPlus
{
+ /**
+ * Stores a mapping between URLs and their referrers.
+ * This can be used to build a chain of referrers for any URL
+ * (see `BuildReferrerChain()`), which approximates the frame structure, see
+ * FilterEngine::Matches().
+ */
class ReferrerMapping
{
public:
+ /**
+ * Constructor.
+ * @param maxCachedUrls Number of URL mappings to store. The higher the
+ * better - clients typically cache requests, and a single cached
+ * request will break the referrer chain.
+ */
ReferrerMapping(const int maxCachedUrls = 5000);
+
+ /**
+ * Records the refferer for a URL.
+ * @param url Request URL.
+ * @param referrer Request referrer.
+ */
void Add(const std::string& url, const std::string& referrer);
+
+ /**
+ * Builds a chain of referrers for the supplied URL.
+ * This should reconstruct a document's parent frame URLs.
+ * @param url URL to build the chain for.
+ * @return List of URLs, starting with `url`.
+ */
std::vector BuildReferrerChain(const std::string& url) const;
private:
Index: include/AdblockPlus/WebRequest.h
===================================================================
--- a/include/AdblockPlus/WebRequest.h
+++ b/include/AdblockPlus/WebRequest.h
@@ -26,23 +26,55 @@
namespace AdblockPlus
{
+ /**
+ * List of HTTP headers.
+ */
typedef std::vector > HeaderList;
+ /**
+ * HTTP response.
+ */
struct ServerResponse
{
+ //@{
+ /**
+ * [Mozilla status code](https://developer.mozilla.org/en/docs/Table_Of_Errors#Network_Errors)
+ * indicating the network-level request status.
+ * This should be 0 (NS_OK) if the request succeeded. Note that this should
+ * be NS_OK if the server responded with an error code like "404 Not Found".
+ */
#ifdef _WIN32
__int64 status;
#else
int64_t status;
#endif
+ //@}
+
+ /**
+ * List of response headers.
+ */
HeaderList responseHeaders;
+
+ /**
+ * HTTP status of the response (e.g.\ 404).
+ */
int responseStatus;
+
+ /**
+ * Body text of the response.
+ */
std::string responseText;
};
+ /**
+ * Web request interface.
+ */
class WebRequest
{
public:
+ /**
+ * Possible [Mozilla status codes](https://developer.mozilla.org/en/docs/Table_Of_Errors#Network_Errors).
+ */
enum
{
NS_OK = 0,
@@ -64,9 +96,19 @@
};
virtual inline ~WebRequest() {};
+
+ /**
+ * Performs a GET request.
+ * @param url Request URL.
+ * @param requestHeaders Request headers.
+ * @return HTTP response.
+ */
virtual ServerResponse GET(const std::string& url, const HeaderList& requestHeaders) const = 0;
};
+ /**
+ * Shared smart pointer to a `WebRequest` instance.
+ */
typedef std::tr1::shared_ptr WebRequestPtr;
}