msAddTrackingProtectionList method

2017-08-15

Adds an external Tracking Protection list.

Syntax

*object.*msAddTrackingProtectionList(URL, bstrFilterName)

Parameters

URL [in]
Type: BSTR

The address of the Tracking Protection list.
bstrFilterName [in]
Type: BSTR

The display name.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

A Tracking Protection list is a specially formatted text file that contains the following elements, each on their own line.

Element	Description
msFilterList	File header. This exact keyword must appear by itself on the first line of the file.
# (hash)	Comment line. This character at the beginning of a line indicates a comment.
: (colon)	Property rule. The only property rule currently defined is "Expires=N" where N represents the number of days (max 30) to elapse before refreshing the Tracking Protection list from the server. If not specified, the default value is `7`.
- (hyphen)	Block rule. The block rule can filter strings or ___domain labels, or a combination of both, as follows: If the block character is followed by whitespace and a string, the rule blocks downloads of any resource that contains the string in its URL. If the block character is followed by `d`, whitespace, and a ___domain label, the rule blocks domains according to rules described in the Domain Labels section. If a block ___domain rule is followed by whitespace and a string, the ___domain request is blocked only if the URL contains the specified string.
+ (plus)	Allow rule. Only ___domain labels can be allowed. The allow rule follows the same syntax as the block rule for domains.

A Tracking Protection list requires at least one valid block or allow rule.

Domain Labels

A ___domain name consists of one or more parts, called labels, that are concatenated and delimited by dots, such as host.contoso.com. Domain rules match against each ___domain label, as follows:

A block ___domain rule matches any contiguous ___domain labels in a ___domain name, for example,contoso, host.contoso, or contoso.com.
An allow ___domain rule is less permissive than a block rule, and matches only the right-most characters of the URL, such as contoso.com.

Domain rules can also specify an optional substring to match. There can be only one substring per ___domain rule line. Strings can contain a wildcard (*) that matches any number of characters.

Examples

The following simple Tracking Protection list contains one blocked string and two ___domain rules. The allow ___domain rule is matched only if the URL also contains the string value of home. This list is refreshed from the server every five days.

msFilterList
: Expires = 5
# blocked strings
-    &keyword=
# ___domain rules
-d   blockDomain
+d   allowDomain.com  home

The following script demonstrates how to install the Tracking Protection list by clicking a button.

function installTrackingProtectionList()
{
    var myList = 'http://example.com/tracklist.tpl';
    var myTitle = 'Example Tracking Protection List';
    external.msAddTrackingProtectionList(myList, myTitle);
}

<button onclick="installTrackingProtectionList();">Install List</button>

Share via