CBFilter Class
Properties Methods Events Configuration Settings Errors
The CBFilter class allows applications to intercept and control filesystem requests.
Syntax
class cbfsfilter.CBFilter
Remarks
The CBFilter class gives applications the ability to intercept filesystem requests, allowing them to be altered, handled, blocked, etc. Applications use standard filter rules to specify which requests they're interested in intercepting; and special filter rules to enforce access restrictions and redirect requests to different files.
To learn more about the class's capabilities, please refer to the product's General Information topics.
Getting Started
- If the class's system driver hasn't been installed yet, call the install method to do so. This only needs to be done once.
- In production, the driver can be installed (or updated) ahead-of-time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
- Call the initialize method to initialize the CBFilter class. This must be done each time the application starts.
- Add one or more filter rules using methods like add_filter_rule. (Rules can also be added/removed after the filter is started.)
- Call the start_filter method to start filtering filesystem requests.
- When finished, call the stop_filter method to stop filtering filesystem requests.
- To uninstall the class's system driver, call the uninstall method. This should not be done as part of the driver upgrade process.
- In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| active | Whether the class is active and processing requests. |
| altitude | The altitude the class's system driver should use when operating in minifilter mode. |
| default_rule_count | The number of records in the DefaultRule arrays. |
| default_rule_access_flags | The access restrictions enforced by the rule. |
| default_rule_mask | A file mask that determines which files and directories match the rule. |
| file_flushing_behavior | The file flushing and closing behavior that the class's system driver should enforce. |
| filter_mode | The filter mode the class's system driver should use. |
| filter_rule_count | The number of records in the FilterRule arrays. |
| filter_rule_access_flags | The access restrictions enforced by the rule (CBFilter only). |
| filter_rule_control_flags | Which control events the rule causes the class to fire (CBFilter only). |
| filter_rule_ea_name | The name of an extended attribute that a file or directory must have to match the rule. |
| filter_rule_excluded_attributes | The file attributes that a file or directory must not have to match the rule. |
| filter_rule_included_attributes | The file attributes that a file or directory must have to match the rule. |
| filter_rule_mask | A file mask that determines which files and directories match the rule. |
| filter_rule_max_size | The maximum size a file can be to match the rule. |
| filter_rule_min_size | The minimum size a file can be to match the rule. |
| filter_rule_notify_flags | Which notification events the rule causes the class to fire. |
| fire_volume_events | The events that should be fired when a filesystem volume is mounted to or unmounted from the system. |
| passthrough_rule_count | The number of records in the PassthroughRule arrays. |
| passthrough_rule_access_flags | The access restrictions lifted by the rule (CBFilter only). |
| passthrough_rule_control_flags | Which control events the rule prevents the class from firing (CBFilter only). |
| passthrough_rule_ea_name | The name of an extended attribute that a file or directory must have to match the rule. |
| passthrough_rule_excluded_attributes | The file attributes that a file or directory must not have to match the rule. |
| passthrough_rule_included_attributes | The file attributes that a file or directory must have to match the rule. |
| passthrough_rule_mask | A file mask that determines which files and directories match the rule. |
| passthrough_rule_max_size | The maximum size a file can be to match the rule. |
| passthrough_rule_min_size | The minimum size a file can be to match the rule. |
| passthrough_rule_notify_flags | Which notification events the rule prevents the class from firing. |
| process_cached_io_requests | Whether cached file read/write requests should be processed. |
| process_failed_requests | Whether failed requests should be processed. |
| reparse_rule_count | The number of records in the ReparseRule arrays. |
| reparse_rule_mask | A file mask that determines which files and directories match the rule. |
| reparse_rule_reparse_mask | A file mask that specifies where matching files and directories are redirected to. |
| serialize_events | Whether events should be fired on a single worker thread, or many. |
| tag | Stores application-defined data specific to this instance of the class. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| add_bytes_to_write_buffer | Reserves extra space in the file data buffers used in file read/write events. |
| add_default_rule | Adds a default rule. |
| add_filter_rule | Adds a standard filter rule or access rule. |
| add_filter_rule_ex | Adds a standard filter rule or access rule with additional match qualifiers. |
| add_passthrough_rule | Adds a passthrough rule. |
| add_passthrough_rule_ex | Adds a passthrough rule with additional match qualifiers. |
| add_reparse_rule | Adds a reparse rule. |
| close_default_rules_snapshot | Closes the previously-created default rules snapshot. |
| close_reparse_rules_snapshot | Closes the previously-created reparse rules snapshot. |
| config | Sets or retrieves a configuration setting. |
| create_default_rules_snapshot | Creates a snapshot of information about the default rules that have been added. |
| create_file_direct | Creates or opens a file or directory by passing the request directly to the filesystem. |
| create_file_direct_as_stream | Creates or opens a file by passing the request directly to the filesystem. |
| create_reparse_rules_snapshot | Creates a snapshot of information about the reparse rules that have been added. |
| create_virtual_file | This method is under construction. |
| delete_all_filter_rules | Deletes all standard filter rules and access rules. |
| delete_all_passthrough_rules | Deletes all passthrough rules. |
| delete_all_reparse_rules | Deletes all reparse rules. |
| delete_default_rule | Deletes a particular default rule. |
| delete_filter_rule | Deletes a particular standard filter rule or access rule. |
| delete_passthrough_rule | Deletes a particular passthrough rule. |
| delete_reparse_rule | Deletes a particular reparse rule. |
| file_matches_mask | Checks whether a particular file or directory name matches the specified mask. |
| flush_notification_queue | Flushes the notification event queue. |
| get_driver_status | Retrieves the status of the class's system driver. |
| get_driver_version | Retrieves the version of the class's system driver. |
| get_handle_creator_process_id | Retrieves the Id of the process (PID) that opened the file handle. |
| get_handle_creator_process_name | Retrieves the name of the process that opened the file handle. |
| get_handle_creator_thread_id | Retrieves the Id of the thread that opened the file handle. |
| get_handle_creator_token | Retrieves the security token associated with the process that opened the file handle. |
| get_originator_process_id | Retrieves the Id of the process (PID) that initiated the operation. |
| get_originator_process_name | Retrieves the name of the process that initiated the operation. |
| get_originator_thread_id | Retrieves the Id of the thread that initiated the operation. |
| get_originator_token | Retrieves the security token associated with the process that initiated the operation. |
| get_reparse_rule_by_mask | Retrieves the reparse rule associated with the specified file mask. |
| get_volume_guid | Retrieves the volume GUID of the device targeted by a filesystem operation. |
| initialize | Initializes the class. |
| install | Installs (or upgrades) the class's system driver. |
| is_file_filtered | Checks whether a particular file or directory is covered by any filter rules. |
| nt_status_to_win_32_error | Converts a native status code to a Win32 error code. |
| reset_timeout | Resets the timeout duration for the current event handler. |
| set_file_size_direct | Resizes a file by passing the request directly to the filesystem. |
| shutdown_system | Shuts down or reboots the operating system. |
| start_filter | Start filtering filesystem operations. |
| stop_filter | Stop filtering filesystem operations. |
| suspend_default_rules | Suspends all default rules until the application exits. |
| suspend_file_events | Suspends all events for a particular file or directory until all of its handles have been closed. |
| toggle_process_protection | Enables or disables termination protection for the application. |
| uninstall | Uninstalls the class's system driver. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
| on_after_can_file_be_deleted | Fires after the OS marks a file or directory for deletion or removes such a mark. |
| on_after_cleanup_file | Fires after a file or directory handle is closed. |
| on_after_close_enumeration | Fires after a directory enumeration operation finishes. |
| on_after_close_file | Fires after a file or directory is closed. |
| on_after_create_file | Fires after a file or directory is created. |
| on_after_create_hard_link | Fires after a hard link is created. |
| on_after_delete_file | Fires after a file or directory is deleted. |
| on_after_enumerate_directory | Fires after a directory entry is returned during directory enumeration. |
| on_after_filter_attach_to_volume | Fires after the filter attaches to a newly-mounted filesystem volume. |
| on_after_filter_detach_from_volume | Fires after the filter detaches from a filesystem volume. |
| on_after_fsctl | Fires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed. |
| on_after_get_file_security | Fires after a file or directory's security attributes are retrieved. |
| on_after_get_file_sizes | Fires after a file's size information is retrieved. |
| on_after_ioctl | Fires after an IRP_MJ_DEVICE_CONTROL request is processed. |
| on_after_lock | Fires after a range of bytes in a file is locked. |
| on_after_open_file | Fires after a file or directory is opened. |
| on_after_query_file_info | Fires after information about a file or directory is retrieved. |
| on_after_read_file | Fires after data is read from a file. |
| on_after_rename_or_move_file | Fires after a file or directory is renamed or moved. |
| on_after_set_allocation_size | Fires after a file's allocation size is changed. |
| on_after_set_file_attributes | Fires after a file or directory's attributes and/or times are changed. |
| on_after_set_file_info | Fires after information about a file or directory is changed. |
| on_after_set_file_security | Fires after a file or directory's security attributes are changed. |
| on_after_set_file_size | Fires after a file is resized. |
| on_after_unlock_all | Fires after all locked byte ranges in a file are unlocked. |
| on_after_unlock_all_by_key | Fires after all locked byte ranges in a file, associated with a particular key, are unlocked. |
| on_after_unlock_single | Fires after a particular locked byte range in a file is unlocked. |
| on_after_write_file | Fires after data is written to a file. |
| on_before_can_file_be_deleted | Fires before the OS attempts to mark a file or directory for deletion or remove such a mark. |
| on_before_cleanup_file | Fires before a file or directory handle is closed. |
| on_before_close_file | Fires before a file or directory is closed. |
| on_before_create_file | Fires before a file or directory is created. |
| on_before_create_hard_link | Fires before a hard link is created. |
| on_before_delete_file | Fires before a file or directory is deleted. |
| on_before_filter_attach_to_volume | Fires before the filter attaches to a newly-mounted filesystem volume. |
| on_before_fsctl | Fires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed. |
| on_before_get_file_security | Fires before a file or directory's security attributes are retrieved. |
| on_before_ioctl | Fires before an IRP_MJ_DEVICE_CONTROL request is processed. |
| on_before_lock | Fires before a range of bytes in a file is locked. |
| on_before_open_file | Fires before a file or directory is opened. |
| on_before_query_file_info | Fires before information about a file or directory is retrieved. |
| on_before_read_file | Fires before data is read from a file. |
| on_before_rename_or_move_file | Fires before a file or directory is renamed or moved. |
| on_before_set_allocation_size | Fires before a file's allocation size is changed. |
| on_before_set_file_attributes | Fires before a file or directory's attributes and/or times are changed. |
| on_before_set_file_info | Fires before information about a file or directory is changed. |
| on_before_set_file_security | Fires before a file or directory's security attributes are changed. |
| on_before_set_file_size | Fires before a file is resized. |
| on_before_unlock_all | Fires before all locked byte ranges in a file are unlocked. |
| on_before_unlock_all_by_key | Fires before all locked byte ranges in a file, associated with a particular key, are unlocked. |
| on_before_unlock_single | Fires before a particular locked byte range in a file is unlocked. |
| on_before_write_file | Fires before data is written to a file. |
| on_cleanup_context | Fires when the application-defined data stored in one or more contexts needs to be cleaned up. |
| on_delete_virtual_file | Fires when a virtual file needs to be deleted. |
| on_error | Fires if an unhandled error occurs during an event. |
| on_filter_start | Fires once the filter has attached and filtering has started. |
| on_filter_stop | Fires once filtering has stopped and the filter has detached. |
| on_notify_can_file_be_deleted | Fires when the OS marks a file or directory for deletion or removes such a mark. |
| on_notify_cleanup_file | Fires when a file or directory handle has been closed. |
| on_notify_close_file | Fires when a file or directory has been closed. |
| on_notify_create_file | Fires when a file or directory has been created. |
| on_notify_create_hard_link | Fires when a hard link has been created. |
| on_notify_delete_file | Fires when a file or directory has been deleted. |
| on_notify_enumerate_directory | Fires when a directory entry has been returned during directory enumeration. |
| on_notify_filter_attach_to_volume | Fires when the filter has been attached to a newly-mounted filesystem volume. |
| on_notify_filter_detach_from_volume | Fires when the filter has been detached from a filesystem volume. |
| on_notify_fsctl | Fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred. |
| on_notify_get_file_security | Fires when a file or directory's security attributes have been retrieved. |
| on_notify_get_file_sizes | Fires when a file's size information has been retrieved. |
| on_notify_ioctl | Fires when an IRP_MJ_DEVICE_CONTROL operation has occurred. |
| on_notify_lock | Fires when a range of bytes in a file has been locked. |
| on_notify_open_file | Fires when a file or directory has been opened. |
| on_notify_query_file_info | Fires when information about a file or directory has been retrieved. |
| on_notify_read_file | Fires when data has been read from a file. |
| on_notify_rename_or_move_file | Fires when a file or directory has been renamed or moved. |
| on_notify_set_allocation_size | Fires when a file's allocation size has been changed. |
| on_notify_set_file_attributes | Fires when a file or directory's attributes and/or times have been changed. |
| on_notify_set_file_info | Fires when information about a file or directory has been changed. |
| on_notify_set_file_security | Fires when a file or directory's security attributes have been changed. |
| on_notify_set_file_size | Fires when a file has been resized. |
| on_notify_unlock_all | Fires when all locked byte ranges in a file have been unlocked. |
| on_notify_unlock_all_by_key | Fires when all locked byte ranges in a file, associated with a particular key, have been unlocked. |
| on_notify_unlock_single | Fires when a particular locked byte range in a file has been unlocked. |
| on_notify_write_file | Fires when data has been written to a file. |
| on_reparse_file_name | Fires to allow file access to be dynamically redirected another location. |
| on_reparse_with_tag | Fires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point. |
| on_worker_thread_creation | Fires just after a new worker thread is created. |
| on_worker_thread_termination | Fires just before a worker thread is terminated. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
| AllowFileAccessInBeforeOpen | Whether file access, via the CreateFileDirect method, is allowed in during the BeforeCreateFile and BeforeOpenFile events. |
| AlwaysPrepareFiles | Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the class is initialized. |
| CacheRemoteFilesLocally | Whether remote files involved in filtered operations should be cached locally rather than remotely. |
| DirectRequestsDownTheStack | Whether requests for handles created with the CreateFileDirect method go down the filter stack and not direct to the filesystem. |
| FilterOwnRequests | Whether the class's system driver should filter requests made by the application itself. |
| ForceAdminRightsForDefaultRules | Specifies whether default rules can be added or deleted only by administrators. |
| ForceAppPermissionCheck | Whether the driver should require the controller process to have elevated or system privileges. |
| ForceSecurityChecks | Whether the driver should prevent the controller process from filtering files that it would not normally have access to. |
| LoggingEnabled | Whether extended logging is enabled. |
| MaxWorkerThreadCount | The maximum number of worker threads to use to fire events. |
| MinWorkerThreadCount | The minimum number of worker threads to use to fire events. |
| ModifiableReadWriteBuffers | Whether the driver should duplicate read/write buffers sent to the user. |
| PreprocessedRulesCacheSize | Maximum number of preprocessed rules to keep cached. |
| ResolveNtDeviceToDriveLetter | Whether native device names are translated to drive letters. |
| SendRequestsViaDriverStack | Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers. |
| WorkerInitialStackSize | The initial stack size to create worker threads with. |
| BuildInfo | Information about the product's build. |
| LicenseInfo | Information about the current license. |