libadblockplus
 All Classes Namespaces Functions Variables Typedefs Enumerations Pages
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
AdblockPlus::FilterEngine Class Reference

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

JsEngineGetJsEngine () 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< FilterGetListedFilters () const
 Retrieves the list of custom filters. More...
 
std::vector< SubscriptionGetListedSubscriptions () const
 Retrieves all subscriptions. More...
 
std::vector< SubscriptionFetchAvailableSubscriptions () 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:

Member Typedef Documentation

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.

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
v1First version string.
v2Second 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
contentTypeContentType value.
Returns
The string representation of contentType.
Exceptions
<tt>std::invalid_argument</tt>,ifan invalid contentType was supplied.
static void AdblockPlus::FilterEngine::CreateAsync ( const JsEnginePtr jsEngine,
const OnCreatedCallback onCreated,
const CreationParameters parameters = CreationParameters() 
)
static

Asynchronously constructs FilterEngine.

Parameters
jsEngineJsEngine instance used to run JavaScript code internally.
onCreatedA callback which is called when FilterEngine is ready for use.
parametersoptional 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
callbackOptional 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
domainDomain 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
textText 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
urlURL 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
prefPreference 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
urlSubscription 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
urlURL of the document.
documentUrlsChain 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
urlURL of the document.
documentUrlsChain 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
urlURL to match.
contentTypeMaskContent type mask of the requested resource.
documentUrlURL 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>,ifan 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
urlURL to match.
contentTypeMaskContent type mask of the requested resource.
documentUrlsChain 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>,ifan 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
valueStored 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
callbackCallback to invoke.
void AdblockPlus::FilterEngine::SetPref ( const std::string &  pref,
const JsValue value 
)

Sets a preference value.

Parameters
prefPreference name.
valueNew value of the preference.
void AdblockPlus::FilterEngine::SetShowNotificationCallback ( const ShowNotificationCallback value)

Sets the callback invoked when a notification should be shown.

Parameters
callbackCallback to invoke.
void AdblockPlus::FilterEngine::SetUpdateAvailableCallback ( const UpdateAvailableCallback callback)

Sets the callback invoked when an application update becomes available.

Parameters
callbackCallback 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
urlURL to match notifications to (optional).
static ContentType AdblockPlus::FilterEngine::StringToContentType ( const std::string &  contentType)
static

Retrieves the ContentType for the supplied string.

Parameters
contentTypeContent type string.
Returns
The ContentType for the string.
Exceptions
<tt>std::invalid_argument</tt>,ifan invalid contentType was supplied.

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