Share via

msAddTrackingProtectionList method

  • Article

Adds an external Tracking Protection list.

This method is not supported for Windows apps using JavaScript.

 

Syntax

HRESULT retVal = 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.

Standards information

There are no standards that apply here.

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.

For more information and examples of valid Tracking Protection lists, see Web Tracking Protection section 4, List Format.

See also

IShellUIHelper4::msTrackingProtectionEnabled