Class

NEFilterControlProvider

The principal class for a filter control provider app extension.

Declaration

class NEFilterControlProvider : NEFilterProvider

Overview

The Filter Control Provider’s primary responsibility is to provide information to the associated Filter Data Provider so that it can perform its task of accurately filtering network content. There are several ways in which the Filter Control Provider provides data to the associated Filter Data Provider:

  • By writing information to disk. For example, the Filter Control Provider can maintain a database of filtering rules on disk in a location where the Filter Data Provider can read from the database.

  • By defining a dictionary that maps keys to sets of customization parameters to be used when generating the block page. The Filter Data Provider gives the system the key for the desired customization parameters, and the system uses that key to get the customization parameters from the Filter Control Provider and generate the customized block page.

  • By defining a dictionary that maps keys to strings to be appended to URLs. The Filter Data Provider gives the system the key for the string to be appended, and the system uses that key to get the string to be appended from the Filter Control Provider and appends the string to the URL.

Creating a Filter Control Provider Extension

Filter Control Providers run as App Extensions for the com.apple.networkextension.filter-control extension point.

To create a Filter Control Provider extension, first create a new App Extension target in your project.

For an example of an Xcode build target for this app extension, see the SimpleTunnel: Customized Networking Using the NetworkExtension Framework sample code project.

Once you have a Filter Control Provider extension target, create a sub-class of NEFilterControlProvider. Then, set the NSExtensionPrincipalClass key in the the extension’s Info.plist to the name of your subclass.

If it is not already, set the NSExtensionPointIdentifier key in the extension’s Info.plist to com.apple.networkextension.filter-control.

Here is an example of the NSExtension dictionary in a Filter Control Provider extension’s Info.plist:

<key>NSExtension</key>
<dict>
    <key>NSExtensionPointIdentifier</key>
    <string>com.apple.networkextension.filter-control</string>
    <key>NSExtensionPrincipalClass</key>
    <string>MyCustomFilterControlProvider</string>
</dict>

Finally, add your Filter Control Provider extension target to your app’s Embed App Extensions build phase.

Topics

Handling Requests for New Rules

func notifyRulesChanged()

Notify the Filter Data Provider that the filtering rules have changed on disk.

Handling Remediation

var remediationMap: [String : [String : NSObject]]?

A dictionary containing sets of strings used to customize the remediation portion of the block page.

let NEFilterProviderRemediationMapRemediationButtonTexts: String

A key in the remediationMap dictionary. The value of this key should be set to a dictionary that maps button text string identifiers to the text to display for the remediation URL link in the block page. The button text string identifiers are defined by the Filter Control Provider app extension.

let NEFilterProviderRemediationMapRemediationURLs: String

A key in the remediationMap dictionary. The value of this key should be set to a dictionary that maps URL identifiers to remediation URLs to be inserted into the block page. The URL identifiers are defined by the Filter Control Provider app extension.

var NEFilterProviderRemediationURLFlowURL: String

This string will be replaced with the full URL of the flow.

var NEFilterProviderRemediationURLFlowURLHostname: String

This string will be replaced with the hostname portion of the flow’s URL.

var NEFilterProviderRemediationURLOrganization: String

This string will be replaced with the value of the organization property set in the filter configuration.

var NEFilterProviderRemediationURLUsername: String

This string will be replaced with the value of the username property set in the filter configuration.

var urlAppendStringMap: [String : String]?

A dictionary containing strings to be appended to URLs.

Handling Flow Reports

func handle(NEFilterReport)

Handles a flow report issued when the data provider returns a verdict.

Relationships

Inherits From

Conforms To

See Also

Data and Control Providers

class NEFilterDataProvider

The principal class for a filter data provider app extension.