CBFS Filter 2020 C++ Builder Edition

Questions / Feedback?

CBFilter Component

Properties   Methods   Events   Configuration Settings   Errors  

The CBFilter component allows applications to intercept and control filesystem requests.

Syntax

TcbfCBFilter

Remarks

The CBFilter component 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 component's capabilities, please refer to the product's General Information topics.

Getting Started

  1. If the component'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.
  2. Call the Initialize method to initialize the CBFilter component. This must be done each time the application starts.
  3. Add one or more filter rules using methods like AddFilterRule. (Rules can also be added/removed after the filter is started.)
  4. Call the StartFilter method to start filtering filesystem requests.
  5. When finished, call the StopFilter method to stop filtering filesystem requests.
  6. To uninstall the component'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 component with short descriptions. Click on the links for further details.

ActiveWhether the component is active and processing requests.
AltitudeThe altitude the component's system driver should use when operating in minifilter mode.
DefaultRuleCountThe number of records in the DefaultRule arrays.
DefaultRuleAccessFlagsThe access restrictions enforced by the rule.
DefaultRuleMaskA file mask that determines which files and directories match the rule.
FileFlushingBehaviorThe file flushing and closing behavior that the component's system driver should enforce.
FilterModeThe filter mode the component's system driver should use.
FilterRuleCountThe number of records in the FilterRule arrays.
FilterRuleAccessFlagsThe access restrictions enforced by the rule (CBFilter only).
FilterRuleControlFlagsWhich control events the rule causes the component to fire (CBFilter only).
FilterRuleEaNameThe name of an extended attribute that a file or directory must have to match the rule.
FilterRuleExcludedAttributesThe file attributes that a file or directory must not have to match the rule.
FilterRuleIncludedAttributesThe file attributes that a file or directory must have to match the rule.
FilterRuleMaskA file mask that determines which files and directories match the rule.
FilterRuleMaxSizeThe maximum size a file can be to match the rule.
FilterRuleMinSizeThe minimum size a file can be to match the rule.
FilterRuleNotifyFlagsWhich notification events the rule causes the component to fire.
FireVolumeEventsThe events that should be fired when a filesystem volume is mounted to or unmounted from the system.
PassthroughRuleCountThe number of records in the PassthroughRule arrays.
PassthroughRuleAccessFlagsThe access restrictions lifted by the rule (CBFilter only).
PassthroughRuleControlFlagsWhich control events the rule prevents the component from firing (CBFilter only).
PassthroughRuleEaNameThe name of an extended attribute that a file or directory must have to match the rule.
PassthroughRuleExcludedAttributesThe file attributes that a file or directory must not have to match the rule.
PassthroughRuleIncludedAttributesThe file attributes that a file or directory must have to match the rule.
PassthroughRuleMaskA file mask that determines which files and directories match the rule.
PassthroughRuleMaxSizeThe maximum size a file can be to match the rule.
PassthroughRuleMinSizeThe minimum size a file can be to match the rule.
PassthroughRuleNotifyFlagsWhich notification events the rule prevents the component from firing.
ProcessCachedIORequestsWhether cached file read/write requests should be processed.
ProcessFailedRequestsWhether failed requests should be processed.
ReparseRuleCountThe number of records in the ReparseRule arrays.
ReparseRuleMaskA file mask that determines which files and directories match the rule.
ReparseRuleReparseMaskA file mask that specifies where matching files and directories are redirected to.
SerializeEventsWhether events should be fired on a single worker thread, or many.
TagStores application-defined data specific to this instance of the component.

Method List


The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

AddBytesToWriteBufferReserves extra space in the file data buffers used in file read/write events.
AddDefaultRuleAdds a default rule.
AddFilterRuleAdds a standard filter rule or access rule.
AddFilterRuleExAdds a standard filter rule or access rule with additional match qualifiers.
AddPassthroughRuleAdds a passthrough rule.
AddPassthroughRuleExAdds a passthrough rule with additional match qualifiers.
AddReparseRuleAdds a reparse rule.
CloseDefaultRulesSnapshotCloses the previously-created default rules snapshot.
CloseReparseRulesSnapshotCloses the previously-created reparse rules snapshot.
ConfigSets or retrieves a configuration setting.
CreateDefaultRulesSnapshotCreates a snapshot of information about the default rules that have been added.
CreateFileDirectCreates or opens a file or directory by passing the request directly to the filesystem.
CreateFileDirectAsStreamCreates or opens a file by passing the request directly to the filesystem.
CreateReparseRulesSnapshotCreates a snapshot of information about the reparse rules that have been added.
CreateVirtualFileThis method is under construction.
DeleteAllFilterRulesDeletes all standard filter rules and access rules.
DeleteAllPassthroughRulesDeletes all passthrough rules.
DeleteAllReparseRulesDeletes all reparse rules.
DeleteDefaultRuleDeletes a particular default rule.
DeleteFilterRuleDeletes a particular standard filter rule or access rule.
DeletePassthroughRuleDeletes a particular passthrough rule.
DeleteReparseRuleDeletes a particular reparse rule.
FileMatchesMaskChecks whether a particular file or directory name matches the specified mask.
FlushNotificationQueueFlushes the notification event queue.
GetDriverStatusRetrieves the status of the component's system driver.
GetDriverVersionRetrieves the version of the component's system driver.
GetHandleCreatorProcessIdRetrieves the Id of the process (PID) that opened the file handle.
GetHandleCreatorProcessNameRetrieves the name of the process that opened the file handle.
GetHandleCreatorThreadIdRetrieves the Id of the thread that opened the file handle.
GetHandleCreatorTokenRetrieves the security token associated with the process that opened the file handle.
GetOriginatorProcessIdRetrieves the Id of the process (PID) that initiated the operation.
GetOriginatorProcessNameRetrieves the name of the process that initiated the operation.
GetOriginatorThreadIdRetrieves the Id of the thread that initiated the operation.
GetOriginatorTokenRetrieves the security token associated with the process that initiated the operation.
GetReparseRuleByMaskRetrieves the reparse rule associated with the specified file mask.
GetVolumeGUIDRetrieves the volume GUID of the device targeted by a filesystem operation.
InitializeInitializes the component.
InstallInstalls (or upgrades) the component's system driver.
IsFileFilteredChecks whether a particular file or directory is covered by any filter rules.
NtStatusToWin32ErrorConverts a native status code to a Win32 error code.
ResetTimeoutResets the timeout duration for the current event handler.
SetFileSizeDirectResizes a file by passing the request directly to the filesystem.
ShutdownSystemShuts down or reboots the operating system.
StartFilterStart filtering filesystem operations.
StopFilterStop filtering filesystem operations.
SuspendDefaultRulesSuspends all default rules until the application exits.
SuspendFileEventsSuspends all events for a particular file or directory until all of its handles have been closed.
ToggleProcessProtectionEnables or disables termination protection for the application.
UninstallUninstalls the component's system driver.

Event List


The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

AfterCanFileBeDeletedFires after the filesystem determines whether a file or directory can be deleted.
AfterCleanupFileFires after a file or directory handle is closed.
AfterCloseEnumerationFires after a directory enumeration operation finishes.
AfterCloseFileFires after a file or directory is closed.
AfterCreateFileFires after a file or directory is created.
AfterCreateHardLinkFires after a hard link is created.
AfterDeleteFileFires after a file or directory is deleted.
AfterEnumerateDirectoryFires after a directory entry is returned during directory enumeration.
AfterFilterAttachToVolumeFires after the filter attaches to a newly-mounted filesystem volume.
AfterFilterDetachFromVolumeFires after the filter detaches from a filesystem volume.
AfterFsctlFires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
AfterGetFileSecurityFires after a file or directory's security attributes are retrieved.
AfterGetFileSizesFires after a file's size information is retrieved.
AfterIoctlFires after an IRP_MJ_DEVICE_CONTROL request is processed.
AfterLockFires after a range of bytes in a file is locked.
AfterOpenFileFires after a file or directory is opened.
AfterQueryFileInfoFires after information about a file or directory is retrieved.
AfterReadFileFires after data is read from a file.
AfterRenameOrMoveFileFires after a file or directory is renamed or moved.
AfterSetAllocationSizeFires after a file's allocation size is changed.
AfterSetFileAttributesFires after a file or directory's attributes and/or times are changed.
AfterSetFileInfoFires after information about a file or directory is changed.
AfterSetFileSecurityFires after a file or directory's security attributes are changed.
AfterSetFileSizeFires after a file is resized.
AfterUnlockAllFires after all locked byte ranges in a file are unlocked.
AfterUnlockAllByKeyFires after all locked byte ranges in a file, associated with a particular key, are unlocked.
AfterUnlockSingleFires after a particular locked byte range in a file is unlocked.
AfterWriteFileFires after data is written to a file.
BeforeCanFileBeDeletedFires before the filesystem determines whether a file or directory can be deleted.
BeforeCleanupFileFires before a file or directory handle is closed.
BeforeCloseFileFires before a file or directory is closed.
BeforeCreateFileFires before a file or directory is created.
BeforeCreateHardLinkFires before a hard link is created.
BeforeDeleteFileFires before a file or directory is deleted.
BeforeFilterAttachToVolumeFires before the filter attaches to a newly-mounted filesystem volume.
BeforeFsctlFires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
BeforeGetFileSecurityFires before a file or directory's security attributes are retrieved.
BeforeIoctlFires before an IRP_MJ_DEVICE_CONTROL request is processed.
BeforeLockFires before a range of bytes in a file is locked.
BeforeOpenFileFires before a file or directory is opened.
BeforeQueryFileInfoFires before information about a file or directory is retrieved.
BeforeReadFileFires before data is read from a file.
BeforeRenameOrMoveFileFires before a file or directory is renamed or moved.
BeforeSetAllocationSizeFires before a file's allocation size is changed.
BeforeSetFileAttributesFires before a file or directory's attributes and/or times are changed.
BeforeSetFileInfoFires before information about a file or directory is changed.
BeforeSetFileSecurityFires before a file or directory's security attributes are changed.
BeforeSetFileSizeFires before a file is resized.
BeforeUnlockAllFires before all locked byte ranges in a file are unlocked.
BeforeUnlockAllByKeyFires before all locked byte ranges in a file, associated with a particular key, are unlocked.
BeforeUnlockSingleFires before a particular locked byte range in a file is unlocked.
BeforeWriteFileFires before data is written to a file.
CleanupContextFires when the application-defined data stored in one or more contexts needs to be cleaned up.
DeleteVirtualFileFires when a virtual file needs to be deleted.
ErrorFires if an unhandled error occurs during an event.
FilterStartFires once the filter has attached and filtering has started.
FilterStopFires once filtering has stopped and the filter has detached.
NotifyCanFileBeDeletedFires when the filesystem has determined whether a file or directory can be deleted.
NotifyCleanupFileFires when a file or directory handle has been closed.
NotifyCloseFileFires when a file or directory has been closed.
NotifyCreateFileFires when a file or directory has been created.
NotifyCreateHardLinkFires when a hard link has been created.
NotifyDeleteFileFires when a file or directory has been deleted.
NotifyEnumerateDirectoryFires when a directory entry has been returned during directory enumeration.
NotifyFilterAttachToVolumeFires when the filter has been attached to a newly-mounted filesystem volume.
NotifyFilterDetachFromVolumeFires when the filter has been detached from a filesystem volume.
NotifyFsctlFires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.
NotifyGetFileSecurityFires when a file or directory's security attributes have been retrieved.
NotifyGetFileSizesFires when a file's size information has been retrieved.
NotifyIoctlFires when an IRP_MJ_DEVICE_CONTROL operation has occurred.
NotifyLockFires when a range of bytes in a file has been locked.
NotifyOpenFileFires when a file or directory has been opened.
NotifyQueryFileInfoFires when information about a file or directory has been retrieved.
NotifyReadFileFires when data has been read from a file.
NotifyRenameOrMoveFileFires when a file or directory has been renamed or moved.
NotifySetAllocationSizeFires when a file's allocation size has been changed.
NotifySetFileAttributesFires when a file or directory's attributes and/or times have been changed.
NotifySetFileInfoFires when information about a file or directory has been changed.
NotifySetFileSecurityFires when a file or directory's security attributes have been changed.
NotifySetFileSizeFires when a file has been resized.
NotifyUnlockAllFires when all locked byte ranges in a file have been unlocked.
NotifyUnlockAllByKeyFires when all locked byte ranges in a file, associated with a particular key, have been unlocked.
NotifyUnlockSingleFires when a particular locked byte range in a file has been unlocked.
NotifyWriteFileFires when data has been written to a file.
ReparseFileNameFires to allow file access to be dynamically redirected another location.
ReparseWithTagFires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point.
WorkerThreadCreationFires just after a new worker thread is created.
WorkerThreadTerminationFires just before a worker thread is terminated.

Configuration Settings


The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.

AllowFileAccessInBeforeOpenWhether file access, via the CreateFileDirect method, is allowed in during the BeforeCreateFile and BeforeOpenFile events.
AlwaysPrepareFilesWhether the driver should keep track of information for files that are already open when (i.e., were opened before) the component is initialized.
CacheRemoteFilesLocallyWhether remote files involved in filtered operations should be cached locally rather than remotely.
FilterOwnRequestsWhether the component's system driver should filter requests made by the application itself.
ForceAppPermissionCheckWhether the driver should require the controller process to have elevated or system privileges.
ForceSecurityChecksWhether the driver should prevent the controller process from filtering files that it would not normally have access to.
LoggingEnabledWhether extended logging is enabled.
MaxWorkerThreadCountThe maximum number of worker threads to use to fire events.
MinWorkerThreadCountThe minimum number of worker threads to use to fire events.
ModifiableReadWriteBuffersWhether the driver should duplicate read/write buffers sent to the user.
NotificationFetchBatchSizeHow many notification entries to transfer from the kernel to the user mode at once.
PreprocessedRulesCacheSizeMaximum number of preprocessed rules to keep cached.
ResolveNtDeviceToDriveLetterWhether native device names are translated to drive letters.
SendRequestsViaDriverStackWhether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers.
WorkerInitialStackSizeThe initial stack size to create worker threads with.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Filter 2020 C++ Builder Edition - Version 20.0 [Build 7543]