Main component of libadblockplus. More...

#include <FilterEngine.h>

Classes
struct	CreationParameters
	FilterEngine creation parameters. More...

Public Types
enum	ContentType { CONTENT_TYPE_OTHER = 1, CONTENT_TYPE_SCRIPT = 2, CONTENT_TYPE_IMAGE = 4, CONTENT_TYPE_STYLESHEET = 8, CONTENT_TYPE_OBJECT = 16, CONTENT_TYPE_SUBDOCUMENT = 32, CONTENT_TYPE_DOCUMENT = 64, CONTENT_TYPE_WEBSOCKET = 128, CONTENT_TYPE_WEBRTC = 256, CONTENT_TYPE_PING = 1024, CONTENT_TYPE_XMLHTTPREQUEST = 2048, CONTENT_TYPE_OBJECT_SUBREQUEST = 4096, CONTENT_TYPE_MEDIA = 16384, CONTENT_TYPE_FONT = 32768, CONTENT_TYPE_GENERICBLOCK = 0x20000000, CONTENT_TYPE_ELEMHIDE = 0x40000000, CONTENT_TYPE_GENERICHIDE = 0x80000000 }
	Possible resource content types.

typedef int32_t	ContentTypeMask
	Bitmask of `ContentType` values. More...

typedef std::function< void(const std::string &)>	UpdateAvailableCallback
	Callback type invoked when an update becomes available. More...

typedef std::function< void(const std::string &)>	UpdateCheckDoneCallback
	Callback type invoked when a manually triggered update check finishes. More...

typedef std::function< void(const std::string &, JsValue &&)>	FilterChangeCallback
	Callback type invoked when the filters change. More...

typedef std::map< std::string, AdblockPlus::JsValue >	Prefs
	Container of name-value pairs representing a set of preferences.

typedef std::function< void(Notification &&)>	ShowNotificationCallback
	Callback type invoked when a new notification should be shown. More...

typedef std::function< void(const std::string *allowedConnectionType, const std::function< void(bool)> &)>	IsConnectionAllowedAsyncCallback
	Asynchronous callback function passing false when current connection type does not correspond to allowedConnectionType, e.g. More...

typedef std::function< void(const FilterEnginePtr &)>	OnCreatedCallback
	Callback type invoked when FilterEngine is created.

Public Member Functions
JsEngine &	GetJsEngine () const
	Retrieves the `JsEngine` instance associated with this `FilterEngine` instance.

bool	IsFirstRun () const
	Checks if this is the first run of the application. More...

Filter	GetFilter (const std::string &text) const
	Retrieves a filter object from its text representation. More...

Subscription	GetSubscription (const std::string &url) const
	Retrieves a subscription object for the supplied URL. More...

std::vector< Filter >	GetListedFilters () const
	Retrieves the list of custom filters. More...

std::vector< Subscription >	GetListedSubscriptions () const
	Retrieves all subscriptions. More...

std::vector< Subscription >	FetchAvailableSubscriptions () const
	Retrieves all recommended subscriptions. More...

void	SetAAEnabled (bool enabled)
	Ensures that the Acceptable Ads subscription is enabled or disabled. More...

bool	IsAAEnabled () const
	Checks whether the Acceptable Ads subscription is enabled. More...

std::string	GetAAUrl () const
	Retrieves the URL of the Acceptable Ads subscription, what makes the URL available even if subscription is not added yet. More...

void	ShowNextNotification (const std::string &url=std::string()) const
	Invokes the listener set via SetNotificationAvailableCallback() with the next notification to be shown. More...

void	SetShowNotificationCallback (const ShowNotificationCallback &value)
	Sets the callback invoked when a notification should be shown. More...

void	RemoveShowNotificationCallback ()
	Removes the callback invoked when a notification should be shown.

FilterPtr	Matches (const std::string &url, ContentTypeMask contentTypeMask, const std::string &documentUrl) const
	Checks if any active filter matches the supplied URL. More...

FilterPtr	Matches (const std::string &url, ContentTypeMask contentTypeMask, const std::vector< std::string > &documentUrls) const
	Checks if any active filter matches the supplied URL. More...

bool	IsDocumentWhitelisted (const std::string &url, const std::vector< std::string > &documentUrls) const
	Checks whether the document at the supplied URL is whitelisted. More...

bool	IsElemhideWhitelisted (const std::string &url, const std::vector< std::string > &documentUrls) const
	Checks whether element hiding is disabled at the supplied URL. More...

std::vector< std::string >	GetElementHidingSelectors (const std::string &domain) const
	Retrieves CSS selectors for all element hiding filters active on the supplied domain. More...

JsValue	GetPref (const std::string &pref) const
	Retrieves a preference value. More...

void	SetPref (const std::string &pref, const JsValue &value)
	Sets a preference value. More...

std::string	GetHostFromURL (const std::string &url) const
	Extracts the host from a URL. More...

void	SetUpdateAvailableCallback (const UpdateAvailableCallback &callback)
	Sets the callback invoked when an application update becomes available. More...

void	RemoveUpdateAvailableCallback ()
	Removes the callback invoked when an application update becomes available.

void	ForceUpdateCheck (const UpdateCheckDoneCallback &callback=UpdateCheckDoneCallback())
	Forces an immediate update check. More...

void	SetFilterChangeCallback (const FilterChangeCallback &callback)
	Sets the callback invoked when the filters change. More...

void	RemoveFilterChangeCallback ()
	Removes the callback invoked when the filters change.

void	SetAllowedConnectionType (const std::string *value)
	Stores the value indicating what connection types are allowed, it is passed to CreateParameters::isConnectionAllowed callback. More...

std::unique_ptr< std::string >	GetAllowedConnectionType () const
	Retrieves previously stored allowed connection type. More...

int	CompareVersions (const std::string &v1, const std::string &v2) const
	Compares two version strings in Mozilla toolkit version format. More...

Static Public Member Functions
static void	CreateAsync (const JsEnginePtr &jsEngine, const OnCreatedCallback &onCreated, const CreationParameters &parameters=CreationParameters())
	Asynchronously constructs FilterEngine. More...

static ContentType	StringToContentType (const std::string &contentType)
	Retrieves the `ContentType` for the supplied string. More...

static std::string	ContentTypeToString (ContentType contentType)
	Retrieves the string representation of the supplied `ContentType`. More...

Detailed Description

Main component of libadblockplus.

It handles:

Filter management and matching.
Subscription management and synchronization.
Update checks for the application.

Member Typedef Documentation

typedef int32_t AdblockPlus::FilterEngine::ContentTypeMask

Bitmask of ContentType values.

The underlying type is signed 32 bit integer because it is actually used in JavaScript where it is converted into 32 bit signed integer.

typedef std::function<void(const std::string&, JsValue&&)> AdblockPlus::FilterEngine::FilterChangeCallback

Callback type invoked when the filters change.

The first parameter is the action event code (see FilterNotifier.triggerListeners for the full list). The second parameter is the filter/subscription object affected, if any.

typedef std::function<void(const std::string* allowedConnectionType, const std::function<void(bool)>&)> AdblockPlus::FilterEngine::IsConnectionAllowedAsyncCallback

Asynchronous callback function passing false when current connection type does not correspond to allowedConnectionType, e.g.

because it is a metered connection.

typedef std::function<void(Notification&&)> AdblockPlus::FilterEngine::ShowNotificationCallback

Callback type invoked when a new notification should be shown.

The parameter is the Notification object to be shown.

typedef std::function<void(const std::string&)> AdblockPlus::FilterEngine::UpdateAvailableCallback

Callback type invoked when an update becomes available.

The parameter is the download URL of the update.

typedef std::function<void(const std::string&)> AdblockPlus::FilterEngine::UpdateCheckDoneCallback

Callback type invoked when a manually triggered update check finishes.

The parameter is an optional error message.

Member Function Documentation

int AdblockPlus::FilterEngine::CompareVersions	(	const std::string &	v1,
		const std::string &	v2
	)		const

Compares two version strings in Mozilla toolkit version format.

Parameters

v1	First version string.
v2	Second version string.

Returns

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.

static std::string AdblockPlus::FilterEngine::ContentTypeToString ( ContentType contentType )

static

Retrieves the string representation of the supplied ContentType.

Parameters

contentType ContentType value.

Returns: The string representation of contentType.

Exceptions

<tt>std::invalid_argument</tt>,if an invalid contentType was supplied.

static void AdblockPlus::FilterEngine::CreateAsync	(	const JsEnginePtr &	jsEngine,
		const OnCreatedCallback &	onCreated,
		const CreationParameters &	parameters = `CreationParameters()`
	)

static

Asynchronously constructs FilterEngine.

Parameters

jsEngine	`JsEngine` instance used to run JavaScript code internally.
onCreated	A callback which is called when FilterEngine is ready for use.
parameters	optional creation parameters.

std::vector<Subscription> AdblockPlus::FilterEngine::FetchAvailableSubscriptions ( ) const

Retrieves all recommended subscriptions.

Returns: List of recommended subscriptions.

void AdblockPlus::FilterEngine::ForceUpdateCheck ( const UpdateCheckDoneCallback & callback = UpdateCheckDoneCallback() )

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.

Parameters

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 whether updates are available or not - to react to updates being available, use FilterEngine::SetUpdateAvailableCallback().

std::string AdblockPlus::FilterEngine::GetAAUrl ( ) const

Retrieves the URL of the Acceptable Ads subscription, what makes the URL available even if subscription is not added yet.

Returns: Returns URL of the Acceptable Ads.

std::unique_ptr<std::string> AdblockPlus::FilterEngine::GetAllowedConnectionType ( ) const

Retrieves previously stored allowed connection type.

Returns: Preference value, or nullptr if it doesn't exist.

std::vector<std::string> AdblockPlus::FilterEngine::GetElementHidingSelectors ( const std::string & domain ) const

Retrieves CSS selectors for all element hiding filters active on the supplied domain.

Parameters

domain Domain to retrieve CSS selectors for.

Returns: List of CSS selectors.

Filter AdblockPlus::FilterEngine::GetFilter ( const std::string & text ) const

Retrieves a filter object from its text representation.

Parameters

text	Text representation of the filter, see https://adblockplus.org/en/filters.

Returns: New Filter instance.

std::string AdblockPlus::FilterEngine::GetHostFromURL ( const std::string & url ) const

Extracts the host from a URL.

Parameters

url	URL to extract the host from.

Returns: Extracted host.

std::vector<Filter> AdblockPlus::FilterEngine::GetListedFilters ( ) const

Retrieves the list of custom filters.

Returns: List of custom filters.

std::vector<Subscription> AdblockPlus::FilterEngine::GetListedSubscriptions ( ) const

Retrieves all subscriptions.

Returns: List of subscriptions.

JsValue AdblockPlus::FilterEngine::GetPref ( const std::string & pref ) const

Retrieves a preference value.

Parameters

pref	Preference name.

Returns: Preference value, or null if it doesn't exist.

Subscription AdblockPlus::FilterEngine::GetSubscription ( const std::string & url ) const

Retrieves a subscription object for the supplied URL.

Parameters

url	Subscription URL.

Returns: New Subscription instance.

bool AdblockPlus::FilterEngine::IsAAEnabled ( ) const

Checks whether the Acceptable Ads subscription is enabled.

Returns: true if the Acceptable Ads subscription is present and enabled.

bool AdblockPlus::FilterEngine::IsDocumentWhitelisted	(	const std::string &	url,
		const std::vector< std::string > &	documentUrls
	)		const

Checks whether the document at the supplied URL is whitelisted.

Parameters

url	URL of the document.
documentUrls	Chain of document URLs requesting the document, starting with the current document'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`.

Returns: true if the URL is whitelisted.

bool AdblockPlus::FilterEngine::IsElemhideWhitelisted	(	const std::string &	url,
		const std::vector< std::string > &	documentUrls
	)		const

Checks whether element hiding is disabled at the supplied URL.

Parameters

url	URL of the document.
documentUrls	Chain of document URLs requesting the document, starting with the current document'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`.

Returns: true if element hiding is whitelisted for the supplied URL.

bool AdblockPlus::FilterEngine::IsFirstRun ( ) const

Checks if this is the first run of the application.

Returns: true if the application is running for the first time.

FilterPtr AdblockPlus::FilterEngine::Matches	(	const std::string &	url,
		ContentTypeMask	contentTypeMask,
		const std::string &	documentUrl
	)		const

Checks if any active filter matches the supplied URL.

Parameters

url	URL to match.
contentTypeMask	Content type mask of the requested resource.
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.

Returns: Matching filter, or null if there was no match.

Exceptions

<tt>std::invalid_argument</tt>,if an invalid contentType was supplied.

FilterPtr AdblockPlus::FilterEngine::Matches	(	const std::string &	url,
		ContentTypeMask	contentTypeMask,
		const std::vector< std::string > &	documentUrls
	)		const

Checks if any active filter matches the supplied URL.

Parameters

url	URL to match.
contentTypeMask	Content type mask of the requested resource.
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`.

Returns: Matching filter, or a null if there was no match.

Exceptions

<tt>std::invalid_argument</tt>,if an invalid contentType was supplied.

void AdblockPlus::FilterEngine::SetAAEnabled ( bool enabled )

Ensures that the Acceptable Ads subscription is enabled or disabled.

Parameters

enabled

if the value is true
- ensure that the filter set includes an enabled AA subscription, adding it if needed and enabling it if disabled.
if the value is false
- if an AA subscription is present, disable it.
- if absent, do nothing.

void AdblockPlus::FilterEngine::SetAllowedConnectionType ( const std::string * value )

Stores the value indicating what connection types are allowed, it is passed to CreateParameters::isConnectionAllowed callback.

Parameters

value Stored value. nullptr means removing of any previously stored value.

void AdblockPlus::FilterEngine::SetFilterChangeCallback ( const FilterChangeCallback & callback )

Sets the callback invoked when the filters change.

Parameters

callback Callback to invoke.

void AdblockPlus::FilterEngine::SetPref	(	const std::string &	pref,
		const JsValue &	value
	)

Sets a preference value.

Parameters

pref	Preference name.
value	New value of the preference.

void AdblockPlus::FilterEngine::SetShowNotificationCallback ( const ShowNotificationCallback & value )

Sets the callback invoked when a notification should be shown.

Parameters

callback Callback to invoke.

void AdblockPlus::FilterEngine::SetUpdateAvailableCallback ( const UpdateAvailableCallback & callback )

Sets the callback invoked when an application update becomes available.

Parameters

callback Callback to invoke.

void AdblockPlus::FilterEngine::ShowNextNotification ( const std::string & url = std::string() ) const

Invokes the listener set via SetNotificationAvailableCallback() with the next notification to be shown.

Parameters

url	URL to match notifications to (optional).

static ContentType AdblockPlus::FilterEngine::StringToContentType ( const std::string & contentType )

static

Retrieves the ContentType for the supplied string.

Parameters

contentType Content type string.

Returns: The ContentType for the string.

Exceptions

<tt>std::invalid_argument</tt>,if an invalid contentType was supplied.

The documentation for this class was generated from the following file:

include/AdblockPlus/FilterEngine.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Function Documentation