CBFS Filter 2020 Python Edition

Questions / Feedback?

add_filter_rule_ex Method

Adds a standard filter rule with additional match qualifiers.

Syntax

def add_filter_rule_ex(mask: str, ea_name: str, notify_flags: int, min_size: int, max_size: int, included_attributes: int, excluded_attributes: int) -> bool: ...

Remarks

This method adds a standard filter rule for the files and directories that match the specified Mask (which must be provided), and other qualifiers (which are optional). Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

If the rule is added successfully, this method returns True; otherwise, it returns False.

Standard filter rules determine which filesystem operations, of those performed on matching files and directories, the class should fire its events for.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories which match the specified mask will be covered by the rule.

The EaName parameter specifies the name of an extended attribute that a file or directory must have in order to qualify as a match; wildcards are not allowed. Pass empty string if this parameter should not be used as a match qualifier.

The NotifyFlags parameter specifies which filesystem operations the class should fire Notification Events for. For example, if the FS_NE_READ flag is present, the on_notify_read_file event will fire after a read operation is performed on any file that matches Mask. The value passed for this parameter should be constructed by OR'ing together zero or more of the following flags:

FS_NE_NONE0Don't fire for any filesystem operations.

Notification Events will not fire for any filesystem operations.

FS_NE_CREATE0x00000001LFire for file creation operations.

The on_notify_create_file event will fire anytime the OS creates a file or directory. In some cases, can cause the on_notify_open_file event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

The on_notify_open_file event will fire anytime the OS opens a file or directory. In some cases, can cause the on_notify_create_file event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_READ0x00000004LFire for read operations.

The on_notify_read_file event will fire anytime the OS reads data from a file.

FS_NE_WRITE0x00000008LFire for write operations.

The on_notify_write_file event will fire anytime the OS write data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The on_notify_lock, on_notify_unlock_all, on_notify_unlock_all_by_key, and on_notify_unlock_single events will fire, as applicable, anytime the OS locks or unlocks a range of bytes in a file.

FS_NE_CLEANUP0x00000020LFire for file handle cleanup operations.

The on_notify_cleanup_file event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

The on_notify_close_file event will fire anytime the OS closes a file or directory.

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

The on_notify_can_file_be_deleted event will fire anytime the OS checks whether a file or directory can be deleted.

FS_NE_DELETE0x00000100LFire for delete operations.

The on_notify_delete_file event will fire anytime the OS deletes a file or directory.

FS_NE_RENAME0x00000200LFire for rename/move operations.

The on_notify_rename_or_move_file event will fire anytime the OS renames or moves a file or directory.

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

The on_notify_get_file_security event will fire anytime the OS queries the security attributes of a file or directory.

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

The on_notify_enumerate_directory event will fire anytime the OS retrieves a directory entry during directory enumeration.

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

The on_notify_query_file_info event will fire anytime the OS retrieves information about a file or directory.

FS_NE_GET_SIZES0x00002000LFire for get size operations.

The on_notify_get_file_sizes event will fire anytime the OS retrieves a file's size information.

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The on_notify_set_file_security event will fire anytime the OS changes the security attributes of a file or directory.

FS_NE_SET_ATTRIBUTES0x00008000LFire for file attribute update operations.

The on_notify_set_file_attributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

The on_notify_set_file_size event will fire anytime the OS resizes a file, and the on_notify_set_allocation_size event will fire anytime the OS changes a file's allocation size.

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

The on_notify_create_hard_link event will fire anytime the OS creates a hard link.

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The on_notify_fsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The on_notify_ioctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The on_notify_set_file_info event will fire anytime the OS changed information about a file or directory.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations.

The MinSize and MaxSize parameters specify the minimum and/or maximum size, in bytes, that a file can be to qualify as a match. Pass -1 for either parameter if it should not be used as a match qualifier.

The IncludedAttributes and ExcludedAttributes parameters specify which file attributes a file or directory must have and/or not have in order to qualify as a match. Pass 0 for either parameter if it should not be used as a match qualifier.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (such as, e.g., during the on_after_filter_attach_to_volume and on_after_filter_detach_from_volume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

Copyright (c) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Filter 2020 Python Edition - Version 20.0 [Build 8317]