Filter Rules

In their default state, the CBFS Filter classs ignore all operations; applications must explicitly specify which operations they're interested in by adding one or more filter rules. This "opt-in" approach prevents applications from being overwhelmed by the constant flood of operations occurring on a system at all times.

At a high level, there are two basic categories of filter rules: standard filter rules, which the classs use to determine which operations they should (or should not) fire events for; and special filter rules, which alter or augment the classs' behavior in a variety of ways. The sections below discuss each category of filter rules in more detail, and provide class-specific information where applicable.

Standard Filter Rules

Standard filter rules are typically an integral part of a CBFS Filter-based application's design. There may be thousands of operations occurring on a system at any given moment, and rarely are applications interested in more than a small subset of them. To start receiving events for those "interesting" operations, applications must add one or more standard filter rules so that the CBFS Filter driver knows which operations it needs to monitor.

For the CBFilter, CBMonitor, and CBRegistry classs, standard filter rules always contain two key pieces of information:

1. A mask that determines which files or registry keys the filter matches (or, "covers"). The CBFilter and CBMonitor classes use File Masks, while the CBRegistry class uses Registry Key Masks.
   • For CBFilter and CBMonitor, standard filter rules can also include additional qualifiers like file size, attributes, etc.; but the mask always takes precedence.
2. A set of flags that specifies what kinds of filesystem/registry operations the class should fire events for.

Together, this pair of parameters gives applications great flexibility, allowing them to create filter rules that are as broad or as narrow in scope as desired. For example, one application might wish to monitor any and all operations performed on files or registry keys whose name contains a specific word; while another application might only care about read operations performed on audio files in a specific directory, or on values of a specific registry key.

The CBFilter, CBMonitor, and CBRegistry classs provide the following methods for managing standard filter rules:

• AddFilterRule
• AddFilterRuleEx (CBFilter and CBMonitor only)
• DeleteFilterRule
• DeleteAllFilterRules

For the CBProcess class, whose design is far less complex than the other classs', standard filter rules are much simpler. Applications specify which processes they wish to monitor and ignore by name and/or PID using the following methods:

• AddFilteredProcessByName and RemoveFilteredProcessByName
• AddFilteredProcessById and RemoveFilteredProcessById
• AddIgnoredProcessByName and RemoveIgnoredProcessByName
• AddIgnoredProcessById and RemoveIgnoredProcessById

For all classs, standard filter rules are deactivated and deleted when the application exits.

Special Filter Rules

In addition to standard filter rules, the CBFilter, CBMonitor, and CBRegistry classs also support special filter rules. Unlike standard filter rules, special filter rules determine when a class should do something other than fire its events. There are multiple types of special filter rules, each of which alters (or augments) a class's behavior in a different way.

The following table provides links to topics with more information about each type of special filter rule, as well as information about which types are supported by each class. Note that the CBProcess class does not support any special filter rules.

Rulesets

All rules, regardless of their type, are stored in some sort of ruleset; and within a ruleset, rules are uniquely identified by their masks. Adding multiple rules with the same mask to a particular ruleset will result in a single, aggregate rule. Knowledge of this behavior is helpful for understanding how to use the methods that add and delete rules.

The number of rulesets each class has depends on its complexity. The most complex class, CBFilter, has four rulesets:

• One for standard filter rules and access rules (please refer to the Access Rules topic for more information on how this works).
• One for default rules.
• One for passthrough rules.
• One for reparse rules.