CBFilter Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

CBFilter

Remarks

The CBFilter class gives applications the ability to intercept filesystem requests, allowing them to be altered, handled, or blocked. Applications use standard filter rules to specify which requests they are 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

  1. If the class's system driver has not been installed yet, call the Install method to do so. This needs to be done only once.
    • In production, the driver can be installed (or updated) ahead of time with 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 class. 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 or 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 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.

ActiveThis property notes whether the class is active and processing requests.
AltitudeThis property specifies the altitude the class's system driver should use .
DefaultRulesThis property includes the collection of default rules.
FileFlushingBehaviorThis property specifies the file flushing and closing behavior that the class's system driver should enforce.
FilterRulesThis property includes a collection of filter rules.
FireVolumeEventsThis property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system.
NormalizeShortFileNamesCBFILTER_NORMALIZE_SHORT_FILE_NAMES_NEVER 0 CBFILTER_NORMALIZE_SHORT_FILE_NAMES_LOCAL_FS 1 CBFILTER_NORMALIZE_SHORT_FILE_NAMES_ALWAYS 2, TBD.
PassthroughRulesThis property includes a collection of passthrough rules.
ProcessCachedIORequestsThis property specifies whether cached file read/write requests should be processed.
ProcessFailedRequestsThis property specifies whether failed requests should be processed.
ReparseRulesThis property includes a collection of reparse rules.
SerializeEventsWhether events should be fired on a single worker thread, or many.
TagThis property stores application-defined data specific to a particular instance of the class.
VirtualFilesThis property includes a collection of virtual files.

Method List


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

AddDefaultRuleThis method adds a default rule.
AddFilterRuleThis method adds a standard filter rule or access rule.
AddFilterRuleExThis method adds a standard filter rule or access rule with additional match qualifiers.
AddPassthroughRuleThis method adds a passthrough rule.
AddPassthroughRuleExThis method adds a passthrough rule with additional match qualifiers.
AddReparseRuleThis method adds a reparse rule.
AddVirtualFileThis method adds a virtual file to the list of virtual entries and makes it visible in the filesystem.
CloseDefaultRulesSnapshotThis method closes the previously created default rules snapshot.
CloseReparseRulesSnapshotThis method closes the previously created reparse rules snapshot.
ConfigSets or retrieves a configuration setting.
CreateDefaultRulesSnapshotThis method creates a snapshot of information about the default rules that have been added.
CreateFileDirectThis method creates or opens a file or directory by passing the request directly to the filesystem.
CreateFileDirectAsStreamThis method creates or opens a file by passing the request directly to the filesystem.
CreateReparseRulesSnapshotThis method creates a snapshot of information about the reparse rules that have been added.
DeleteAllFilterRulesThis method deletes all standard filter rules and access rules.
DeleteAllPassthroughRulesThis method deletes all passthrough rules.
DeleteAllReparseRulesThis method deletes all reparse rules.
DeleteDefaultRuleThis method deletes a particular default rule.
DeleteFilterRuleThis method deletes a particular standard filter rule or access rule.
DeletePassthroughRuleThis method deletes a particular passthrough rule.
DeleteReparseRuleThis method deletes a particular reparse rule.
FileMatchesMaskThis method checks whether a particular file or directory name matches the specified mask.
GetDriverStatusThis method retrieves the status of the class's system driver.
GetDriverVersionThis method retrieves the version of the class's system driver.
GetEventFileNameThis method retrieves the name of the file or directory, to which the event applies.
GetHandleCreatorProcessIdThis method retrieves the Id of the process (PID) that opened the file handle.
GetHandleCreatorProcessNameThis method retrieves the name of the process that opened the file handle.
GetHandleCreatorThreadIdThis method retrieves the Id of the thread that opened the file handle.
GetHandleCreatorTokenThis method retrieves the security token associated with the process that opened the file handle.
GetOperationTimeThis method returns the time at which the request was received by the filter driver.
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.
GetRemoteAccessInformationThis method returns networking-related information about the operation.
GetReparseRuleByMaskThis method retrieves the reparse rule associated with the specified file mask.
GetVolumeGUIDThis method retrieves the volume GUID of the device targeted by a filesystem operation.
InitializeThis method initializes the class.
InstallThis method installs (or upgrades) the class's system driver.
IsFileFilteredThis method checks whether a particular file or directory is covered by any filter rules.
NtStatusToWin32ErrorThis method converts a native status code to a Win32 error code.
QueryFileInformationDirectThis method returns various kinds of information about a file object.
QueryFileSecurityDirectThis method retrieves security information of a file.
RemoveVirtualFileThis method removes a virtual file from the list of virtual entries.
ResetTimeoutThis method resets the timeout duration for the current event handler.
SetFileInformationDirectThis method sets the file information of a file opened using CreateFileDirect.
SetFileSecurityDirectThis method sets security information of a file.
SetFileSizeDirectThis method resizes a file by passing the request directly to the filesystem.
ShutdownSystemShuts down or reboots the operating system.
StartFilterThis method starts filtering filesystem operations.
StopFilterThis method stops filtering filesystem operations.
SuspendDefaultRulesThis method suspends all default rules until the application exits.
SuspendFileEventsThis method suspends all events for a particular file or directory until all of its handles have been closed.
ToggleProcessProtectionThis method enables or disables termination protection for the application.
UninstallThis method uninstalls the class's system driver.
UpdateVirtualFileThis method updates known information about a virtual file .

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.

AfterCanFileBeDeletedThis event fires after the OS marks a file or directory for deletion or removes such a mark.
AfterCleanupFileThis event fires after a file or directory handle is closed.
AfterCloseEnumerationThis event fires after a directory enumeration operation finishes.
AfterCloseFileThis event fires after a file or directory is closed.
AfterCreateFileThis event fires after a file or directory is created.
AfterCreateHardLinkThis event fires after a hard link is created.
AfterDeleteFileThis event fires after a file or directory is deleted.
AfterDeleteReparsePointThis event fires after the OS deletes a reparse point from a file or directory.
AfterEnumerateDirectoryThis event fires after a directory entry is returned during directory enumeration.
AfterFilterAttachToVolumeThis event fires after the filter attaches to a newly mounted filesystem volume.
AfterFilterDetachFromVolumeThis event fires after the filter detaches from a filesystem volume.
AfterFsctlThis event fires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
AfterGetFileSecurityThis event fires after a file or directory's security attributes are retrieved.
AfterGetFileSizesThis event fires after a file's size information is retrieved.
AfterGetReparsePointThis event fires after a file or directory's reparse point information is retrieved.
AfterIoctlThis event fires after an IRP_MJ_DEVICE_CONTROL request is processed.
AfterLockThis event fires after a range of bytes in a file is locked.
AfterOpenFileThis event fires after a file or directory is opened.
AfterQueryEaThis event fires after information about extended attributes of a file is retrieved.
AfterQueryFileInfoThis event fires after information about a file or directory is retrieved.
AfterReadFileThis event fires after data are read from a file.
AfterRenameOrMoveFileThis event fires after a file or directory is renamed or moved.
AfterSetAllocationSizeThis event fires after a file's allocation size is changed.
AfterSetEaThis event fires after extended attributes of a file are changed.
AfterSetFileAttributesThis event fires after a file or directory's attributes or times are changed.
AfterSetFileInfoThis event fires after information about a file or directory is changed.
AfterSetFileSecurityThis event fires after a file or directory's security attributes are changed.
AfterSetFileSizeThis event fires after a file is resized.
AfterSetReparsePointThis event fires after the OS creates or updates a reparse point on a file or directory.
AfterUnlockAllThis event fires after all locked byte ranges in a file are unlocked.
AfterUnlockAllByKeyThis event fires after all locked byte ranges in a file, associated with a particular key, are unlocked.
AfterUnlockSingleThis event fires after a particular locked byte range in a file is unlocked.
AfterWriteFileThis event fires after data are written to a file.
BeforeCanFileBeDeletedThis event fires before the OS attempts to mark a file or directory for deletion or remove such a mark.
BeforeCleanupFileThis event fires before a file or directory handle is closed.
BeforeCloseFileThis event fires before a file or directory is closed.
BeforeCreateFileThis event fires before a file or directory is created.
BeforeCreateHardLinkThis event fires before a hard link is created.
BeforeDeleteFileThis event fires before a file or directory is deleted.
BeforeDeleteReparsePointThis event fires when the OS wants to delete a reparse point from a file or directory.
BeforeEnumerateDirectoryThis event fires when an enumeration request is sent by the OS.
BeforeFilterAttachToVolumeThis event fires before the filter attaches to a newly mounted filesystem volume.
BeforeFsctlThis event fires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
BeforeGetFileSecurityThis event fires before a file or directory's security attributes are retrieved.
BeforeGetReparsePointThis event fires when the OS wants to read a reparse point for a file or directory.
BeforeIoctlThis event fires before an IRP_MJ_DEVICE_CONTROL request is processed.
BeforeLockThis event fires before a range of bytes in a file is locked.
BeforeOpenFileThis event fires before a file or directory is opened.
BeforeQueryEaThis event fires before information about extended attributes of a file is retrieved.
BeforeQueryFileInfoThis event fires before information about a file or directory is retrieved.
BeforeReadFileThis event fires before data are read from a file.
BeforeRenameOrMoveFileThis event fires before a file or directory is renamed or moved.
BeforeSetAllocationSizeThis event fires before a file's allocation size is changed.
BeforeSetEaThis event fires before extended attributes of a file are changed.
BeforeSetFileAttributesThis event fires before a file or directory's attributes or times are changed.
BeforeSetFileInfoThis event fires before information about a file or directory is changed.
BeforeSetFileSecurityThis event fires before a file or directory's security attributes are changed.
BeforeSetFileSizeThis event fires before a file is resized.
BeforeSetReparsePointThis event fires when the OS wants to create or update a reparse point on a file or directory.
BeforeUnlockAllThis event fires before all locked byte ranges in a file are unlocked.
BeforeUnlockAllByKeyThis event fires before all locked byte ranges in a file, associated with a particular key, are unlocked.
BeforeUnlockSingleThis event fires before a particular locked byte range in a file is unlocked.
BeforeWriteFileThis event fires before data are written to a file.
BypassIORequestThis event fires when the OS sends one of BypassIO commands.
CleanupContextThis event fires when the application-defined data stored in one or more contexts need to be cleaned up.
ErrorThis event fires if an unhandled error occurs during an event.
FilterStartThis event fires once the filter has attached and filtering has started.
FilterStopThis event fires once filtering has stopped and the filter has detached.
NotifyCanFileBeDeletedThis event fires when the OS marks a file or directory for deletion or removes such a mark.
NotifyCleanupFileThis event fires when a file or directory handle has been closed.
NotifyCloseFileThis event fires when a file or directory has been closed.
NotifyCreateFileThis event fires when a file or directory has been created.
NotifyCreateHardLinkThis event fires when a hard link has been created.
NotifyDeleteFileThis event fires when a file or directory has been deleted.
NotifyDeleteReparsePointThis event fires when a file or directory's reparse point has been deleted.
NotifyEnumerateDirectoryThis event fires when a directory entry has been returned during directory enumeration.
NotifyFilterAttachToVolumeThis event fires when the filter has been attached to a newly mounted filesystem volume.
NotifyFilterDetachFromVolumeThis event fires when the filter has been detached from a filesystem volume.
NotifyFsctlThis event fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.
NotifyGetFileSecurityThis event fires when a file or directory's security attributes have been retrieved.
NotifyGetFileSizesThis event fires when a file's size information has been retrieved.
NotifyGetReparsePointThis event fires when a file or directory's reparse point information has been retrieved.
NotifyIoctlThis event fires when an IRP_MJ_DEVICE_CONTROL operation has occurred.
NotifyLockThis event fires when a range of bytes in a file has been locked.
NotifyOpenFileThis event fires when a file or directory has been opened.
NotifyQueryEaThis event fires when information about the extended attributes of a file has been retrieved.
NotifyQueryFileInfoThis event fires when information about a file or directory has been retrieved.
NotifyReadFileThis event fires when data have been read from a file.
NotifyRenameOrMoveFileThis event fires when a file or directory has been renamed or moved.
NotifySetAllocationSizeThis event fires when a file's allocation size has been changed.
NotifySetEaThis event fires when information about the extended attributes of a file has been changed.
NotifySetFileAttributesThis event fires when a file or directory's attributes or times have been changed.
NotifySetFileInfoThis event fires when information about a file or directory has been changed.
NotifySetFileSecurityThis event fires when a file or directory's security attributes have been changed.
NotifySetFileSizeThis event fires when a file has been resized.
NotifySetReparsePointThis event fires when a file or directory's reparse point has been created or updated.
NotifyUnlockAllThis event fires when all locked byte ranges in a file have been unlocked.
NotifyUnlockAllByKeyThis event fires when all locked byte ranges in a file, associated with a particular key, have been unlocked.
NotifyUnlockSingleThis event fires when a particular locked byte range in a file has been unlocked.
NotifyWriteFileThis event fires when data have been written to a file.
ReparseFileNameThis event fires to allow file access to be dynamically redirected to another location.
ReparseWithTagThis event fires 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.

Config Settings


The following is a list of config settings for the class 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 class is initialized.
AlwaysRequestAttributesOnOpenWhether the driver should keep request existing attributes before file create/open operation.
CacheRemoteFilesLocallyWhether remote files involved in filtered operations should be cached locally rather than remotely.
FilterOwnRequestsWhether the class's system driver should filter requests made by the application itself.
ForceAdminRightsForDefaultRulesSpecifies whether default rules can be added or deleted only by administrators.
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.
NormalizeShortFileNamesWhether the driver should attempt to resolve short file names and convert them to regular ones.
OmitEventFileNamesWhether the filename parameter should be empty in events.
PassAllFileNamesWhether the driver should pass all known names of a file, including hardlinks and previous names, to event handlers.
PassSecurityInFileOpenEventsWhether security information, associated with the file create/open request, is passed to file creation and opening events.
PreprocessedRulesCacheSizeMaximum number of preprocessed rules to keep cached.
RecordOperationTimeEnables collection of operation time.
ResolveNtDeviceToDriveLetterWhether native device names are translated to drive letters.
RetriveLinkNamesOnOpenSpecifies that the driver should collect all hard links when a file is opened.
SendRequestsViaDriverStackWhether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers.
SerializeAccessWhether nonintersecting operations against the same file should execute serially or in parallel.
TranslateDOSCharsInEnumMasksWhether the DOS wildcard characters should be translated during search.
WorkerInitialStackSizeThe initial stack size to create worker threads with.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

Active Property (CBFilter Class)

This property notes whether the class is active and processing requests.

Syntax

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();
int cbfsfilter_cbfilter_getactive(void* lpObj);
bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class is active and currently processing requests. It will be true after the filter has been attached successfully via a call to StartFilter.

This property is read-only and not available at design time.

Data Type

Boolean

Altitude Property (CBFilter Class)

This property specifies the altitude the class's system driver should use .

Syntax

ANSI (Cross Platform)
char* GetAltitude();
int SetAltitude(const char* lpszAltitude); Unicode (Windows) LPWSTR GetAltitude();
INT SetAltitude(LPCWSTR lpszAltitude);
char* cbfsfilter_cbfilter_getaltitude(void* lpObj);
int cbfsfilter_cbfilter_setaltitude(void* lpObj, const char* lpszAltitude);
QString GetAltitude();
int SetAltitude(QString qsAltitude);

Default Value

""

Remarks

This property specifies the altitude that the class's system driver should use . A driver's altitude determines its absolute position in the stack of filter drivers; drivers with higher altitudes are attached toward the top of the stack, closer to the user mode, which allows them to process requests earlier.

Microsoft manages and assigns filesystem minifilter driver altitudes directly, so an application-specific altitude value must be obtained from Microsoft before an application is deployed in production. Please refer to the Driver Altitudes topic for more information. During development, an appropriate arbitrary value, such as 360000 (which is not registered with Microsoft), can be used.

If this property is queried before an altitude has been set (via this property or the Install method), it will return an empty string.

Note: This property cannot be changed when Active is true. Additionally, the Initialize method must be called before attempting to get or set this property's value, which is stored in the registry.

Data Type

String

DefaultRules Property (CBFilter Class)

This property includes the collection of default rules.

Syntax

int cbfsfilter_cbfilter_getdefaultrulecount(void* lpObj);
int cbfsfilter_cbfilter_getdefaultruleaccessflags(void* lpObj, int defaultruleindex);
char* cbfsfilter_cbfilter_getdefaultrulemask(void* lpObj, int defaultruleindex);
int GetDefaultRuleCount();

int GetDefaultRuleAccessFlags(int iDefaultRuleIndex);

QString GetDefaultRuleMask(int iDefaultRuleIndex);

Remarks

This property holds a collection of FileDefaultRule objects, each of which represents a default rule. Please refer to the Default Rules topic for more information.

Use the following methods to manage default rules:

Note: Because default rules are managed by the class's system driver, this collection is not populated by default, nor is it updated by any of the aforementioned methods. Applications can call the CreateDefaultRulesSnapshot method to populate this collection; and must call the CloseDefaultRulesSnapshot method when finished working with it to release the associated memory.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

This property is read-only and not available at design time.

Data Type

CBFSFilterFileDefaultRule

FileFlushingBehavior Property (CBFilter Class)

This property specifies the file flushing and closing behavior that the class's system driver should enforce.

Syntax

ANSI (Cross Platform)
int GetFileFlushingBehavior();
int SetFileFlushingBehavior(int iFileFlushingBehavior); Unicode (Windows) INT GetFileFlushingBehavior();
INT SetFileFlushingBehavior(INT iFileFlushingBehavior);
int cbfsfilter_cbfilter_getfileflushingbehavior(void* lpObj);
int cbfsfilter_cbfilter_setfileflushingbehavior(void* lpObj, int iFileFlushingBehavior);
int GetFileFlushingBehavior();
int SetFileFlushingBehavior(int iFileFlushingBehavior);

Default Value

0

Remarks

This property specifies what file flushing and closing behaviors the class's system driver should enforce.

Applications that modify file data as it is being read or written may need to change this property's value to function correctly. For example, applications that provide on-the-fly encryption should choose the proper flags to ensure that other applications that have opened the files being encrypted cannot accidentally write nonencrypted data to the disk.

Applications that do not modify file data as it is being read or written can leave this property unchanged.

The value of this property should be constructed by ORing together zero or more of the following flags:

FS_FLUSH_FILES_ON_OPEN1Whether memory-mapped file data should be flushed to disk before files are opened.

This flag indicates that the class's system driver should flush any cached and memory-mapped file data, leftover from the last time a file was opened, before opening it again. Doing so ensures that file data are read directly from the disk rather than from the old memory mapping.

Applications that modify file data as it is being read may need to set this flag to function correctly. For example, applications that provide on-the-fly encryption should set this flag to ensure that file data are always read from the disk (and thus have a chance to get decrypted) when a file is opened.

Applications that do not modify file data as it is being read should leave this flag unset to maintain optimal performance when opening files.

FS_FLUSH_FILES_ON_CLOSE2Whether file buffers must be flushed when files are closed.

This flag indicates that the class's system driver should flush and clear the buffers of files that are opened for writing (and have had data written to them) when they are closed.

Applications that modify file data as it is being written may need to set this flag to function correctly. For example, applications that provide on-the-fly encryption should set this flag to ensure that all file data are flushed to the disk (and thus has a chance to get encrypted) when a file is closed.

Applications that do not modify file data as it is being written can unset this flag.

After a file is flushed, all in-memory buffers and memory mappings are cleared to avoid leakage of unprotected information.

FS_CLOSE_FILES_ON_STOPFILTER4Whether files opened for writing must be closed when the application stops filtering.

This flag indicates that the class's system driver should close files that are opened for writing (and have had data written to them) when the application calls StopFilter.

Applications that modify file data as it is being written (e.g., on-the-fly encryption) may need to set this flag to prevent further operations against the file data from being performed. Applications that do not modify file data as it is being written can leave this flag unset.

Note: If memory mappings of some file exist, these mappings will remain active; only the open handles to such files are closed.

When the file is closed, all in-memory buffers and memory mappings are cleared to avoid leakage of unprotected information. Applications can control whether file data are flushed before files are closed using the FS_FLUSH_FILES_ON_STOPFILTER flag; any data that are not flushed get discarded.

FS_FLUSH_FILES_ON_STOPFILTER8Whether file buffers must be flushed when the application stops filtering.

This flag indicates that the class's system driver should flush and clear the buffers of files that are opened for writing (and have had data written to them) when the application calls StopFilter.

Applications that modify file data as it is being written (e.g., on-the-fly encryption) may need to set this flag to ensure that no unprotected data are kept in memory, but rather has a chance to be encrypted and written out to disk. Applications that do not modify file data as it is being written can leave this flag unset.

If the application will not be able to perform on-the-fly data modification at the moment when StopFilter is called (e.g., because a cryptographic hardware module is unplugged), then this flag should be unset before calling StopFilter.

After a file is flushed, all in-memory buffers and memory mappings are cleared to avoid leakage of unprotected information.

FS_CLOSE_FILES_ON_CRASH16Whether files opened for writing must be closed if the application terminates unexpectedly.

This flag indicates that the class's system driver should close files that are opened for writing (and have had data written to them) if the driver detects that the application has terminated.

Applications that modify file data as it is being written (e.g., on-the-fly encryption) may need to set this flag to prevent further operations against the file data from being performed. Applications that do not modify file data as it is being written can leave this flag unset.

Note: If memory mappings of some file exist, these mappings will remain active; only the open handles to such files are closed.

When the file is closed, all in-memory buffers and memory mappings are cleared to avoid leakage of unprotected information.

FS_FLUSH_FILES_ON_CRASH32Whether file buffers must be flushed if the application terminates unexpectedly.

This flag indicates that the class's system driver should flush and clear the buffers of files that are opened for writing (and have had data written to them) if the driver detects that the application has terminated.

Applications that do not modify data as it is being written may set this flag if necessary. Applications that modify data as it is being written (e.g., on-the-fly encryption) should not set this flag, because such flushing could cause unprotected data to be written out to disk.

FS_SUPPORT_FILE_ENCRYPTION31Combination of flags suitable for on-the-fly file encryption applications.

This option includes the following flags: FS_FLUSH_FILES_ON_OPEN, FS_FLUSH_FILES_ON_CLOSE, FS_CLOSE_FILES_ON_STOPFILTER, FS_FLUSH_FILES_ON_STOPFILTER, and FS_CLOSE_FILES_ON_CRASH flags.

Data Type

Integer

FilterRules Property (CBFilter Class)

This property includes a collection of filter rules.

Syntax

int cbfsfilter_cbfilter_getfilterrulecount(void* lpObj);
int cbfsfilter_cbfilter_getfilterruleaccessflags(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbfilter_getfilterrulecontrolflags(void* lpObj, int filterruleindex);
char* cbfsfilter_cbfilter_getfilterruleeaname(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbfilter_getfilterruleexcludedattributes(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbfilter_getfilterruleincludedattributes(void* lpObj, int filterruleindex);
char* cbfsfilter_cbfilter_getfilterrulemask(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbfilter_getfilterrulemaxsize(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbfilter_getfilterruleminsize(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbfilter_getfilterrulenotifyflags(void* lpObj, int filterruleindex);
int GetFilterRuleCount();

int GetFilterRuleAccessFlags(int iFilterRuleIndex);

qint64 GetFilterRuleControlFlags(int iFilterRuleIndex);

QString GetFilterRuleEaName(int iFilterRuleIndex);

qint64 GetFilterRuleExcludedAttributes(int iFilterRuleIndex);

qint64 GetFilterRuleIncludedAttributes(int iFilterRuleIndex);

QString GetFilterRuleMask(int iFilterRuleIndex);

qint64 GetFilterRuleMaxSize(int iFilterRuleIndex);

qint64 GetFilterRuleMinSize(int iFilterRuleIndex);

qint64 GetFilterRuleNotifyFlags(int iFilterRuleIndex);

Remarks

This property holds a collection of FileFilterRule objects, each of which represents a standard filter rule, access rule, or both. Please refer to the File and Registry Filter Rules and Access Rules topics for more information.

Use the following methods to manage the rules in this collection:

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

This property is read-only and not available at design time.

Data Type

CBFSFilterFileFilterRule

FireVolumeEvents Property (CBFilter Class)

This property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system.

Syntax

ANSI (Cross Platform)
int GetFireVolumeEvents();
int SetFireVolumeEvents(int iFireVolumeEvents); Unicode (Windows) INT GetFireVolumeEvents();
INT SetFireVolumeEvents(INT iFireVolumeEvents);
int cbfsfilter_cbfilter_getfirevolumeevents(void* lpObj);
int cbfsfilter_cbfilter_setfirevolumeevents(void* lpObj, int iFireVolumeEvents);
int GetFireVolumeEvents();
int SetFireVolumeEvents(int iFireVolumeEvents);

Default Value

0

Remarks

This property specifies the events that the class should fire when a filesystem volume is mounted to or unmounted from the system. Possible values are as follows:

FS_MOUNT_IGNORE0Don't fire any events when volumes are mounted or unmounted.

FS_MOUNT_NOTIFY64Fire Notification Events when volumes are mounted or unmounted.

The NotifyFilterAttachToVolume and NotifyFilterDetachFromVolume events will fire, asynchronously, as necessary.

FS_MOUNT_CONTROL128Fire Control Events when volumes are mounted or unmounted.

The BeforeFilterAttachToVolume, AfterFilterAttachToVolume, and AfterFilterDetachFromVolume events will fire, synchronously, as necessary.

FS_MOUNT_BOTH192Fire all events when volumes are mounted or unmounted.

Note: The aforementioned events are fired only for volumes mounted/unmounted after the StartFilter method is called. Typically, applications use these events to dynamically add or remove volume-specific filter rules that target removable volumes (e.g., USB drives) as well as to create virtual files on such volumes. Please refer to the File Masks topic for more information.

Data Type

Integer

NormalizeShortFileNames Property (CBFilter Class)

CBFILTER_NORMALIZE_SHORT_FILE_NAMES_NEVER 0 CBFILTER_NORMALIZE_SHORT_FILE_NAMES_LOCAL_FS 1 CBFILTER_NORMALIZE_SHORT_FILE_NAMES_ALWAYS 2, TBD.

Syntax

ANSI (Cross Platform)
int GetNormalizeShortFileNames();
int SetNormalizeShortFileNames(int iNormalizeShortFileNames); Unicode (Windows) INT GetNormalizeShortFileNames();
INT SetNormalizeShortFileNames(INT iNormalizeShortFileNames);
int cbfsfilter_cbfilter_getnormalizeshortfilenames(void* lpObj);
int cbfsfilter_cbfilter_setnormalizeshortfilenames(void* lpObj, int iNormalizeShortFileNames);
int GetNormalizeShortFileNames();
int SetNormalizeShortFileNames(int iNormalizeShortFileNames);

Default Value

0

Remarks

TBD.

Data Type

Integer

PassthroughRules Property (CBFilter Class)

This property includes a collection of passthrough rules.

Syntax

int cbfsfilter_cbfilter_getpassthroughrulecount(void* lpObj);
int cbfsfilter_cbfilter_getpassthroughruleaccessflags(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbfilter_getpassthroughrulecontrolflags(void* lpObj, int passthroughruleindex);
char* cbfsfilter_cbfilter_getpassthroughruleeaname(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbfilter_getpassthroughruleexcludedattributes(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbfilter_getpassthroughruleincludedattributes(void* lpObj, int passthroughruleindex);
char* cbfsfilter_cbfilter_getpassthroughrulemask(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbfilter_getpassthroughrulemaxsize(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbfilter_getpassthroughruleminsize(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbfilter_getpassthroughrulenotifyflags(void* lpObj, int passthroughruleindex);
int GetPassthroughRuleCount();

int GetPassthroughRuleAccessFlags(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleControlFlags(int iPassthroughRuleIndex);

QString GetPassthroughRuleEaName(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleExcludedAttributes(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleIncludedAttributes(int iPassthroughRuleIndex);

QString GetPassthroughRuleMask(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleMaxSize(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleMinSize(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleNotifyFlags(int iPassthroughRuleIndex);

Remarks

This property holds a collection of FilePassthroughRule objects, each of which represents a passthrough rule. Please refer to the Passthrough Rules topic for more information.

Use the following methods to manage the rules in this collection:

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

This property is read-only and not available at design time.

Data Type

CBFSFilterFilePassthroughRule

ProcessCachedIORequests Property (CBFilter Class)

This property specifies whether cached file read/write requests should be processed.

Syntax

ANSI (Cross Platform)
int GetProcessCachedIORequests();
int SetProcessCachedIORequests(int bProcessCachedIORequests); Unicode (Windows) BOOL GetProcessCachedIORequests();
INT SetProcessCachedIORequests(BOOL bProcessCachedIORequests);
int cbfsfilter_cbfilter_getprocesscachediorequests(void* lpObj);
int cbfsfilter_cbfilter_setprocesscachediorequests(void* lpObj, int bProcessCachedIORequests);
bool GetProcessCachedIORequests();
int SetProcessCachedIORequests(bool bProcessCachedIORequests);

Default Value

FALSE

Remarks

This property specifies whether the class's system driver should process cached file read/write requests (i.e., fire *ReadFile and *WriteFile events for them). Please refer to the Cached and Non-Cached Requests topic for more information.

Note: This property cannot be changed when Active is true.

Data Type

Boolean

ProcessFailedRequests Property (CBFilter Class)

This property specifies whether failed requests should be processed.

Syntax

ANSI (Cross Platform)
int GetProcessFailedRequests();
int SetProcessFailedRequests(int bProcessFailedRequests); Unicode (Windows) BOOL GetProcessFailedRequests();
INT SetProcessFailedRequests(BOOL bProcessFailedRequests);
int cbfsfilter_cbfilter_getprocessfailedrequests(void* lpObj);
int cbfsfilter_cbfilter_setprocessfailedrequests(void* lpObj, int bProcessFailedRequests);
bool GetProcessFailedRequests();
int SetProcessFailedRequests(bool bProcessFailedRequests);

Default Value

FALSE

Remarks

This property specifies whether the class's system driver should process failed requests (i.e., fire After* or Notify* events for them).

When this property is enabled, applications can inspect the Status parameter of the aforementioned events to determine whether an operation has failed. If an operation fails, then the corresponding event's Status parameter will contain a nonzero native status code. Applications generally can use the NtStatusToWin32Error method to convert these status codes into Win32 error codes (but keep in mind that not all native status codes have direct Win32 error code mapping).

Data Type

Boolean

ReparseRules Property (CBFilter Class)

This property includes a collection of reparse rules.

Syntax

int cbfsfilter_cbfilter_getreparserulecount(void* lpObj);
char* cbfsfilter_cbfilter_getreparserulemask(void* lpObj, int reparseruleindex);
char* cbfsfilter_cbfilter_getreparserulereparsemask(void* lpObj, int reparseruleindex);
int GetReparseRuleCount();

QString GetReparseRuleMask(int iReparseRuleIndex);

QString GetReparseRuleReparseMask(int iReparseRuleIndex);

Remarks

This property holds a collection of FileReparseRule objects, each of which represents a reparse rule. Please refer to the Reparse Rules topic for more information.

Use the following methods to manage reparse rules:

Note: Because reparse rules are managed by the class's system driver, this collection is not populated by default, nor is it updated by any of the aforementioned methods. Applications can call the CreateReparseRulesSnapshot method to populate this collection; and must call the CloseReparseRulesSnapshot method when finished working with it to release the associated memory.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

This property is read-only and not available at design time.

Data Type

CBFSFilterFileReparseRule

SerializeEvents Property (CBFilter Class)

Whether events should be fired on a single worker thread, or many.

Syntax

ANSI (Cross Platform)
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents); Unicode (Windows) INT GetSerializeEvents();
INT SetSerializeEvents(INT iSerializeEvents);

Possible Values

SE_ON_MULTIPLE_THREADS(0), 
SE_ON_ONE_WORKER_THREAD(1)
int cbfsfilter_cbfilter_getserializeevents(void* lpObj);
int cbfsfilter_cbfilter_setserializeevents(void* lpObj, int iSerializeEvents);
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Default Value

0

Remarks

This property specifies whether the class should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:

0 (seOnMultipleThreads) The class fires events in the context of multiple worker threads. The MinWorkerThreadCount and MaxWorkerThreadCount configuration settings control how many worker threads are used for this.
1 (seOnOneWorkerThread) The class fires events in the context of one background worker thread.

Please refer to the Threading and Concurrency topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Integer

Tag Property (CBFilter Class)

This property stores application-defined data specific to a particular instance of the class.

Syntax

ANSI (Cross Platform)
int64 GetTag();
int SetTag(int64 lTag); Unicode (Windows) LONG64 GetTag();
INT SetTag(LONG64 lTag);
int64 cbfsfilter_cbfilter_gettag(void* lpObj);
int cbfsfilter_cbfilter_settag(void* lpObj, int64 lTag);
qint64 GetTag();
int SetTag(qint64 lTag);

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the class.

Data Type

Long64

VirtualFiles Property (CBFilter Class)

This property includes a collection of virtual files.

Syntax

CBFSFilterList<CBFSFilterVirtualFile>* GetVirtualFiles();

int cbfsfilter_cbfilter_getvirtualfilecount(void* lpObj);
int cbfsfilter_cbfilter_getvirtualfileattributes(void* lpObj, int virtualfileindex);
int64 cbfsfilter_cbfilter_getvirtualfilechangetime(void* lpObj, int virtualfileindex);
int64 cbfsfilter_cbfilter_getvirtualfilecreationtime(void* lpObj, int virtualfileindex);
int64 cbfsfilter_cbfilter_getvirtualfilelastaccesstime(void* lpObj, int virtualfileindex);
int64 cbfsfilter_cbfilter_getvirtualfilelastwritetime(void* lpObj, int virtualfileindex);
char* cbfsfilter_cbfilter_getvirtualfilename(void* lpObj, int virtualfileindex);
char* cbfsfilter_cbfilter_getvirtualfilentnativename(void* lpObj, int virtualfileindex);
int64 cbfsfilter_cbfilter_getvirtualfilesize(void* lpObj, int virtualfileindex);
int GetVirtualFileCount();

int GetVirtualFileAttributes(int iVirtualFileIndex);

QDateTime GetVirtualFileChangeTime(int iVirtualFileIndex);

QDateTime GetVirtualFileCreationTime(int iVirtualFileIndex);

QDateTime GetVirtualFileLastAccessTime(int iVirtualFileIndex);

QDateTime GetVirtualFileLastWriteTime(int iVirtualFileIndex);

QString GetVirtualFileName(int iVirtualFileIndex);

QString GetVirtualFileNTNativeName(int iVirtualFileIndex);

qint64 GetVirtualFileSize(int iVirtualFileIndex);

Remarks

This property holds a collection of VirtualFile objects, each of which represents a virtual file.

Use the following methods to manage virtual files in this collection:

This property is read-only and not available at design time.

Data Type

CBFSFilterVirtualFile

AddDefaultRule Method (CBFilter Class)

This method adds a default rule.

Syntax

ANSI (Cross Platform)
bool AddDefaultRule(const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);

Unicode (Windows)
INT AddDefaultRule(LPCWSTR lpszMask, INT iAccessFlags, LPCWSTR lpszProductGUID);
bool cbfsfilter_cbfilter_adddefaultrule(void* lpObj, const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);
bool AddDefaultRule(const QString& qsMask, int iAccessFlags, const QString& qsProductGUID);

Remarks

This method adds a default rule for the files and directories that match the specified Mask. 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.

Default rules, like access rules, instruct the class's system driver to apply certain access restrictions to matching files and directories. However, unlike access rules, default rules are managed by the driver directly; they are activated as soon as the driver loads at boot time, and then continue to be enforced at all times, regardless of whether the application that added them is open.

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

The AccessFlags parameter specifies which access restrictions the class's system driver should apply to matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ProductGUID parameter identifies the application that the rule should be associated with in the registry. In most cases, the value passed for this parameter should be the same one that was used to call the Initialize method.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error. Please refer to the Default Rules topic for more information.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddFilterRule Method (CBFilter Class)

This method adds a standard filter rule or access rule.

Syntax

ANSI (Cross Platform)
bool AddFilterRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);

Unicode (Windows)
INT AddFilterRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags, LONG64 lNotifyFlags);
bool cbfsfilter_cbfilter_addfilterrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);
bool AddFilterRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags, qint64 lNotifyFlags);

Remarks

This method adds a standard filter rule or access rule for the files and directories that match the specified Mask. 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. Access rules instruct the class's system driver to apply certain access restrictions to matching files and directories.

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

The AccessFlags parameter specifies which access restrictions the class's system driver should apply to matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which filesystem operations the class should fire Control Events for. For example, if the FS_CE_BEFORE_READ and FS_CE_AFTER_READ flags are present, the BeforeReadFile and AfterReadFile events will fire before and after a read operation is performed on any file that matches Mask. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

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 NotifyReadFile 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 ORing 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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddFilterRuleEx Method (CBFilter Class)

This method adds a standard filter rule or access rule with additional match qualifiers.

Syntax

ANSI (Cross Platform)
bool AddFilterRuleEx(const char* lpszMask, const char* lpszEaName, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);

Unicode (Windows)
INT AddFilterRuleEx(LPCWSTR lpszMask, LPCWSTR lpszEaName, INT iAccessFlags, LONG64 lControlFlags, LONG64 lNotifyFlags, LONG64 lMinSize, LONG64 lMaxSize, LONG64 lIncludedAttributes, LONG64 lExcludedAttributes);
bool cbfsfilter_cbfilter_addfilterruleex(void* lpObj, const char* lpszMask, const char* lpszEaName, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);
bool AddFilterRuleEx(const QString& qsMask, const QString& qsEaName, int iAccessFlags, qint64 lControlFlags, qint64 lNotifyFlags, qint64 lMinSize, qint64 lMaxSize, qint64 lIncludedAttributes, qint64 lExcludedAttributes);

Remarks

This method adds a standard filter rule or access 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. Access rules instruct the class's system driver to apply certain access restrictions to matching files and directories.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories that 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 to qualify as a match; wildcards are not allowed. Pass an empty string if this parameter should not be used as a match qualifier.

The AccessFlags parameter specifies which access restrictions the class's system driver should apply to matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which filesystem operations the class should fire Control Events for. For example, if the FS_CE_BEFORE_READ and FS_CE_AFTER_READ flags are present, the BeforeReadFile and AfterReadFile events will fire before and after a read operation is performed on any file that matches Mask. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

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 NotifyReadFile 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 ORing 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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

The MinSize and MaxSize parameters specify the minimum and 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 or not have 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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddPassthroughRule Method (CBFilter Class)

This method adds a passthrough rule.

Syntax

ANSI (Cross Platform)
bool AddPassthroughRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);

Unicode (Windows)
INT AddPassthroughRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags, LONG64 lNotifyFlags);
bool cbfsfilter_cbfilter_addpassthroughrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);
bool AddPassthroughRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags, qint64 lNotifyFlags);

Remarks

This method adds a passthrough rule for the files and directories that match the specified Mask. 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.

Passthrough rules exclude matching files and directories from being processed by other filter rules.

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

The AccessFlags parameter specifies which access restrictions the class's system driver should lift from matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which filesystem operations the class should not fire Control Events for. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

The NotifyFlags parameter specifies which filesystem operations the class should not fire Notification Events for. The value passed for this parameter should be constructed by ORing 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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddPassthroughRuleEx Method (CBFilter Class)

This method adds a passthrough rule with additional match qualifiers.

Syntax

ANSI (Cross Platform)
bool AddPassthroughRuleEx(const char* lpszMask, const char* lpszEaName, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);

Unicode (Windows)
INT AddPassthroughRuleEx(LPCWSTR lpszMask, LPCWSTR lpszEaName, INT iAccessFlags, LONG64 lControlFlags, LONG64 lNotifyFlags, LONG64 lMinSize, LONG64 lMaxSize, LONG64 lIncludedAttributes, LONG64 lExcludedAttributes);
bool cbfsfilter_cbfilter_addpassthroughruleex(void* lpObj, const char* lpszMask, const char* lpszEaName, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);
bool AddPassthroughRuleEx(const QString& qsMask, const QString& qsEaName, int iAccessFlags, qint64 lControlFlags, qint64 lNotifyFlags, qint64 lMinSize, qint64 lMaxSize, qint64 lIncludedAttributes, qint64 lExcludedAttributes);

Remarks

This method adds a passthrough 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.

Passthrough rules exclude matching files and directories from being processed by other filter rules.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories that 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 to qualify as a match; wildcards are not allowed. Pass an empty string if this parameter should not be used as a match qualifier.

The AccessFlags parameter specifies which access restrictions the class's system driver should lift from matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which filesystem operations the class should not fire Control Events for. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

The NotifyFlags parameter specifies which filesystem operations the class should not fire Notification Events for. The value passed for this parameter should be constructed by ORing 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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

The MinSize and MaxSize parameters specify the minimum and 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 or not have 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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddReparseRule Method (CBFilter Class)

This method adds a reparse rule.

Syntax

ANSI (Cross Platform)
bool AddReparseRule(const char* lpszMask, const char* lpszReparseMask, const char* lpszProductGUID, int iFlags);

Unicode (Windows)
INT AddReparseRule(LPCWSTR lpszMask, LPCWSTR lpszReparseMask, LPCWSTR lpszProductGUID, INT iFlags);
bool cbfsfilter_cbfilter_addreparserule(void* lpObj, const char* lpszMask, const char* lpszReparseMask, const char* lpszProductGUID, int iFlags);
bool AddReparseRule(const QString& qsMask, const QString& qsReparseMask, const QString& qsProductGUID, int iFlags);

Remarks

This method adds a reparse rule for the files and directories that match the specified Mask. Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule replaces it.

If the rule is added successfully, this method returns true; otherwise, it returns false.

Reparse rules are used to redirect access from a file or directory covered by Mask to another location in the filesystem, specified by ReparseMask.

The Mask and ReparseMask parameters must be valid file masks according to the File Masks topic. Only the files and directories that match Mask will be covered by the rule (i.e., redirected to the path specified by ReparseMask). For example, passing *.txt for Mask and *_1.txt for ReparseMask would cause, for example, test.txt to be redirected to test_1.txt.

More generally, for each wildcard (* or ?) present in Mask, there must be a corresponding wildcard (of the same type) in ReparseMask; and the wildcards in ReparseMask must appear in the same order as they do in Mask. For example, if Mask is 20??_Budget.*, then 20??_Budget_Report.* would be a legal value for ReparseMask; but 20??_Budget_Report.xls would not be, nor would 20*_Budget_Report.*.

The ProductGUID parameter identifies the application that the rule should be associated with in the registry. In most cases, the value passed for this parameter should be the same one that was used to call the Initialize method.

The Flags parameter specifies how, exactly, the redirection should be performed. Possible values are as follows:

FS_REPARSE_CHANGE_PATH0Perform redirection by modifying the path directly using the CBFilter system driver.

FS_REPARSE_USE_REPARSE_POINT1Perform redirection by having the CBFilter system driver emulate real reparse point behavior.

This option will cause the driver to report that a file or directory's parent directory is a reparse point of the SYMLINK variety. Redirection performed in this manner is more consistent with Windows' behavior; however, some software may fail to correctly handle paths that cross such symbolic links.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddVirtualFile Method (CBFilter Class)

This method adds a virtual file to the list of virtual entries and makes it visible in the filesystem.

Syntax

ANSI (Cross Platform)
bool AddVirtualFile(const char* lpszFileName, int64 lCreationTime, int64 lLastAccessTime, int64 lLastWriteTime, int64 lChangeTime, int64 lSize, int iAttributes);

Unicode (Windows)
INT AddVirtualFile(LPCWSTR lpszFileName, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lLastWriteTime, LONG64 lChangeTime, LONG64 lSize, INT iAttributes);
bool cbfsfilter_cbfilter_addvirtualfile(void* lpObj, const char* lpszFileName, int64 lCreationTime, int64 lLastAccessTime, int64 lLastWriteTime, int64 lChangeTime, int64 lSize, int iAttributes);
bool AddVirtualFile(const QString& qsFileName, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtLastWriteTime, QDateTime qdtChangeTime, qint64 lSize, int iAttributes);

Remarks

This method creates or opens a virtual file and adds it to the list of virtual entries, managed by the class. If the class is active, the virtual file also appears in the filesystem. Virtual directories are not supported.

The class stores the creation parameters in the list. Adding the same file name several times will create only one list entry for each distinct file name, and subsequent calls to AddVirtualFile with different parameters will be ignored. To update properties of the file that is already in the list, use the UpdateVirtualFile method. To remove the file from the list, use the RemoveVirtualFile method.

The FileName parameter must contain the full path and name of the file being added. The drive on which the file resides may be referenced in one of following formats:

  • A volume GUID, formatted like Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} . A path may start with the \\?\ prefix, such as "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}".
  • A DOS name, formatted like C:\.
  • A volume NT-native name, formatted like \Device\HarddiskVolumeX\, where X is the number of the volume.
To successfully add a virtual file, the volume in the path must already be present on the system.

Note: if an application adds multiple files to the same drive, it is more efficient to convert a GUID-based or a DOS-name-based volume name to the NT-native format using the GetNTPathName method, then use the obtained NT-native volume name in the calls to this AddVirtualFile method.

CreationTime, LastAccessTime, LastWriteTime, ChangeTime must specify the corresponding time values for the file, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

Size must be set to the size of the file. It may be 0 for an empty file or a positive value.

Attributes must be set to the file's attributes. Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The method will return true if the file was added to the list and false if the file is already present in the list. An error will be reported if adding the file failed on the driver side.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CloseDefaultRulesSnapshot Method (CBFilter Class)

This method closes the previously created default rules snapshot.

Syntax

ANSI (Cross Platform)
int CloseDefaultRulesSnapshot();

Unicode (Windows)
INT CloseDefaultRulesSnapshot();
int cbfsfilter_cbfilter_closedefaultrulessnapshot(void* lpObj);
int CloseDefaultRulesSnapshot();

Remarks

This method closes the default rules snapshot previously created by CreateDefaultRulesSnapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CloseReparseRulesSnapshot Method (CBFilter Class)

This method closes the previously created reparse rules snapshot.

Syntax

ANSI (Cross Platform)
int CloseReparseRulesSnapshot();

Unicode (Windows)
INT CloseReparseRulesSnapshot();
int cbfsfilter_cbfilter_closereparserulessnapshot(void* lpObj);
int CloseReparseRulesSnapshot();

Remarks

This method closes the reparse rules snapshot previously created by CreateReparseRulesSnapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (CBFilter Class)

Sets or retrieves a configuration setting.

Syntax

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);
char* cbfsfilter_cbfilter_config(void* lpObj, const char* lpszConfigurationString);
QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateDefaultRulesSnapshot Method (CBFilter Class)

This method creates a snapshot of information about the default rules that have been added.

Syntax

ANSI (Cross Platform)
int CreateDefaultRulesSnapshot(const char* lpszProductGUID);

Unicode (Windows)
INT CreateDefaultRulesSnapshot(LPCWSTR lpszProductGUID);
int cbfsfilter_cbfilter_createdefaultrulessnapshot(void* lpObj, const char* lpszProductGUID);
int CreateDefaultRulesSnapshot(const QString& qsProductGUID);

Remarks

This method creates a snapshot of information about all default rules that have been added by the application identified by ProductGUID. This information is then used to populate the DefaultRule* properties.

When the application is finished working with the default rules snapshot, it must close it by calling the CloseDefaultRulesSnapshot method to release the associated memory. If this method is called again before an existing snapshot is closed, the class will attempt to close it before creating a new one.

Note: This method cannot be called within events.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CreateFileDirect Method (CBFilter Class)

This method creates or opens a file or directory by passing the request directly to the filesystem.

Syntax

ANSI (Cross Platform)
int64 CreateFileDirect(const char* lpszFileName, int bSynchronize, int iDesiredAccess, int iShareMode, int iCreationDisposition, int iFlagsAndAttributes, int bCloseImmediately, int bSendViaStack);

Unicode (Windows)
LONG64 CreateFileDirect(LPCWSTR lpszFileName, BOOL bSynchronize, INT iDesiredAccess, INT iShareMode, INT iCreationDisposition, INT iFlagsAndAttributes, BOOL bCloseImmediately, BOOL bSendViaStack);
int64 cbfsfilter_cbfilter_createfiledirect(void* lpObj, const char* lpszFileName, int bSynchronize, int iDesiredAccess, int iShareMode, int iCreationDisposition, int iFlagsAndAttributes, int bCloseImmediately, int bSendViaStack);
qint64 CreateFileDirect(const QString& qsFileName, bool bSynchronize, int iDesiredAccess, int iShareMode, int iCreationDisposition, int iFlagsAndAttributes, bool bCloseImmediately, bool bSendViaStack);

Remarks

This method should be used instead of the Windows API's CreateFile function to create or open a file or directory when an application needs to access this file without sending requests through the complete filesystem filter driver stack.

The parameters of this method correspond to the parameters of the CreateFile function.

If the file or directory is created or opened successfully, this method returns a file handle for it; otherwise, it returns INVALID_HANDLE_VALUE. The returned handle, if valid, must be closed using the Windows API's CloseHandle function when the application is finished with it. See the "Use of Handle" section below for details of how to use the handle.

If CloseImmediately is true, this method will create or open the specified file or directory and then immediately close the resulting handle. In this case, the handle will still be returned to indicate the success of the operation, but it will not be usable in any file operations.

The SendViaStack parameter specifies how the driver should send the request for opening the file as well as other requests that will be sent using the opened file handle. When this parameter is false, requests made by the application using the handle, created by the CreateFileDirect method, are sent directly to the filesystem. When some filter drivers are located lower in the driver stack than the CBFilter driver, such requests will bypass that filter drivers with possibly unexpected consequences (e.g., requests going to the wrong file, wrong data being read or written). Set this parameter to true to make the driver pass these requests down the filter stack, letting them reach other filter drivers before the filesystem.

When the SendViaStack parameter is false, requests against the returned file handle are routed directly to the filesystem (bypassing all filter drivers, including the class's); applications can use it to call the Windows File API functions (ReadFile, WriteFile) within filesystem-related events without causing a system deadlock. However, pay special attention to the Synchronize parameter's documentation, which is given below.

The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively).

Please refer to Microsoft's documentation for more information about how to set these parameters appropriately.

The CreationDisposition parameter should be set to one of the valid values and may not be 0. If any of these requirements is not met, the ERROR_INVALID_PARAMETER error is returned.

The ShareMode parameter should be set by ORing together zero or more of the following flags:

FILESYS_SHARE_NONE0x00000000Prevents any process from opening a file or device if it requests delete, read, or write access.

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

CBFILTER_IGNORE_SHARE_ACCESS_CHECK0x10000000Specifies that the driver should pass IO_IGNORE_SHARE_ACCESS_CHECK flag to the system functions.

Use this flag to bypass sharing checks performed by the I/O manager when opening local files.

Note: The filesystem still may perform these checks. Also, the internal structures are not updated with the share mode values, passed in this call. This means that subsequent file open operations will not know about the previous share mode and may succeed where they would have to fail.

The Synchronize parameter specifies whether this method and operations with the resulting handle should be synchronized with the thread that originated the underlying filesystem request associated with the current event (i.e., the event that this method was called from).

The parameter is applicable only when a caller uses it to open the file, for which the event was fired, when isolation is not used. If the file create/open operation is isolated (the handler sets the Isolate parameter of the corresponding event to true), the application may safely set Synchronize to false. Also, the parameter should not be set to true when this method is called from the AfterCloseFile event; when the event is fired, no file is open to synchronize operations with.

It is recommended to set Synchronize to true when the method is called from AfterCreateFile and AfterOpenFile event handlers. This helps prevent possible deadlocks in other filter drivers.

Please refer to Direct File operations for additional information about the use of a handle or a stream obtained using this method.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateFileDirectAsStream Method (CBFilter Class)

This method creates or opens a file by passing the request directly to the filesystem.

Syntax

ANSI (Cross Platform)
CBFSFilterStream* CreateFileDirectAsStream(const char* lpszFileName, int bSynchronize, int iDesiredAccess, int iShareMode, int iCreationDisposition, int iFlagsAndAttributes, int bSendViaStack, int64* lHandle);

Unicode (Windows)
CBFSFilterStream* CreateFileDirectAsStream(LPCWSTR lpszFileName, BOOL bSynchronize, INT iDesiredAccess, INT iShareMode, INT iCreationDisposition, INT iFlagsAndAttributes, BOOL bSendViaStack, LONG64*  lHandle);
CBFSFilterStream* cbfsfilter_cbfilter_createfiledirectasstream(void* lpObj, const char* lpszFileName, int bSynchronize, int iDesiredAccess, int iShareMode, int iCreationDisposition, int iFlagsAndAttributes, int bSendViaStack, int64* lHandle);
CBFSFilterStream* CreateFileDirectAsStream(const QString& qsFileName, bool bSynchronize, int iDesiredAccess, int iShareMode, int iCreationDisposition, int iFlagsAndAttributes, bool bSendViaStack, qint64* lHandle);

Remarks

This method should be used instead of the Windows API's CreateFile function to create or open a file when an application needs to access this file without sending requests through the complete filesystem filter driver stack.

The parameters of this method correspond to the parameters of the CreateFile function.

If the file is created or opened successfully, this method returns a stream object that provides access to its data; otherwise, it returns NULL.

Upon success, the Handle parameter is populated with the file handle value. This handle value does not need to be closed - the class will do this automatically when the stream is closed. See the "Use of Handle" section below for details of how to use the handle.

The SendViaStack parameter specifies how the driver should send the request for opening the file as well as other requests that will be sent using the opened file handle. When this parameter is false, requests made by the application using the handle, created by the CreateFileDirect method, are sent directly to the filesystem. When some filter drivers are located lower in the driver stack than the CBFilter driver, such requests will bypass that filter drivers with possibly unexpected consequences (e.g., requests going to the wrong file, wrong data being read or written). Set this parameter to true to make the driver pass these requests down the filter stack, letting them reach other filter drivers before the filesystem.

When the SendViaStack parameter is false, requests against the opened file are routed directly to the filesystem (bypassing all filter drivers, including the class's); applications can use it within filesystem-related events without causing a system deadlock. However, pay special attention to the Synchronize parameter's documentation, which is given below.

The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively).

Please refer to Microsoft's documentation for more information about how to set these parameters appropriately.

The CreationDisposition parameter should be set to one of the valid values and may not be 0. If any of these requirements is not met, the ERROR_INVALID_PARAMETER error is returned.

The ShareMode parameter should be set by ORing together zero or more of the following flags:

FILESYS_SHARE_NONE0x00000000Prevents any process from opening a file or device if it requests delete, read, or write access.

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

CBFILTER_IGNORE_SHARE_ACCESS_CHECK0x10000000Specifies that the driver should pass IO_IGNORE_SHARE_ACCESS_CHECK flag to the system functions.

Use this flag to bypass sharing checks performed by the I/O manager when opening local files.

Note: The filesystem still may perform these checks. Also, the internal structures are not updated with the share mode values, passed in this call. This means that subsequent file open operations will not know about the previous share mode and may succeed where they would have to fail.

The Synchronize parameter specifies whether this method and operations with the resulting handle should be synchronized with the thread that originated the underlying filesystem request associated with the current event (i.e., the event that this method was called from).

The parameter is applicable only when a caller uses it to open the file, for which the event was fired, when isolation is not used. If the file create/open operation is isolated (the handler sets the Isolate parameter of the corresponding event to true), the application may safely set Synchronize to false. Also, the parameter should not be set to true when this method is called from the AfterCloseFile event; when the event is fired, no file is open to synchronize operations with.

It is recommended to set Synchronize to true when the method is called from AfterCreateFile and AfterOpenFile event handlers. This helps prevent possible deadlocks in other filter drivers.

Please refer to Direct File operations for additional information about the use of a handle or a stream obtained using this method.

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateReparseRulesSnapshot Method (CBFilter Class)

This method creates a snapshot of information about the reparse rules that have been added.

Syntax

ANSI (Cross Platform)
int CreateReparseRulesSnapshot(const char* lpszProductGUID);

Unicode (Windows)
INT CreateReparseRulesSnapshot(LPCWSTR lpszProductGUID);
int cbfsfilter_cbfilter_createreparserulessnapshot(void* lpObj, const char* lpszProductGUID);
int CreateReparseRulesSnapshot(const QString& qsProductGUID);

Remarks

This method creates a snapshot of information about all reparse rules that have been added by the application identified by ProductGUID. This information is then used to populate the ReparseRule* properties.

When the application is finished working with the reparse rules snapshot, it must close it by calling the CloseReparseRulesSnapshot method to release the associated memory. If this method is called again before an existing snapshot is closed, the class will attempt to close it before creating a new one.

Note: This method cannot be called within events.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteAllFilterRules Method (CBFilter Class)

This method deletes all standard filter rules and access rules.

Syntax

ANSI (Cross Platform)
bool DeleteAllFilterRules();

Unicode (Windows)
INT DeleteAllFilterRules();
bool cbfsfilter_cbfilter_deleteallfilterrules(void* lpObj);
bool DeleteAllFilterRules();

Remarks

This method deletes all standard filter rules and access rules that are currently present.

If the rules are deleted successfully, this method returns true; otherwise, it returns false.

To delete standard filter rules or access rules individually, use the DeleteFilterRule method instead.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteAllPassthroughRules Method (CBFilter Class)

This method deletes all passthrough rules.

Syntax

ANSI (Cross Platform)
bool DeleteAllPassthroughRules();

Unicode (Windows)
INT DeleteAllPassthroughRules();
bool cbfsfilter_cbfilter_deleteallpassthroughrules(void* lpObj);
bool DeleteAllPassthroughRules();

Remarks

This method deletes all passthrough rules that are currently present.

If the rules are deleted successfully, this method returns true; otherwise, it returns false.

To delete passthrough rules individually, use the DeletePassthroughRule method instead.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteAllReparseRules Method (CBFilter Class)

This method deletes all reparse rules.

Syntax

ANSI (Cross Platform)
bool DeleteAllReparseRules(const char* lpszProductGUID);

Unicode (Windows)
INT DeleteAllReparseRules(LPCWSTR lpszProductGUID);
bool cbfsfilter_cbfilter_deleteallreparserules(void* lpObj, const char* lpszProductGUID);
bool DeleteAllReparseRules(const QString& qsProductGUID);

Remarks

This method deletes all reparse rules associated with the application identified by ProductGUID.

If the rules are deleted successfully, this method returns true; otherwise, it returns false.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the Initialize method. Please refer to the AddReparseRule method's documentation for more information.

To delete reparse rules individually, use the DeleteReparseRule method instead.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteDefaultRule Method (CBFilter Class)

This method deletes a particular default rule.

Syntax

ANSI (Cross Platform)
bool DeleteDefaultRule(const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);

Unicode (Windows)
INT DeleteDefaultRule(LPCWSTR lpszMask, INT iAccessFlags, LPCWSTR lpszProductGUID);
bool cbfsfilter_cbfilter_deletedefaultrule(void* lpObj, const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);
bool DeleteDefaultRule(const QString& qsMask, int iAccessFlags, const QString& qsProductGUID);

Remarks

This method deletes the specified AccessFlags from the default rule identified by Mask and associated with the application identified by ProductGUID. If AccessFlags includes all flags currently present in the rule, then the entire rule is deleted; otherwise, the flags specified by AccessFlags are simply removed from the rule.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the file mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The AccessFlags parameter specifies which access restrictions should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the Initialize method. Please refer to the AddDefaultRule method's documentation for more information.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error. Please refer to the Default Rules topic for more information.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteFilterRule Method (CBFilter Class)

This method deletes a particular standard filter rule or access rule.

Syntax

ANSI (Cross Platform)
bool DeleteFilterRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);

Unicode (Windows)
INT DeleteFilterRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags, LONG64 lNotifyFlags);
bool cbfsfilter_cbfilter_deletefilterrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);
bool DeleteFilterRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags, qint64 lNotifyFlags);

Remarks

This method deletes the specified AccessFlags, ControlFlags, and/or NotifyFlags from the standard filter rule and/or access rule identified by Mask. If the aforementioned parameters include all flags currently present in the rule, then the entire rule is deleted; otherwise, the specified flags are simply removed from the rule.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the file mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The AccessFlags parameter specifies which access restrictions should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which Control Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

The NotifyFlags parameter specifies which Notification Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing 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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

To delete all standard filter rules and access rules, use the DeleteAllFilterRules method instead.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeletePassthroughRule Method (CBFilter Class)

This method deletes a particular passthrough rule.

Syntax

ANSI (Cross Platform)
bool DeletePassthroughRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);

Unicode (Windows)
INT DeletePassthroughRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags, LONG64 lNotifyFlags);
bool cbfsfilter_cbfilter_deletepassthroughrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags, int64 lNotifyFlags);
bool DeletePassthroughRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags, qint64 lNotifyFlags);

Remarks

This method deletes the specified AccessFlags, ControlFlags, and/or NotifyFlags from the passthrough rule identified by Mask. If the aforementioned parameters include all flags currently present in the rule, then the entire rule is deleted; otherwise, the specified flags are simply removed from the rule.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the file mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The AccessFlags parameter specifies which access restrictions should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which Control Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

The NotifyFlags parameter specifies which Notification Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing 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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

To delete all passthrough rules, use the DeleteAllPassthroughRules method instead.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteReparseRule Method (CBFilter Class)

This method deletes a particular reparse rule.

Syntax

ANSI (Cross Platform)
bool DeleteReparseRule(const char* lpszMask, const char* lpszProductGUID);

Unicode (Windows)
INT DeleteReparseRule(LPCWSTR lpszMask, LPCWSTR lpszProductGUID);
bool cbfsfilter_cbfilter_deletereparserule(void* lpObj, const char* lpszMask, const char* lpszProductGUID);
bool DeleteReparseRule(const QString& qsMask, const QString& qsProductGUID);

Remarks

This method deletes the ReparseRules identified by Mask and associated with the application identified by ProductGUID.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the file mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the Initialize method. Please refer to the AddReparseRule method's documentation for more information.

To delete all reparse rules, use the DeleteAllReparseRules method instead.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

FileMatchesMask Method (CBFilter Class)

This method checks whether a particular file or directory name matches the specified mask.

Syntax

ANSI (Cross Platform)
bool FileMatchesMask(const char* lpszMask, const char* lpszFileName, int bCaseSensitive);

Unicode (Windows)
INT FileMatchesMask(LPCWSTR lpszMask, LPCWSTR lpszFileName, BOOL bCaseSensitive);
bool cbfsfilter_cbfilter_filematchesmask(void* lpObj, const char* lpszMask, const char* lpszFileName, int bCaseSensitive);
bool FileMatchesMask(const QString& qsMask, const QString& qsFileName, bool bCaseSensitive);

Remarks

This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns true. The CaseSensitive parameter controls whether a case-sensitive match should be performed.

Note: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.

Note: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverStatus Method (CBFilter Class)

This method retrieves the status of the class's system driver.

Syntax

ANSI (Cross Platform)
int GetDriverStatus(const char* lpszProductGUID);

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID);
int cbfsfilter_cbfilter_getdriverstatus(void* lpObj, const char* lpszProductGUID);
int GetDriverStatus(const QString& qsProductGUID);

Remarks

This method retrieves the status of the class's system driver. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:

MODULE_STATUS_NOT_PRESENT0x00000000The specified module is not present on the system.

Note: This functionality is only available in Windows.

MODULE_STATUS_STOPPED0x00000001The specified module is in the Stopped state.

Note: This functionality is only available in Windows.

MODULE_STATUS_RUNNING0x00000004The specified module is loaded and running.

Note: This functionality is only available in Windows.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverVersion Method (CBFilter Class)

This method retrieves the version of the class's system driver.

Syntax

ANSI (Cross Platform)
int64 GetDriverVersion(const char* lpszProductGUID);

Unicode (Windows)
LONG64 GetDriverVersion(LPCWSTR lpszProductGUID);
int64 cbfsfilter_cbfilter_getdriverversion(void* lpObj, const char* lpszProductGUID);
qint64 GetDriverVersion(const QString& qsProductGUID);

Remarks

This method retrieves the version of the class's system driver. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the class's system driver is not installed, this method returns 0.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetEventFileName Method (CBFilter Class)

This method retrieves the name of the file or directory, to which the event applies.

Syntax

ANSI (Cross Platform)
char* GetEventFileName();

Unicode (Windows)
LPWSTR GetEventFileName();
char* cbfsfilter_cbfilter_geteventfilename(void* lpObj);
QString GetEventFileName();

Remarks

This method can be called within event handlers of events, related to the file or directory operations, to retrieve the name of the file or directory, to which the operation applies. If the query fails or an event does not have an associated file name, this method returns an empty string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorProcessId Method (CBFilter Class)

This method retrieves the Id of the process (PID) that opened the file handle.

Syntax

ANSI (Cross Platform)
int GetHandleCreatorProcessId();

Unicode (Windows)
INT GetHandleCreatorProcessId();
int cbfsfilter_cbfilter_gethandlecreatorprocessid(void* lpObj);
int GetHandleCreatorProcessId();

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that opened the file handle. If the query fails, this method returns 0.

Note: PIDs are not unique and may be reused by different processes over time (although in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

  1. Call this method within the AfterCreateFile or AfterOpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information through the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorProcessName Method (CBFilter Class)

This method retrieves the name of the process that opened the file handle.

Syntax

ANSI (Cross Platform)
char* GetHandleCreatorProcessName();

Unicode (Windows)
LPWSTR GetHandleCreatorProcessName();
char* cbfsfilter_cbfilter_gethandlecreatorprocessname(void* lpObj);
QString GetHandleCreatorProcessName();

Remarks

This method can be called within certain events to retrieve the name of the process that opened the file handle. If the query fails, this method returns an empty string.

Applications cannot use this method to retrieve information about remote processes accessing drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

  1. Call this method within the AfterCreateFile or AfterOpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information through the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorThreadId Method (CBFilter Class)

This method retrieves the Id of the thread that opened the file handle.

Syntax

ANSI (Cross Platform)
int GetHandleCreatorThreadId();

Unicode (Windows)
INT GetHandleCreatorThreadId();
int cbfsfilter_cbfilter_gethandlecreatorthreadid(void* lpObj);
int GetHandleCreatorThreadId();

Remarks

This method can be called within certain events to retrieve the Id of the thread that opened the file handle. If the query fails, this method returns 0.

Notes: Thread Ids are not unique and may be reused by different threads over time.

Note: This method can be called only within the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

  1. Call this method within the AfterCreateFile or AfterOpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information through the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorToken Method (CBFilter Class)

This method retrieves the security token associated with the process that opened the file handle.

Syntax

ANSI (Cross Platform)
int64 GetHandleCreatorToken();

Unicode (Windows)
LONG64 GetHandleCreatorToken();
int64 cbfsfilter_cbfilter_gethandlecreatortoken(void* lpObj);
qint64 GetHandleCreatorToken();

Remarks

This method can be called within certain events to retrieve the security token associated with the process that opened the file handle. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

Note: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

Applications monitoring a drive shared on the network may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

  • Authenticated mode, in which case the network redirector (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
  • Guest mode, in which case the retrievable information is for the system's GUEST account.
  • Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

  1. Call this method within the AfterCreateFile or AfterOpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information through the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOperationTime Method (CBFilter Class)

This method returns the time at which the request was received by the filter driver.

Syntax

ANSI (Cross Platform)
int64 GetOperationTime();

Unicode (Windows)
LONG64 GetOperationTime();
int64 cbfsfilter_cbfilter_getoperationtime(void* lpObj);
QDateTime GetOperationTime();

Remarks

This method can be called within operation-related events to retrieve the time at which the filter driver received the request. The time is recorded before an event is fired but only when the RecordOperationTime configuration setting is enabled.

The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorProcessId Method (CBFilter Class)

Retrieves the Id of the process (PID) that initiated the operation.

Syntax

ANSI (Cross Platform)
int GetOriginatorProcessId();

Unicode (Windows)
INT GetOriginatorProcessId();
int cbfsfilter_cbfilter_getoriginatorprocessid(void* lpObj);
int GetOriginatorProcessId();

Remarks

This method can be called within events fired for filesystem operations to retrieve the Id of the process (PID) that initiated the operation. If the query fails, this method returns 0.

Please note that PIDs are not unique, and may be reused by different processes over time (though in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the CreateFile or OpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorProcessName Method (CBFilter Class)

Retrieves the name of the process that initiated the operation.

Syntax

ANSI (Cross Platform)
char* GetOriginatorProcessName();

Unicode (Windows)
LPWSTR GetOriginatorProcessName();
char* cbfsfilter_cbfilter_getoriginatorprocessname(void* lpObj);
QString GetOriginatorProcessName();

Remarks

This method can be called within events fired for filesystem operations to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

Applications cannot use this method to retrieve information about remote processes accessing drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the CreateFile or OpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorThreadId Method (CBFilter Class)

Retrieves the Id of the thread that initiated the operation.

Syntax

ANSI (Cross Platform)
int GetOriginatorThreadId();

Unicode (Windows)
INT GetOriginatorThreadId();
int cbfsfilter_cbfilter_getoriginatorthreadid(void* lpObj);
int GetOriginatorThreadId();

Remarks

This method can be called within events fired for filesystem operations to retrieve the Id of the thread that initiated the operation. If the query fails, this method returns 0.

Please note that thread Ids are not unique, and may be reused by different threads over time.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the CreateFile or OpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorToken Method (CBFilter Class)

Retrieves the security token associated with the process that initiated the operation.

Syntax

ANSI (Cross Platform)
int64 GetOriginatorToken();

Unicode (Windows)
LONG64 GetOriginatorToken();
int64 cbfsfilter_cbfilter_getoriginatortoken(void* lpObj);
qint64 GetOriginatorToken();

Remarks

This method can be called within synchronous, i.e., Before* and After* events fired for filesystem operations to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE. Note: This method will not work properly when called from Notify* event handlers because security tokens are not kept for possible later use. If you need to obtain security information about a request, use corresponding After* events.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

Important: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

Applications monitoring a drive shared on the network may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

  • Authenticated mode, in which case the network redirector (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
  • Guest mode, in which case the retrievable information is for the system's GUEST account.
  • Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the CreateFile or OpenFile event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetRemoteAccessInformation Method (CBFilter Class)

This method returns networking-related information about the operation.

Syntax

ANSI (Cross Platform)
int GetRemoteAccessInformation(char** lpszShareName, void* lpClientSocketAddressBuffer, int* iClientSocketAddressBufferSize);

Unicode (Windows)
INT GetRemoteAccessInformation(LPWSTR* lpszShareName, LPVOID lpClientSocketAddressBuffer, INT*  iClientSocketAddressBufferSize);
int cbfsfilter_cbfilter_getremoteaccessinformation(void* lpObj, char** lpszShareName, void* lpClientSocketAddressBuffer, int* iClientSocketAddressBufferSize);
int GetRemoteAccessInformation(QString& qsShareName, void* lpClientSocketAddressBuffer, int* iClientSocketAddressBufferSize);

Remarks

Call this method from *CreateFile/*OpenFile events to retrieve the collected networking details information related to the filesystem operation performed across the network.

Note: The information will be available only when the CollectRemoteOpenInformation configuration setting is enabled.

This method returns the contents of one of two structures, SRV_OPEN_ECP_CONTEXT or NFS_OPEN_ECP_CONTEXT. These structures contain various networking information that differs depending on the remote access type. Please refer to MSDN for additional information.

Depending on the type of remote access, the information is extracted from one of those structures. When the method returns, ShareName will contain the value of either ShareName or ExportAlias field of the corresponding structure. ClientSocketAddressBuffer will contain the value of the SocketAddress or ClientSocketAddress field of the corresponding structure. This field is a structure of the SOCKADDR_STORAGE_NFS type.

When calling the method, an application needs to prepare the buffer of the required size and specify this size of the ClientSocketAddressBuffer buffer in the ClientSocketAddressBufferSize argument.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetReparseRuleByMask Method (CBFilter Class)

This method retrieves the reparse rule associated with the specified file mask.

Syntax

ANSI (Cross Platform)
char* GetReparseRuleByMask(const char* lpszMask, const char* lpszProductGUID);

Unicode (Windows)
LPWSTR GetReparseRuleByMask(LPCWSTR lpszMask, LPCWSTR lpszProductGUID);
char* cbfsfilter_cbfilter_getreparserulebymask(void* lpObj, const char* lpszMask, const char* lpszProductGUID);
QString GetReparseRuleByMask(const QString& qsMask, const QString& qsProductGUID);

Remarks

This method retrieves the reparse rule identified by Mask and associated with the application identified by ProductGUID. If such a reparse rule is found, this method returns its reparse mask (see AddReparseRule); otherwise, it returns empty string.

The Mask parameter must be the file mask of an existing rule.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the Initialize method.

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 (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetVolumeGUID Method (CBFilter Class)

This method retrieves the volume GUID of the device targeted by a filesystem operation.

Syntax

ANSI (Cross Platform)
char* GetVolumeGUID();

Unicode (Windows)
LPWSTR GetVolumeGUID();
char* cbfsfilter_cbfilter_getvolumeguid(void* lpObj);
QString GetVolumeGUID();

Remarks

This method can be called within events fired for filesystem operations to retrieve the volume GUID of the device targeted by the operation, returned in the Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format. If the query fails, this method returns an empty string.

Volume GUIDs can be used to enumerate the mounting points of a device using the Windows API's GetVolumePathNamesForVolumeName function.

Note: This method can be called only within events.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Initialize Method (CBFilter Class)

This method initializes the class.

Syntax

ANSI (Cross Platform)
int Initialize(const char* lpszProductGUID);

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);
int cbfsfilter_cbfilter_initialize(void* lpObj, const char* lpszProductGUID);
int Initialize(const QString& qsProductGUID);

Remarks

This method initializes the class and must be called each time the application starts before attempting to call any of the class's other methods with the exception of installation-related methods.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, Initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the Install method is required before the class can be used.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Install Method (CBFilter Class)

This method installs (or upgrades) the class's system driver.

Syntax

ANSI (Cross Platform)
bool Install(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, const char* lpszAltitude, int iFlags, const char* lpszAllowedControllers);

Unicode (Windows)
INT Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszPathToInstall, LPCWSTR lpszAltitude, INT iFlags, LPCWSTR lpszAllowedControllers);
bool cbfsfilter_cbfilter_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, const char* lpszAltitude, int iFlags, const char* lpszAllowedControllers);
bool Install(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsPathToInstall, const QString& qsAltitude, int iFlags, const QString& qsAllowedControllers);

Remarks

This method is used to install or upgrade the class's system driver. If the system must be rebooted to complete the installation process, this method returns true; otherwise, it returns false.

Important: To upgrade the class's driver, use only the Install method. Previously installed versions of the driver should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the cbfilter.cab file containing the class's system driver.

Note: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required to uninstall the driver from the system.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

PathToInstall controls where the driver is installed. Pass empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

Altitude specifies the driver altitude to use . During development, you can use any acceptable altitude value. For deployment, an altitude value must be assigned by Microsoft before deploying a filesystem minifilter in production. After installation, the altitude can be changed at any time using the Altitude property. Please refer to the Driver Altitudes topic for more information.

Flags specifies various installation options. It should contain zero or more of the following flags, ORed together:

INSTALL_REMOVE_OLD_VERSIONS0x00000001Uninstall drivers from previous class versions (e.g., 2017).

INSTALL_KEEP_START_TYPE0x00000002Keep the driver's current start type setting in the registry.

If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application) set it previously.

INSTALL_OVERWRITE_SAME_VERSION0x00000004Install the driver file when its version and build number is the same as the version of the already installed driver.

INSTALL_REQUESTS_VIA_DRIVER_STACK0x00001000Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers.

This flag is applicable only for CBFilter and CBMonitor.

After installation, the effects of this flag can be changed using the SendRequestsViaDriverStack configuration setting.

INSTALL_ALWAYS_PREPARE_FILES0x00010000Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the class is initialized.

This flag is applicable only for CBFilter and CBMonitor.

If this flag is set, the driver will prepare information about each file as it is opened, regardless of whether a CBFilter/CBMonitor-based application is actually running at the time. This information then allows applications to receive events for any files that are already open when the CBFilter/CBMonitor class is initialized.

Note: These preparations will slow down all file open operations; do not enable this feature unless it is actually necessary.

After installation, the effects of this flag can be changed using the AlwaysPrepareFiles configuration setting.

INSTALL_FORCE_APP_PERMISSION_CHECK0x00020000Whether the driver should require the controller process to have elevated or system privileges.

This flag is not applicable for CBProcess.

If this flag is set, the driver will verify that the controller process is a system service (or is executing with elevated privileges) anytime a file is opened. If the controller process does not meet these requirements, the file will be skipped (i.e., not filtered in any way).

Note: This additional verification will slow down all file open operations.

After installation, the effects of this flag can be changed using the ForceAppPermissionCheck configuration setting.

INSTALL_FORCE_SECURITY_CHECKS0x00040000Whether the driver should prevent the controller process from filtering files that it would not normally have access to.

This flag is not applicable for CBProcess.

If this flag is set, the driver will check the security permissions of the controller process anytime a file is opened to verify that the process has access to the file. If the controller process does not have access to the file, the file will be skipped (i.e., not filtered in any way). For example, if this flag is set and the controller process is running with limited privileges, then the driver will not allow it to filter files that require greater privileges to access.

Note: This additional verification will slow down all file open operations.

After installation, the effects of this flag can be changed using the ForceSecurityChecks configuration setting.

Note: Enabling the AlwaysPrepareFiles and/or SendRequestsViaDriverStack configuration settings before calling this method will cause the corresponding flags to be added automatically. These configuration settings can also be used to toggle the corresponding options at any time after installation.

AllowedControllers is the optional parameter that makes it possible to limit communication with the driver to just the predefined set of processes. When the caller specifies one or more names of the executable files, filtering can be started with the specified ProductGUID only when filtering is initiated by the process created from one of the listed executable files. If the name of the caller process does not match any of the allowed names, the call to StartFilter will fail with an error.

The parameter may be either empty or contain one or more EXE file names with complete paths. Separate names/paths should be separated by the LF character (numeric code 10).

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

IsFileFiltered Method (CBFilter Class)

This method checks whether a particular file or directory is covered by any filter rules.

Syntax

ANSI (Cross Platform)
bool IsFileFiltered(const char* lpszFileName);

Unicode (Windows)
INT IsFileFiltered(LPCWSTR lpszFileName);
bool cbfsfilter_cbfilter_isfilefiltered(void* lpObj, const char* lpszFileName);
bool IsFileFiltered(const QString& qsFileName);

Remarks

This method checks whether the file or directory specified by FileName is covered by any of the standard filter rules active currently (i.e., whether the class would fire its events for one or more kinds of filesystem operations performed on it). If the specified file or directory matches any of the active standard filter rules, this method returns true; otherwise, it returns false.

Applications should use this method anytime they want to create/open some file or directory from within an event handler. If this method returns true, then the file or directory must be created/opened using the class's CreateFileDirect method rather than the Windows API's CreateFile function, because the latter could trigger recursion and cause a system deadlock.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

NtStatusToWin32Error Method (CBFilter Class)

This method converts a native status code to a Win32 error code.

Syntax

ANSI (Cross Platform)
int NtStatusToWin32Error(int iStatus);

Unicode (Windows)
INT NtStatusToWin32Error(INT iStatus);
int cbfsfilter_cbfilter_ntstatustowin32error(void* lpObj, int iStatus);
int NtStatusToWin32Error(int iStatus);

Remarks

This method converts the native status code specified by Status to a Win32 error code. If the specified native status code does not map directly to a Win32 error code, this method returns ERROR_MR_MID_NOT_FOUND (317).

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

QueryFileInformationDirect Method (CBFilter Class)

This method returns various kinds of information about a file object.

Syntax

ANSI (Cross Platform)
int QueryFileInformationDirect(int64 lFileHandle, void* lpFileInformation, int lenFileInformation, int iFileInformationClass, int* iBytesTransferred);

Unicode (Windows)
INT QueryFileInformationDirect(LONG64 lFileHandle, LPVOID lpFileInformation, INT lenFileInformation, INT iFileInformationClass, INT*  iBytesTransferred);
int cbfsfilter_cbfilter_queryfileinformationdirect(void* lpObj, int64 lFileHandle, void* lpFileInformation, int lenFileInformation, int iFileInformationClass, int* iBytesTransferred);
int QueryFileInformationDirect(qint64 lFileHandle, void* qbaFileInformation, int iFileInformationClass, int* iBytesTransferred);

Remarks

Applications may call this method to query various kinds of information about the file or directory using the open handle. The method uses the NtQueryInformationFile Windows API function to retrieve the information.

The FileHandle parameter specifies the file that should be updated. The value passed for this parameter must be a file handle obtained from the CreateFileDirect method; please refer to its documentation for more information.

The InformationClass parameter specifies the class of information to be query. For the list of supported classes, please refer to the documentation of the Windows API's NtQueryInformationFile function.

FileInformation is a buffer that must contain the information queried. The exact size and format of the information depend on InformationClass and are described in the NtQueryInformationFile help topic.

BytesTrasferredThe actual bytes of information received on completion.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

QueryFileSecurityDirect Method (CBFilter Class)

This method retrieves security information of a file.

Syntax

ANSI (Cross Platform)
int QueryFileSecurityDirect(int64 lFileHandle, int iSecurityInformation, void* lpSecurityDescriptor, int lenSecurityDescriptor, int* iLengthNeeded);

Unicode (Windows)
INT QueryFileSecurityDirect(LONG64 lFileHandle, INT iSecurityInformation, LPVOID lpSecurityDescriptor, INT lenSecurityDescriptor, INT*  iLengthNeeded);
int cbfsfilter_cbfilter_queryfilesecuritydirect(void* lpObj, int64 lFileHandle, int iSecurityInformation, void* lpSecurityDescriptor, int lenSecurityDescriptor, int* iLengthNeeded);
int QueryFileSecurityDirect(qint64 lFileHandle, int iSecurityInformation, void* qbaSecurityDescriptor, int* iLengthNeeded);

Remarks

Applications may call this method to query security attributes of the file or directory using the open handle. The method uses the NtQuerySecurityObject Windows API function to change the security attributes.

The FileHandle parameter specifies the file that should be queried. The value passed for this parameter must be a file handle obtained from the CreateFileDirect method; please refer to its documentation for more information.

The SecurityInformation parameter specifies the information to be queried as a combination of one or more of the following:

  • OWNER_SECURITY_INFORMATION
  • GROUP_SECURITY_INFORMATION
  • DACL_SECURITY_INFORMATION
  • SACL_SECURITY_INFORMATION
Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to the memory buffer that receives the requested data. It is available only if the length of the buffer is greater than 0. The data must be formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to these articles for more information about self-relative security descriptors.

The LengthNeeded parameter points to a caller-allocated variable that receives the number of bytes required to store the copied security descriptor.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

RemoveVirtualFile Method (CBFilter Class)

This method removes a virtual file from the list of virtual entries.

Syntax

ANSI (Cross Platform)
bool RemoveVirtualFile(const char* lpszFileName);

Unicode (Windows)
INT RemoveVirtualFile(LPCWSTR lpszFileName);
bool cbfsfilter_cbfilter_removevirtualfile(void* lpObj, const char* lpszFileName);
bool RemoveVirtualFile(const QString& qsFileName);

Remarks

This method removes a previously added virtual file identified by FileName from the list of virtual entries, managed by the class.

The FileName parameter must contain the same value as the one used to add a virtual file earlier.

The method will return true if the file was found and removed from the list and false if the file was not found in the list. An error will be reported if removal of the file failed on the driver side.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ResetTimeout Method (CBFilter Class)

This method resets the timeout duration for the current event handler.

Syntax

ANSI (Cross Platform)
bool ResetTimeout(int iTimeout);

Unicode (Windows)
INT ResetTimeout(INT iTimeout);
bool cbfsfilter_cbfilter_resettimeout(void* lpObj, int iTimeout);
bool ResetTimeout(int iTimeout);

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the class that request processing is taking longer than expected.

If called successfully, this method returns true, and the current event handler's timeout timer is immediately reset to 0; when it reaches the number of milliseconds specified by Timeout, the driver will either "release" the underlying request and pass it onwards, or cancel it by reporting an error; whichever is most appropriate for the event in question. Please refer to the Timeouts topic for more information.

Passing 0 for Timeout disables the timeout timer for the current event handler, allowing it to take as long as it needs to complete.

Note: When several events are fired for the same file concurrently (if the SerializeAccess configuration setting is disabled), and ResetTimeout is called from one of the handlers of these events, this method will reset the timer for all currently executed event handlers.

Note: This method can be called only within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

SetFileInformationDirect Method (CBFilter Class)

This method sets the file information of a file opened using CreateFileDirect.

Syntax

ANSI (Cross Platform)
int SetFileInformationDirect(int64 lFileHandle, int iInformationClass, const char* lpFileInformation, int lenFileInformation);

Unicode (Windows)
INT SetFileInformationDirect(LONG64 lFileHandle, INT iInformationClass, LPCSTR lpFileInformation, INT lenFileInformation);
int cbfsfilter_cbfilter_setfileinformationdirect(void* lpObj, int64 lFileHandle, int iInformationClass, const char* lpFileInformation, int lenFileInformation);
int SetFileInformationDirect(qint64 lFileHandle, int iInformationClass, QByteArray qbaFileInformation);

Remarks

Applications may call this method to change various kinds of information about a file that was opened using the CreateFileDirect method.

The FileHandle parameter specifies the file that should be updated. The value passed for this parameter must be a file handle obtained from the CreateFileDirect method; please refer to its documentation for more information.

The InformationClass parameter specifies the class of information to be set. For the list of supported classes, please refer to the documentation of the Windows API's FltSetInformationFile function.

Note: Only a limited subset of classes comparing to similar functions like NtSetInformationFile or NtQueryInformationFile is supported by this function.

FileInformation is a buffer that must contain the information to be set. The exact size and format of the information depend on InformationClass and are described in the FltSetInformationFile help topic.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileSecurityDirect Method (CBFilter Class)

This method sets security information of a file.

Syntax

ANSI (Cross Platform)
int SetFileSecurityDirect(int64 lFileHandle, int iSecurityInformation, const char* lpSecurityDescriptor, int lenSecurityDescriptor);

Unicode (Windows)
INT SetFileSecurityDirect(LONG64 lFileHandle, INT iSecurityInformation, LPCSTR lpSecurityDescriptor, INT lenSecurityDescriptor);
int cbfsfilter_cbfilter_setfilesecuritydirect(void* lpObj, int64 lFileHandle, int iSecurityInformation, const char* lpSecurityDescriptor, int lenSecurityDescriptor);
int SetFileSecurityDirect(qint64 lFileHandle, int iSecurityInformation, QByteArray qbaSecurityDescriptor);

Remarks

Applications may call this method to set security attributes of the file or directory using the open handle. The method uses the NtSetSecurityObject Windows API function to query the security attributes.

The FileHandle parameter specifies the file that should be updated. The value passed for this parameter must be a file handle obtained from the CreateFileDirect method; please refer to its documentation for more information.

The SecurityInformation parameter indicates which pieces of security information must be set. This value is a bitfield; possible flags include (but are not limited to):

  • OWNER_SECURITY_INFORMATION
  • GROUP_SECURITY_INFORMATION
  • DACL_SECURITY_INFORMATION
  • SACL_SECURITY_INFORMATION
Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains data indicated by SecurityInformation. The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to those articles for more information about self-relative security descriptors.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileSizeDirect Method (CBFilter Class)

This method resizes a file by passing the request directly to the filesystem.

Syntax

ANSI (Cross Platform)
bool SetFileSizeDirect(int64 lFileHandle, int64 lSize);

Unicode (Windows)
INT SetFileSizeDirect(LONG64 lFileHandle, LONG64 lSize);
bool cbfsfilter_cbfilter_setfilesizedirect(void* lpObj, int64 lFileHandle, int64 lSize);
bool SetFileSizeDirect(qint64 lFileHandle, qint64 lSize);

Remarks

Applications can call this method in filesystem-related event handlers to resize a file without sending the request through the filesystem filter driver stack. If the file is resized successfully, this method returns true; otherwise, it returns false.

The FileHandle parameter specifies the file that should be resized. The value passed for this parameter must be a file handle obtained from the CreateFileDirect method; please refer to its documentation for more information.

The Size parameter specifies the new file size, in bytes.

To set file allocation size or valid file length, you may use the SetFileInformationDirect method.

Note: This method can be called only within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ShutdownSystem Method (CBFilter Class)

Shuts down or reboots the operating system.

Syntax

ANSI (Cross Platform)
bool ShutdownSystem(const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

Unicode (Windows)
INT ShutdownSystem(LPCWSTR lpszShutdownPrompt, INT iTimeout, BOOL bForceCloseApps, BOOL bReboot);
bool cbfsfilter_cbfilter_shutdownsystem(void* lpObj, const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);
bool ShutdownSystem(const QString& qsShutdownPrompt, int iTimeout, bool bForceCloseApps, bool bReboot);

Remarks

This method shuts down or (if Reboot is true) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns false, then this method will return false; otherwise, it returns true. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (true) or just shut down (false).

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

StartFilter Method (CBFilter Class)

This method starts filtering filesystem operations.

Syntax

ANSI (Cross Platform)
int StartFilter(int iTimeout);

Unicode (Windows)
INT StartFilter(INT iTimeout);
int cbfsfilter_cbfilter_startfilter(void* lpObj, int iTimeout);
int StartFilter(int iTimeout);

Remarks

This method attaches the filter, causing the class's system driver to start filtering filesystem operations according to the filter rules currently present. Rules can be added and removed both before and after this method is called, so long as the Initialize method is called before doing anything else.

This method can fail for a number of reasons, including (but not limited to) the following:

  • If the class's system driver has not been properly installed, or is awaiting a system reboot (as indicated by the return value of Install), this method fails with an ERROR_FILE_NOT_FOUND (2) error code.
  • If the Initialize method has not been called yet, this method fails with an ERROR_NOT_READY (21) error code.
  • If the filter is already Active, this method fails with an ERROR_CONNECTION_ACTIVE (1230) error code.
  • If an invalid value is passed for Timeout, this method fails with an ERROR_IMPLEMENTATION_LIMIT (1292) error code.

Timeout

Timeout specifies how many milliseconds the driver should wait for events to execute before releasing or cancelling the underlying OS requests; please refer to the Timeouts topic for more information. Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. When event timeouts are in effect, event handlers can call ResetTimeout to reset the timer if they require additional time to complete.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

StopFilter Method (CBFilter Class)

This method stops filtering filesystem operations.

Syntax

ANSI (Cross Platform)
int StopFilter();

Unicode (Windows)
INT StopFilter();
int cbfsfilter_cbfilter_stopfilter(void* lpObj);
int StopFilter();

Remarks

This method detaches the filter, causing the class's system driver to stop filtering filesystem operations. This method will block until all pending requests have been completed and the filter has been detached.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SuspendDefaultRules Method (CBFilter Class)

This method suspends all default rules until the application exits.

Syntax

ANSI (Cross Platform)
bool SuspendDefaultRules(const char* lpszProductGUID);

Unicode (Windows)
INT SuspendDefaultRules(LPCWSTR lpszProductGUID);
bool cbfsfilter_cbfilter_suspenddefaultrules(void* lpObj, const char* lpszProductGUID);
bool SuspendDefaultRules(const QString& qsProductGUID);

Remarks

This method suspends (i.e., deactivates) all default rules associated with the application identified by ProductGUID until the application exits. If the rules are suspended successfully, this method returns true; otherwise, it returns false.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the Initialize method.

When the application exits, the class's system driver will reactivate the suspended rules and start enforcing them once again.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

SuspendFileEvents Method (CBFilter Class)

This method suspends all events for a particular file or directory until all of its handles have been closed.

Syntax

ANSI (Cross Platform)
int SuspendFileEvents();

Unicode (Windows)
INT SuspendFileEvents();
int cbfsfilter_cbfilter_suspendfileevents(void* lpObj);
int SuspendFileEvents();

Remarks

Applications can call this method from an AfterCreateFile or AfterOpenFile event to suspend all further events for the file or directory that the event fired for. The suspension will remain in effect until all handles to said file or directory have been closed, at which point the class will once again fire events for it (if it is accessed again).

Typically, this method should be used only as a "last resort"; that is, when the application cannot achieve the same outcome through the use of more granular standard filter rules. Said another way, it is almost always more efficient for an application to exclude files or directories implicitly using standard filter rules, if possible, than it is to exclude them explicitly using this method.

Note: This method can be called only within the AfterCreateFile and AfterOpenFile events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ToggleProcessProtection Method (CBFilter Class)

This method enables or disables termination protection for the application.

Syntax

ANSI (Cross Platform)
bool ToggleProcessProtection(int bEnabled);

Unicode (Windows)
INT ToggleProcessProtection(BOOL bEnabled);
bool cbfsfilter_cbfilter_toggleprocessprotection(void* lpObj, int bEnabled);
bool ToggleProcessProtection(bool bEnabled);

Remarks

This method controls the termination protection mechanism, which applications can enable to prevent their process and threads from being terminated. If successful, this method returns true; otherwise, it returns false.

The Enabled parameter specifies whether termination protection should be enabled (true) or disabled (false); it is disabled by default. If termination protection is enabled, an application must disable it before attempting to exit.

Note: When developing a GUI-based application, please keep in mind that the termination protection mechanism does not intercept Windows' notifications like WM_CLOSE or WM_QUIT; applications must intercept and handle such messages themselves if they wish to protect their UI. Please refer to Microsoft's Window Notifications articles for more information.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Uninstall Method (CBFilter Class)

This method uninstalls the class's system driver.

Syntax

ANSI (Cross Platform)
bool Uninstall(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

Unicode (Windows)
INT Uninstall(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszInstalledPath, INT iFlags);
bool cbfsfilter_cbfilter_uninstall(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);
bool Uninstall(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsInstalledPath, int iFlags);

Remarks

This method is used to uninstall the class's system driver. If the system must be rebooted to complete the uninstallation process, this method returns true; otherwise, it returns false.

Important: To upgrade the class's driver, use only the Install method. Previously installed versions of the driver should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when Install was called; please refer to its documentation for more information.

Flags specifies which versions of the class's system driver should be uninstalled and which should be set by ORing together one or more of the following values:

UNINSTALL_VERSION_PREVIOUS0x00000001Uninstall modules from previous product versions.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_CURRENT0x00000002Uninstall modules from the current product version.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_ALL0x00000003Uninstall modules from all product versions.

Note: This functionality is only available in Windows.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

UpdateVirtualFile Method (CBFilter Class)

This method updates known information about a virtual file .

Syntax

ANSI (Cross Platform)
bool UpdateVirtualFile(const char* lpszFileName, int64 lCreationTime, int64 lLastAccessTime, int64 lLastWriteTime, int64 lChangeTime, int64 lSize, int iAttributes);

Unicode (Windows)
INT UpdateVirtualFile(LPCWSTR lpszFileName, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lLastWriteTime, LONG64 lChangeTime, LONG64 lSize, INT iAttributes);
bool cbfsfilter_cbfilter_updatevirtualfile(void* lpObj, const char* lpszFileName, int64 lCreationTime, int64 lLastAccessTime, int64 lLastWriteTime, int64 lChangeTime, int64 lSize, int iAttributes);
bool UpdateVirtualFile(const QString& qsFileName, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtLastWriteTime, QDateTime qdtChangeTime, qint64 lSize, int iAttributes);

Remarks

This method updates the information about the virtual file identified by FileName.

The FileName parameter must contain the same value as the one used to add a virtual file earlier.

CreationTime, LastAccessTime, LastWriteTime, ChangeTime should contain new time values for the file, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME; any of the time values may be 0 to indicate that the existing value of the corresponding time must remain unchanged.

Size must be set to the new size of the file to update the known file size or to -1 to indicate that the size didn't change.

Attributes must be set to new file's attributes. Set this parameter to 0 to indicate that the existing attributes must remain unchanged.

  • FILE_ATTRIBUTE_NORMAL: This attribute is valid only when used alone; it "resets" a file's attributes.
  • Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The method will return true if the file was found and updated and false if the file was not found in the list. An error will be reported if updating the file failed on the driver side.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AfterCanFileBeDeleted Event (CBFilter Class)

This event fires after the OS marks a file or directory for deletion or removes such a mark.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCanFileBeDeleted(CBFilterAfterCanFileBeDeletedEventParams *e);
typedef struct {
const char *FileName;
int RequestType;
int CanDelete;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterCanFileBeDeletedEventParams;
Unicode (Windows) virtual INT FireAfterCanFileBeDeleted(CBFilterAfterCanFileBeDeletedEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestType;
BOOL CanDelete;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterCanFileBeDeletedEventParams;
#define EID_CBFILTER_AFTERCANFILEBEDELETED 1

virtual INT CBFSFILTER_CALL FireAfterCanFileBeDeleted(LPWSTR &lpszFileName, INT &iRequestType, BOOL &bCanDelete, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterCanFileBeDeletedEventParams {
public:
  const QString &FileName();

  int RequestType();

  bool CanDelete();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCanFileBeDeleted(CBFilterAfterCanFileBeDeletedEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterCanFileBeDeleted(CBFilterAfterCanFileBeDeletedEventParams *e) {...}

Remarks

This event fires after the OS marks the file or directory specified by FileName for deletion or removes such a mark. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If the file or directory is marked for deletion, they will not be removed immediately but will actually be removed when the last handle is closed. Moreover, it is possible that a future call to a system function will remove the mark, so this event is not a final indicator that the file or directory will be deleted.

Files and directories can be deleted in two ways: (1) a file or directory can be opened with the FILE_FLAG_DELETE_ON_CLOSE flag, or (2) some process may call Windows API's NtSetInformationFile function with FILE_DISPOSITION_INFORMATION or FILE_DISPOSITION_INFORMATION_EX structure as a parameter.

If the file or directory is created or opened with the FILE_FLAG_DELETE_ON_CLOSE flag, this event is fired shortly after the AfterCreateFile or AfterOpenFile event.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

DEL_REQ_OPEN_FLAG0x1The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag

DEL_REQ_SET_DISPOSITION0x2The system has sent the IRP_MJ_SET_INFORMATION request with SetFileDisposition structure as a parameter.

This request usually is sent using the NtSetInformationFile() Windows native API function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_CAN_DELETE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The CanDelete parameter reflects whether the file or directory will be deleted.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterCleanupFile Event (CBFilter Class)

This event fires after a file or directory handle is closed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCleanupFile(CBFilterAfterCleanupFileEventParams *e);
typedef struct {
const char *FileName;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterCleanupFileEventParams;
Unicode (Windows) virtual INT FireAfterCleanupFile(CBFilterAfterCleanupFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterCleanupFileEventParams;
#define EID_CBFILTER_AFTERCLEANUPFILE 2

virtual INT CBFSFILTER_CALL FireAfterCleanupFile(LPWSTR &lpszFileName, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterCleanupFileEventParams {
public:
  const QString &FileName();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCleanupFile(CBFilterAfterCleanupFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterCleanupFile(CBFilterAfterCleanupFileEventParams *e) {...}

Remarks

This event fires after a handle to the file or directory specified by FileName is closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event differs from AfterCloseFile in that AfterCleanupFile fires immediately after an open handle to the specified file or directory is closed by a process, whereas AfterCloseFile may be fired much later when the OS decides that the file or directory can be formally closed.

Other events may fire for the file or directory in the time between when this event fires and when the AfterCloseFile event fires. For example, system components, such as the memory manager or cache manager, may cause the AfterReadFile and AfterWriteFile events to fire.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_CLEANUP flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterCloseEnumeration Event (CBFilter Class)

This event fires after a directory enumeration operation finishes.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCloseEnumeration(CBFilterAfterCloseEnumerationEventParams *e);
typedef struct {
const char *DirectoryName;
void *DirectoryContext;
void *HandleContext;
void *EnumerationContext;
int ResultCode; int reserved; } CBFilterAfterCloseEnumerationEventParams;
Unicode (Windows) virtual INT FireAfterCloseEnumeration(CBFilterAfterCloseEnumerationEventParams *e);
typedef struct {
LPCWSTR DirectoryName;
LPVOID DirectoryContext;
LPVOID HandleContext;
LPVOID EnumerationContext;
INT ResultCode; INT reserved; } CBFilterAfterCloseEnumerationEventParams;
#define EID_CBFILTER_AFTERCLOSEENUMERATION 3

virtual INT CBFSFILTER_CALL FireAfterCloseEnumeration(LPWSTR &lpszDirectoryName, LPVOID &lpDirectoryContext, LPVOID &lpHandleContext, LPVOID &lpEnumerationContext, INT &iResultCode);
class CBFilterAfterCloseEnumerationEventParams {
public:
  const QString &DirectoryName();

  void *DirectoryContext();

  void *HandleContext();

  void *EnumerationContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCloseEnumeration(CBFilterAfterCloseEnumerationEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterCloseEnumeration(CBFilterAfterCloseEnumerationEventParams *e) {...}

Remarks

This event fires after enumeration of the directory specified by DirectoryName finishes. For more information about the DirectoryName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_CLOSE flag (directory enumerations are typically closed immediately before a directory is closed).

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterCloseFile Event (CBFilter Class)

This event fires after a file or directory is closed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCloseFile(CBFilterAfterCloseFileEventParams *e);
typedef struct {
const char *FileName;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterCloseFileEventParams;
Unicode (Windows) virtual INT FireAfterCloseFile(CBFilterAfterCloseFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterCloseFileEventParams;
#define EID_CBFILTER_AFTERCLOSEFILE 4

virtual INT CBFSFILTER_CALL FireAfterCloseFile(LPWSTR &lpszFileName, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterCloseFileEventParams {
public:
  const QString &FileName();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCloseFile(CBFilterAfterCloseFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterCloseFile(CBFilterAfterCloseFileEventParams *e) {...}

Remarks

This event fires after the file or directory specified by FileName is closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_CLOSE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

If the file or directory was marked for deletion earlier, the AfterDeleteFile will fire shortly before this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterCreateFile Event (CBFilter Class)

This event fires after a file or directory is created.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCreateFile(CBFilterAfterCreateFileEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int Isolate;
const char *BackendFileName;
int DesiredAccess;
int Attributes;
int ShareMode;
int Options;
int CreateDisposition;
const void *SecurityDescriptor;
int Length;
int Status;
int CreationStatus;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterCreateFileEventParams;
Unicode (Windows) virtual INT FireAfterCreateFile(CBFilterAfterCreateFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
BOOL Isolate;
LPCWSTR BackendFileName;
INT DesiredAccess;
INT Attributes;
INT ShareMode;
INT Options;
INT CreateDisposition;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
INT CreationStatus;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterCreateFileEventParams;
#define EID_CBFILTER_AFTERCREATEFILE 5

virtual INT CBFSFILTER_CALL FireAfterCreateFile(LPWSTR &lpszFileName, INT &iExistingAttributes, BOOL &bIsolate, LPWSTR &lpszBackendFileName, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iCreationStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterCreateFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  bool Isolate();

  const QString &BackendFileName();

  int DesiredAccess();

  int Attributes();

  int ShareMode();

  int Options();

  int CreateDisposition();

  const void *SecurityDescriptor();

  int Length();

  int Status();
  void SetStatus(int iStatus);

  int CreationStatus();
  void SetCreationStatus(int iCreationStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCreateFile(CBFilterAfterCreateFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterCreateFile(CBFilterAfterCreateFileEventParams *e) {...}

Remarks

This event fires after the file or directory specified by FileName is created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or AfterOpenFile.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_CREATE flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory creation requests.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

If Isolate was set to true in the BeforeCreateFile or BeforeOpenFile events, the value of the Isolate and BackendFileName parameters in this event will contain the values initially set in those events. Additionally, if a file was added using the AddVirtualFile method Isolate will be true.

The DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE IRP).

DesiredAccess may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to true and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

CreateDisposition may contain one of the following values:

FILE_DISPOSITION_CREATE_NEW0x00000001Creates a new file, only if it does not already exist.

If the specified file exists, the operation fails with an "already exists" error.

FILE_DISPOSITION_CREATE_ALWAYS0x00000002Creates a new file, always.

If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.

FILE_DISPOSITION_OPEN_EXISTING0x00000003Opens a file, only if it exists

If the specified file does not exist, opening fails.

FILE_DISPOSITION_OPEN_ALWAYS0x00000004Opens a file, always.

If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.

FILE_DISPOSITION_TRUNCATE_EXISTING0x00000005Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the operation fails with a "file not found" error.

Options contains the flags that are described in the CreateOptions parameter of the native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to the native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request was for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present if it was specified by the calling process or if the existing filesystem entry is a directory.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE; Note: Because files can be deleted in different ways, do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the AfterCanFileBeDeleted event will fire after this event.

If the file is created with Extended Attributes passed in the request, the AfterSetEa event will fire after this event.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The CreationStatus parameter indicates whether the file was created or opened and can be one of the following values:

CREATION_STATUS_SUPERSEDED0x00000000An existing file was superseded by the new file.

The previous version of a file may still exist if it had hard links other than the name used in the operation.

CREATION_STATUS_OPENED0x00000001The file existed before the operation and was opened.

CREATION_STATUS_CREATED0x00000002The file didn't exist before the operation and was created.

CREATION_STATUS_OVERWRITTEN0x00000003The file exists, and its contents have been replaced.

CREATION_STATUS_EXISTS0x00000004The file existed before the operation, and no action was taken.

CREATION_STATUS_DOES_NOT_EXIST0x000000055The file did not exist before the operation, and no action was taken.

Applications may change this parameter's value if they want a different creation status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

When the ProcessFailedRequests property is enabled, this event may fire even if the specified file or directory has not been created or opened, in which case the Status parameter will be non-zero. When this occurs, applications must not alter the FileContext and HandleContext parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterCreateHardLink Event (CBFilter Class)

This event fires after a hard link is created.

Syntax

Remarks

This event fires after a hard link to the file specified by FileName is created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to Microsoft's Hard Links article for more information about hard links.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_CREATE_HARD_LINK flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The LinkName parameter reflects the name of the created hard link.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterDeleteFile Event (CBFilter Class)

This event fires after a file or directory is deleted.

Syntax

ANSI (Cross Platform)
virtual int FireAfterDeleteFile(CBFilterAfterDeleteFileEventParams *e);
typedef struct {
const char *FileName;
int RequestType;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterDeleteFileEventParams;
Unicode (Windows) virtual INT FireAfterDeleteFile(CBFilterAfterDeleteFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestType;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterDeleteFileEventParams;
#define EID_CBFILTER_AFTERDELETEFILE 7

virtual INT CBFSFILTER_CALL FireAfterDeleteFile(LPWSTR &lpszFileName, INT &iRequestType, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterDeleteFileEventParams {
public:
  const QString &FileName();

  int RequestType();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterDeleteFile(CBFilterAfterDeleteFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterDeleteFile(CBFilterAfterDeleteFileEventParams *e) {...}

Remarks

This event fires after the file or directory specified by FileName is deleted. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. More specifically, this event is fired after the final IRP_MJ_CLOSE IRP is processed by the filesystem (i.e., after the last handle to the file or directory is closed and the file or directory is gone) and before AfterCloseFile fires.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_DELETE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

DEL_REQ_OPEN_FLAG0x1The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag

DEL_REQ_SET_DISPOSITION0x2The system has sent the IRP_MJ_SET_INFORMATION request with SetFileDisposition structure as a parameter.

This request usually is sent using the NtSetInformationFile() Windows native API function.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterDeleteReparsePoint Event (CBFilter Class)

This event fires after the OS deletes a reparse point from a file or directory.

Syntax

ANSI (Cross Platform)
virtual int FireAfterDeleteReparsePoint(CBFilterAfterDeleteReparsePointEventParams *e);
typedef struct {
const char *FileName;
const void *ReparseBuffer;
int BufferLength;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterDeleteReparsePointEventParams;
Unicode (Windows) virtual INT FireAfterDeleteReparsePoint(CBFilterAfterDeleteReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCVOID ReparseBuffer;
INT BufferLength;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterDeleteReparsePointEventParams;
#define EID_CBFILTER_AFTERDELETEREPARSEPOINT 8

virtual INT CBFSFILTER_CALL FireAfterDeleteReparsePoint(LPWSTR &lpszFileName, LPVOID &lpReparseBuffer, INT &iBufferLength, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterDeleteReparsePointEventParams {
public:
  const QString &FileName();

  const void *ReparseBuffer();

  int BufferLength();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterDeleteReparsePoint(CBFilterAfterDeleteReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterDeleteReparsePoint(CBFilterAfterDeleteReparsePointEventParams *e) {...}

Remarks

This event fires after the OS deletes a reparse point from a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: The file or directory is not deleted, only a reparse point is.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_DELETE_REPARSE_POINT flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The ReparseBuffer parameter points to a memory buffer that specifies the known reparse point information. This information is provided for convenience. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterEnumerateDirectory Event (CBFilter Class)

This event fires after a directory entry is returned during directory enumeration.

Syntax

ANSI (Cross Platform)
virtual int FireAfterEnumerateDirectory(CBFilterAfterEnumerateDirectoryEventParams *e);
typedef struct {
const char *DirectoryName;
int Flags;
int Index;
char *FileName; int lenFileName;
int64 *pCreationTime;
int64 *pLastAccessTime;
int64 *pLastWriteTime;
int64 *pChangeTime;
int64 *pSize;
int64 *pAllocationSize;
int64 *pFileId;
int Attributes;
int Status;
void *DirectoryContext;
void *HandleContext;
void *EventContext;
void *EnumerationContext;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterAfterEnumerateDirectoryEventParams;
Unicode (Windows) virtual INT FireAfterEnumerateDirectory(CBFilterAfterEnumerateDirectoryEventParams *e);
typedef struct {
LPCWSTR DirectoryName;
INT Flags;
INT Index;
LPWSTR FileName; INT lenFileName;
LONG64 *pCreationTime;
LONG64 *pLastAccessTime;
LONG64 *pLastWriteTime;
LONG64 *pChangeTime;
LONG64 *pSize;
LONG64 *pAllocationSize;
LONG64 *pFileId;
INT Attributes;
INT Status;
LPVOID DirectoryContext;
LPVOID HandleContext;
LPVOID EventContext;
LPVOID EnumerationContext;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterAfterEnumerateDirectoryEventParams;
#define EID_CBFILTER_AFTERENUMERATEDIRECTORY 9

virtual INT CBFSFILTER_CALL FireAfterEnumerateDirectory(LPWSTR &lpszDirectoryName, INT &iFlags, INT &iIndex, LPWSTR &lpFileName, INT &lenFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, LONG64 &lSize, LONG64 &lAllocationSize, LONG64 &lFileId, INT &iAttributes, INT &iStatus, LPVOID &lpDirectoryContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, LPVOID &lpEnumerationContext, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterAfterEnumerateDirectoryEventParams {
public:
  const QString &DirectoryName();

  int Flags();

  int Index();

  const QString &FileName();
  bool SetFileName(const QString &lpFileName);

  const QDateTime &CreationTime();
  void SetCreationTime(const QDateTime &qdtCreationTime);

  const QDateTime &LastAccessTime();
  void SetLastAccessTime(const QDateTime &qdtLastAccessTime);

  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);

  const QDateTime &ChangeTime();
  void SetChangeTime(const QDateTime &qdtChangeTime);

  qint64 Size();
  void SetSize(qint64 lSize);

  qint64 AllocationSize();
  void SetAllocationSize(qint64 lAllocationSize);

  qint64 FileId();
  void SetFileId(qint64 lFileId);

  int Attributes();
  void SetAttributes(int iAttributes);

  int Status();
  void SetStatus(int iStatus);

  void *DirectoryContext();
  void SetDirectoryContext(void *lpDirectoryContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  void *EnumerationContext();
  void SetEnumerationContext(void *lpEnumerationContext);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterEnumerateDirectory(CBFilterAfterEnumerateDirectoryEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterEnumerateDirectory(CBFilterAfterEnumerateDirectoryEventParams *e) {...}

Remarks

This event fires after a directory entry (i.e., a file or subdirectory) is returned during enumeration of the directory specified by DirectoryName. For more information about the DirectoryName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the entry's metadata before it gets reported to the requestor or even to prevent the entry from being reported in the first place.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_ENUMERATE_DIRECTORY flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Flags parameter specifies supplementary information about enumeration. It is a combination of zero or more values:

FS_ENUM_RESTART_SCAN1The requestor specified that directory enumeration must be restarted.

FS_ENUM_RETURN_SINGLE_ENTRY2One entry should be returned.

FS_ENUM_INDEX_SPECIFIED4The requestor specified the index to start enumeration from.

If the Flags parameter contains FS_ENUM_INDEX_SPECIFIED, the Index parameter contains the index as provided by the OS.

The FileName parameter reflects the name of the directory entry. .

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters specify the entry's time values, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

The Size parameter specifies the size of the file, in bytes; it must always be 0 for subdirectories.

The AllocationSize parameter specifies the amount of space allocated for the file, in bytes; it must always be 0 for subdirectories.

The FileId parameter specifies the unique Id of the entry, as reported by the filesystem (or, for virtual files, by the application itself). This Id is used by the network redirector, and some third-party applications, to open files and directories by Id instead of by name. The root directory always uses the predefined Id 0x7FFFFFFFFFFFFFFF.

The Attributes parameter specifies the entry's attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration, respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the directory entry should actually be reported to the requestor; it is true by default. Setting this parameter to false will "hide" the directory entry (i.e., prevent it from being reported).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterFilterAttachToVolume Event (CBFilter Class)

This event fires after the filter attaches to a newly mounted filesystem volume.

Syntax

ANSI (Cross Platform)
virtual int FireAfterFilterAttachToVolume(CBFilterAfterFilterAttachToVolumeEventParams *e);
typedef struct {
const char *VolumeName;
const char *VolumeNameNT;
int ResultCode; int reserved; } CBFilterAfterFilterAttachToVolumeEventParams;
Unicode (Windows) virtual INT FireAfterFilterAttachToVolume(CBFilterAfterFilterAttachToVolumeEventParams *e);
typedef struct {
LPCWSTR VolumeName;
LPCWSTR VolumeNameNT;
INT ResultCode; INT reserved; } CBFilterAfterFilterAttachToVolumeEventParams;
#define EID_CBFILTER_AFTERFILTERATTACHTOVOLUME 10

virtual INT CBFSFILTER_CALL FireAfterFilterAttachToVolume(LPWSTR &lpszVolumeName, LPWSTR &lpszVolumeNameNT, INT &iResultCode);
class CBFilterAfterFilterAttachToVolumeEventParams {
public:
  const QString &VolumeName();

  const QString &VolumeNameNT();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterFilterAttachToVolume(CBFilterAfterFilterAttachToVolumeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterFilterAttachToVolume(CBFilterAfterFilterAttachToVolumeEventParams *e) {...}

Remarks

This event fires after the filter attaches to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

Note: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

Applications can use this event to add volume-specific rules for the volume that has been mounted (keeping in mind that this event does not fire for volumes that are already present when StartFilter is called). Applications that intend to do so must ensure that proper thread synchronization techniques are used when manipulating or enumerating the rule lists, because this event's handler will always execute in the context of some worker thread. Note: if a path-based rule is added or removed, such a path should use the value from VolumeNameNT to avoid a possible deadlock, which may occur during resolving a DOS name to the NT format.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterFilterDetachFromVolume Event (CBFilter Class)

This event fires after the filter detaches from a filesystem volume.

Syntax

ANSI (Cross Platform)
virtual int FireAfterFilterDetachFromVolume(CBFilterAfterFilterDetachFromVolumeEventParams *e);
typedef struct {
const char *VolumeName;
const char *VolumeNameNT;
int ResultCode; int reserved; } CBFilterAfterFilterDetachFromVolumeEventParams;
Unicode (Windows) virtual INT FireAfterFilterDetachFromVolume(CBFilterAfterFilterDetachFromVolumeEventParams *e);
typedef struct {
LPCWSTR VolumeName;
LPCWSTR VolumeNameNT;
INT ResultCode; INT reserved; } CBFilterAfterFilterDetachFromVolumeEventParams;
#define EID_CBFILTER_AFTERFILTERDETACHFROMVOLUME 11

virtual INT CBFSFILTER_CALL FireAfterFilterDetachFromVolume(LPWSTR &lpszVolumeName, LPWSTR &lpszVolumeNameNT, INT &iResultCode);
class CBFilterAfterFilterDetachFromVolumeEventParams {
public:
  const QString &VolumeName();

  const QString &VolumeNameNT();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterFilterDetachFromVolume(CBFilterAfterFilterDetachFromVolumeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterFilterDetachFromVolume(CBFilterAfterFilterDetachFromVolumeEventParams *e) {...}

Remarks

This event fires after the filter detaches from the filesystem volume specified by VolumeNameNT and, when possible, VolumeName, typically because of the volume being unmounted. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

Note: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

Applications should use this event to remove volume-specific rules for the volume that has been unmounted. Applications that intend to do so must ensure that proper thread synchronization techniques are used when manipulating or enumerating the rule lists, because this event's handler will always execute in the context of some worker thread. Note: if a path-based rule is added or removed, such a path should use the value from VolumeNameNT to avoid a possible deadlock, which may occur during resolving a DOS name to the NT format.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterFsctl Event (CBFilter Class)

This event fires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterFsctl(CBFilterAfterFsctlEventParams *e);
typedef struct {
const char *FileName;
int FsControlCode;
const void *InBuffer;
int InBufferLength;
int InBufferValidBytes;
void *OutBuffer;
int OutBufferLength;
int OutBufferValidBytes;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterFsctlEventParams;
Unicode (Windows) virtual INT FireAfterFsctl(CBFilterAfterFsctlEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FsControlCode;
LPCVOID InBuffer;
INT InBufferLength;
INT InBufferValidBytes;
LPVOID OutBuffer;
INT OutBufferLength;
INT OutBufferValidBytes;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterFsctlEventParams;
#define EID_CBFILTER_AFTERFSCTL 12

virtual INT CBFSFILTER_CALL FireAfterFsctl(LPWSTR &lpszFileName, INT &iFsControlCode, LPVOID &lpInBuffer, INT &iInBufferLength, INT &iInBufferValidBytes, LPVOID &lpOutBuffer, INT &iOutBufferLength, INT &iOutBufferValidBytes, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterFsctlEventParams {
public:
  const QString &FileName();

  int FsControlCode();

  const void *InBuffer();

  int InBufferLength();

  int InBufferValidBytes();

  void *OutBuffer();

  int OutBufferLength();

  int OutBufferValidBytes();
  void SetOutBufferValidBytes(int iOutBufferValidBytes);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterFsctl(CBFilterAfterFsctlEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterFsctl(CBFilterAfterFsctlEventParams *e) {...}

Remarks

This event fires after an IRP_MJ_FILE_SYSTEM_CONTROL (FSCTL) request is processed. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwFsControlFile function (kernel mode); please refer to Microsoft's documentation for more information.

Applications may use this event to modify the output data (if there are any) before the response is returned to the requestor. Applications that choose to do this must:

  1. copy no more than OutBufferLength bytes into OutBuffer; and
  2. update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_FSCTL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileName parameter reflects the file, directory, or volume targeted by the request.

The FsControlCode parameter reflects the requested filesystem control code (FSCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that contains the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation did not return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterGetFileSecurity Event (CBFilter Class)

This event fires after a file or directory's security attributes are retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireAfterGetFileSecurity(CBFilterAfterGetFileSecurityEventParams *e);
typedef struct {
const char *FileName;
int SecurityInformation;
void *SecurityDescriptor;
int Length;
int LengthNeeded;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterGetFileSecurityEventParams;
Unicode (Windows) virtual INT FireAfterGetFileSecurity(CBFilterAfterGetFileSecurityEventParams *e);
typedef struct {
LPCWSTR FileName;
INT SecurityInformation;
LPVOID SecurityDescriptor;
INT Length;
INT LengthNeeded;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterGetFileSecurityEventParams;
#define EID_CBFILTER_AFTERGETFILESECURITY 13

virtual INT CBFSFILTER_CALL FireAfterGetFileSecurity(LPWSTR &lpszFileName, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iLengthNeeded, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterGetFileSecurityEventParams {
public:
  const QString &FileName();

  int SecurityInformation();

  void *SecurityDescriptor();

  int Length();

  int LengthNeeded();
  void SetLengthNeeded(int iLengthNeeded);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterGetFileSecurity(CBFilterAfterGetFileSecurityEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterGetFileSecurity(CBFilterAfterGetFileSecurityEventParams *e) {...}

Remarks

This event fires after security attributes are retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: This event will not fire every time a file or directory is accessed. To check file security upon each access to a file or directory, implement the file create and open events and perform the necessary checks there instead.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_GET_SECURITY flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The SecurityInformation parameter indicates which pieces of security information were requested. Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that, if the request was successful, contains the requested security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

Applications that wish to modify the security information may do so by replacing the data in the SecurityDescriptor buffer. If the current Length is too small to accommodate the new security information, set LengthNeeded to the number of bytes necessary to hold the data and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterGetFileSizes Event (CBFilter Class)

This event fires after a file's size information is retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireAfterGetFileSizes(CBFilterAfterGetFileSizesEventParams *e);
typedef struct {
const char *FileName;
int64 *pSize;
int64 *pAllocationSize;
int Status;
void *FileContext;
void *HandleContext;
int ResultCode; int reserved; } CBFilterAfterGetFileSizesEventParams;
Unicode (Windows) virtual INT FireAfterGetFileSizes(CBFilterAfterGetFileSizesEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pSize;
LONG64 *pAllocationSize;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
INT ResultCode; INT reserved; } CBFilterAfterGetFileSizesEventParams;
#define EID_CBFILTER_AFTERGETFILESIZES 14

virtual INT CBFSFILTER_CALL FireAfterGetFileSizes(LPWSTR &lpszFileName, LONG64 &lSize, LONG64 &lAllocationSize, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, INT &iResultCode);
class CBFilterAfterGetFileSizesEventParams {
public:
  const QString &FileName();

  qint64 Size();
  void SetSize(qint64 lSize);

  qint64 AllocationSize();
  void SetAllocationSize(qint64 lAllocationSize);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterGetFileSizes(CBFilterAfterGetFileSizesEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterGetFileSizes(CBFilterAfterGetFileSizesEventParams *e) {...}

Remarks

This event fires after size information is retrieved for the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications that intend to modify a file's contents should use this event to modify the file's actual size or allocation size as necessary. Applications that make use of virtual files should use this event to report the size of the virtual files.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_GET_SIZES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Size parameter specifies the actual size of the file, in bytes.

The AllocationSize parameter specifies the amount of space allocated for the file, in bytes.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterGetReparsePoint Event (CBFilter Class)

This event fires after a file or directory's reparse point information is retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireAfterGetReparsePoint(CBFilterAfterGetReparsePointEventParams *e);
typedef struct {
const char *FileName;
void *ReparseBuffer;
int BufferLength;
int DataLength;
int LengthNeeded;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterGetReparsePointEventParams;
Unicode (Windows) virtual INT FireAfterGetReparsePoint(CBFilterAfterGetReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID ReparseBuffer;
INT BufferLength;
INT DataLength;
INT LengthNeeded;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterGetReparsePointEventParams;
#define EID_CBFILTER_AFTERGETREPARSEPOINT 15

virtual INT CBFSFILTER_CALL FireAfterGetReparsePoint(LPWSTR &lpszFileName, LPVOID &lpReparseBuffer, INT &iBufferLength, INT &iDataLength, INT &iLengthNeeded, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterGetReparsePointEventParams {
public:
  const QString &FileName();

  void *ReparseBuffer();

  int BufferLength();

  int DataLength();
  void SetDataLength(int iDataLength);

  int LengthNeeded();
  void SetLengthNeeded(int iLengthNeeded);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterGetReparsePoint(CBFilterAfterGetReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterGetReparsePoint(CBFilterAfterGetReparsePointEventParams *e) {...}

Remarks

This event fires after reparse point information is retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_GET_REPARSE_POINT flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The ReparseBuffer parameter points to a memory buffer that, if the request was successful, contains the requested reparse point information. The DataLength parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

Applications that wish to modify the reparse point information may do so by replacing the data in the ReparseBuffer buffer. If the current BufferLength is too small to accommodate the new information, the application should write as much data as possible, set LengthNeeded appropriately, and return the STATUS_BUFFER_OVERFLOW status code via Status.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Depending on how the request originator accessed the specified file or directory, it may or may not currently be open. The FileContext and HandleContext parameters will be absent if it is not open, in which case they will be NULL.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterIoctl Event (CBFilter Class)

This event fires after an IRP_MJ_DEVICE_CONTROL request is processed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterIoctl(CBFilterAfterIoctlEventParams *e);
typedef struct {
const char *FileName;
int IoControlCode;
const void *InBuffer;
int InBufferLength;
int InBufferValidBytes;
void *OutBuffer;
int OutBufferLength;
int OutBufferValidBytes;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterIoctlEventParams;
Unicode (Windows) virtual INT FireAfterIoctl(CBFilterAfterIoctlEventParams *e);
typedef struct {
LPCWSTR FileName;
INT IoControlCode;
LPCVOID InBuffer;
INT InBufferLength;
INT InBufferValidBytes;
LPVOID OutBuffer;
INT OutBufferLength;
INT OutBufferValidBytes;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterIoctlEventParams;
#define EID_CBFILTER_AFTERIOCTL 16

virtual INT CBFSFILTER_CALL FireAfterIoctl(LPWSTR &lpszFileName, INT &iIoControlCode, LPVOID &lpInBuffer, INT &iInBufferLength, INT &iInBufferValidBytes, LPVOID &lpOutBuffer, INT &iOutBufferLength, INT &iOutBufferValidBytes, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterIoctlEventParams {
public:
  const QString &FileName();

  int IoControlCode();

  const void *InBuffer();

  int InBufferLength();

  int InBufferValidBytes();

  void *OutBuffer();

  int OutBufferLength();

  int OutBufferValidBytes();
  void SetOutBufferValidBytes(int iOutBufferValidBytes);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterIoctl(CBFilterAfterIoctlEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterIoctl(CBFilterAfterIoctlEventParams *e) {...}

Remarks

This event fires after an IRP_MJ_DEVICE_CONTROL (IOCTL) request is processed. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwDeviceIoControlFile function (kernel mode). Please refer to Microsoft's documentation for more information.

Applications may use this event to modify the output data (if there are any) before the response is returned to the requestor. Applications that choose to do this must:

  1. copy no more than OutBufferLength bytes into OutBuffer; and
  2. update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_IOCTL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileName parameter reflects the file, directory, or volume targeted by the request.

The IoControlCode parameter reflects the requested I/O control code (IOCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that contains the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation did not return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterLock Event (CBFilter Class)

This event fires after a range of bytes in a file is locked.

Syntax

ANSI (Cross Platform)
virtual int FireAfterLock(CBFilterAfterLockEventParams *e);
typedef struct {
const char *FileName;
int64 Offset;
int64 Length;
int64 Key;
int FailImmediately;
int ExclusiveLock;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterLockEventParams;
Unicode (Windows) virtual INT FireAfterLock(CBFilterAfterLockEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Offset;
LONG64 Length;
LONG64 Key;
BOOL FailImmediately;
BOOL ExclusiveLock;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterLockEventParams;
#define EID_CBFILTER_AFTERLOCK 17

virtual INT CBFSFILTER_CALL FireAfterLock(LPWSTR &lpszFileName, LONG64 &lOffset, LONG64 &lLength, LONG64 &lKey, BOOL &bFailImmediately, BOOL &bExclusiveLock, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterLockEventParams {
public:
  const QString &FileName();

  qint64 Offset();

  qint64 Length();

  qint64 Key();

  bool FailImmediately();

  bool ExclusiveLock();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterLock(CBFilterAfterLockEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterLock(CBFilterAfterLockEventParams *e) {...}

Remarks

This event fires after a range of bytes in the file specified by FileName is locked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This request is made either by the OS, or on behalf of a user mode application that called the Windows API's LockFile or LockFileEx function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Offset parameter reflects the byte offset where the byte range lock starts.

The Length parameter reflects the length of the byte range lock.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock in later unlock-by-key requests.

The FailImmediately parameter indicates whether the request was to fail if the lock could not be granted immediately.

The ExclusiveLock parameter indicates whether the byte range lock was to be exclusive (true) or shared (false).

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterOpenFile Event (CBFilter Class)

This event fires after a file or directory is opened.

Syntax

ANSI (Cross Platform)
virtual int FireAfterOpenFile(CBFilterAfterOpenFileEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int Isolate;
const char *BackendFileName;
int DesiredAccess;
int Attributes;
int ShareMode;
int Options;
int CreateDisposition;
const void *SecurityDescriptor;
int Length;
int Status;
int CreationStatus;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterOpenFileEventParams;
Unicode (Windows) virtual INT FireAfterOpenFile(CBFilterAfterOpenFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
BOOL Isolate;
LPCWSTR BackendFileName;
INT DesiredAccess;
INT Attributes;
INT ShareMode;
INT Options;
INT CreateDisposition;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
INT CreationStatus;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterOpenFileEventParams;
#define EID_CBFILTER_AFTEROPENFILE 18

virtual INT CBFSFILTER_CALL FireAfterOpenFile(LPWSTR &lpszFileName, INT &iExistingAttributes, BOOL &bIsolate, LPWSTR &lpszBackendFileName, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iCreationStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterOpenFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  bool Isolate();

  const QString &BackendFileName();

  int DesiredAccess();

  int Attributes();

  int ShareMode();

  int Options();

  int CreateDisposition();

  const void *SecurityDescriptor();

  int Length();

  int Status();
  void SetStatus(int iStatus);

  int CreationStatus();
  void SetCreationStatus(int iCreationStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterOpenFile(CBFilterAfterOpenFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterOpenFile(CBFilterAfterOpenFileEventParams *e) {...}

Remarks

This event fires after the file or directory specified by FileName is opened. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or AfterCreateFile.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_OPEN flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory open requests.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

If Isolate was set to true in the BeforeCreateFile or BeforeOpenFile events, the value of the Isolate and BackendFileName parameters in this event will contain the values initially set in those events. Additionally, if a file was added using the AddVirtualFile method Isolate will be true.

The DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE IRP).

DesiredAccess may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to true and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

CreateDisposition may contain one of the following values:

FILE_DISPOSITION_CREATE_NEW0x00000001Creates a new file, only if it does not already exist.

If the specified file exists, the operation fails with an "already exists" error.

FILE_DISPOSITION_CREATE_ALWAYS0x00000002Creates a new file, always.

If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.

FILE_DISPOSITION_OPEN_EXISTING0x00000003Opens a file, only if it exists

If the specified file does not exist, opening fails.

FILE_DISPOSITION_OPEN_ALWAYS0x00000004Opens a file, always.

If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.

FILE_DISPOSITION_TRUNCATE_EXISTING0x00000005Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the operation fails with a "file not found" error.

Options contains the flags that are described in the CreateOptions parameter of the native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to the native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request was for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present if it was specified by the calling process or if the existing filesystem entry is a directory.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE; Note: Because files can be deleted in different ways, do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the AfterCanFileBeDeleted event will fire after this event.

If the file is opened with extended attributes passed in the request, the AfterSetEa event will fire after this event.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The CreationStatus parameter indicates whether the file was created or opened and can be one of the following values:

CREATION_STATUS_SUPERSEDED0x00000000An existing file was superseded by the new file.

The previous version of a file may still exist if it had hard links other than the name used in the operation.

CREATION_STATUS_OPENED0x00000001The file existed before the operation and was opened.

CREATION_STATUS_CREATED0x00000002The file didn't exist before the operation and was created.

CREATION_STATUS_OVERWRITTEN0x00000003The file exists, and its contents have been replaced.

CREATION_STATUS_EXISTS0x00000004The file existed before the operation, and no action was taken.

CREATION_STATUS_DOES_NOT_EXIST0x000000055The file did not exist before the operation, and no action was taken.

Applications may change this parameter's value if they want a different creation status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

When the ProcessFailedRequests property is enabled, this event may fire even if the specified file or directory has not been created or opened, in which case the Status parameter will be non-zero. When this occurs, applications must not alter the FileContext and HandleContext parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterQueryEa Event (CBFilter Class)

This event fires after information about extended attributes of a file is retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireAfterQueryEa(CBFilterAfterQueryEaEventParams *e);
typedef struct {
const char *FileName;
void *Buffer;
int BufferLength;
int ReturnSingleEntry;
const void *EaList;
int EaListLength;
int EaIndex;
int RestartScan;
int LengthReturned;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterQueryEaEventParams;
Unicode (Windows) virtual INT FireAfterQueryEa(CBFilterAfterQueryEaEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID Buffer;
INT BufferLength;
BOOL ReturnSingleEntry;
LPCVOID EaList;
INT EaListLength;
INT EaIndex;
BOOL RestartScan;
INT LengthReturned;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterQueryEaEventParams;
#define EID_CBFILTER_AFTERQUERYEA 19

virtual INT CBFSFILTER_CALL FireAfterQueryEa(LPWSTR &lpszFileName, LPVOID &lpBuffer, INT &iBufferLength, BOOL &bReturnSingleEntry, LPVOID &lpEaList, INT &iEaListLength, INT &iEaIndex, BOOL &bRestartScan, INT &iLengthReturned, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterQueryEaEventParams {
public:
  const QString &FileName();

  void *Buffer();

  int BufferLength();

  bool ReturnSingleEntry();

  const void *EaList();

  int EaListLength();

  int EaIndex();

  bool RestartScan();

  int LengthReturned();
  void SetLengthReturned(int iLengthReturned);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterQueryEa(CBFilterAfterQueryEaEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterQueryEa(CBFilterAfterQueryEaEventParams *e) {...}

Remarks

This event fires after information about extended attributes of the file specified by FileName is retrieved using the ZwQueryEaFile or FltQueryEaFile function of the system API. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_QUERY_EA flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the requested information. The data in the buffer are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The Length parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

ReturnSingleEntry specifies that the filesystem had to return only the first entry it has found.

EaList is an optional parameter that points to a caller-supplied memory buffer specifying the extended attributes to be queried. The data in the buffer are formatted as a FILE_GET_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The EaListLength parameter reflects the length of this data, in bytes. If the caller of the FltQueryEaFile function did not specify any value, it will contain 0.

EaIndex is an optional parameter that specifies the starting index of the attribute, information about which was requested. This parameter is ignored by the filesystem if EaList points to a nonempty list. If the caller of the FltQueryEaFile function did not specify any value, the parameter will contain -1.

The RestartScan parameter instructs the filesystem to restart enumeration of extended attributes from the first entry. If the parameter is false, retrieval of the extended attributes is resumed by the filesystem after a previous request.

LengthReturned is an optional parameter that contains the size, in bytes, of the information, returned in the Buffer.

A handler may modify the contents of the Buffer given that the size of the modified data does not exceed the length of the buffer. When modifying the data, a handler should update LengthReturned accordingly.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterQueryFileInfo Event (CBFilter Class)

This event fires after information about a file or directory is retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireAfterQueryFileInfo(CBFilterAfterQueryFileInfoEventParams *e);
typedef struct {
const char *FileName;
int FileInformationClass;
void *Buffer;
int BufferLength;
int ValidBytes;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterQueryFileInfoEventParams;
Unicode (Windows) virtual INT FireAfterQueryFileInfo(CBFilterAfterQueryFileInfoEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FileInformationClass;
LPVOID Buffer;
INT BufferLength;
INT ValidBytes;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterQueryFileInfoEventParams;
#define EID_CBFILTER_AFTERQUERYFILEINFO 20

virtual INT CBFSFILTER_CALL FireAfterQueryFileInfo(LPWSTR &lpszFileName, INT &iFileInformationClass, LPVOID &lpBuffer, INT &iBufferLength, INT &iValidBytes, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterQueryFileInfoEventParams {
public:
  const QString &FileName();

  int FileInformationClass();

  void *Buffer();

  int BufferLength();

  int ValidBytes();
  void SetValidBytes(int iValidBytes);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterQueryFileInfo(CBFilterAfterQueryFileInfoEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterQueryFileInfo(CBFilterAfterQueryFileInfoEventParams *e) {...}

Remarks

This event fires after information about the file or directory specified by FileName is retrieved. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtQueryInformationFile function.

Applications may use this event to modify the output data before the response is returned to the requestor. Applications that choose to do this must:

  1. copy no more than BufferLength bytes into Buffer; and
  2. update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_QUERY_FILE_INFO flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileInformationClass parameter indicates what kind of file information was requested. Please refer to the NtQueryInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the requested file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtQueryInformationFile function's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterReadFile Event (CBFilter Class)

This event fires after data are read from a file.

Syntax

ANSI (Cross Platform)
virtual int FireAfterReadFile(CBFilterAfterReadFileEventParams *e);
typedef struct {
const char *FileName;
int64 Position;
void *Buffer;
int BufferLength;
int BytesToRead;
int Reserved;
int Direction;
int BytesRead;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterReadFileEventParams;
Unicode (Windows) virtual INT FireAfterReadFile(CBFilterAfterReadFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Position;
LPVOID Buffer;
INT BufferLength;
INT BytesToRead;
INT Reserved;
INT Direction;
INT BytesRead;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterReadFileEventParams;
#define EID_CBFILTER_AFTERREADFILE 21

virtual INT CBFSFILTER_CALL FireAfterReadFile(LPWSTR &lpszFileName, LONG64 &lPosition, LPVOID &lpBuffer, INT &iBufferLength, INT &iBytesToRead, INT &iReserved, INT &iDirection, INT &iBytesRead, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterReadFileEventParams {
public:
  const QString &FileName();

  qint64 Position();

  void *Buffer();

  int BufferLength();

  int BytesToRead();

  int Reserved();

  int Direction();

  int BytesRead();
  void SetBytesRead(int iBytesRead);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterReadFile(CBFilterAfterReadFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterReadFile(CBFilterAfterReadFileEventParams *e) {...}

Remarks

This event fires after data are read from the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the data that were read from the file before it is returned to the requestor. Applications that choose to do this must:

  1. enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires);
  2. copy no more than BytesToRead bytes into Buffer; and
  3. update the BytesRead parameter's value afterward so that it correctly reflects the amount of data in Buffer.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_READ flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Position parameter reflects the byte offset in the file at which reading started.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the data that were read from the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToRead parameter reflects how many bytes were to be read from the file (i.e., how many bytes the requestor expects will be read).

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the user mode application <--> filesystem direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the user mode application <--> system cache direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the system cache <--> filesystem direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the system component <--> system cache direction.

The BytesRead parameter specifies how many bytes were actually read from the file, and thus the length of the data in Buffer. This parameter's value must not exceed BufferLength (and should not exceed BytesToRead; please refer to BeforeReadFile for more information).

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterRenameOrMoveFile Event (CBFilter Class)

This event fires after a file or directory is renamed or moved.

Syntax

ANSI (Cross Platform)
virtual int FireAfterRenameOrMoveFile(CBFilterAfterRenameOrMoveFileEventParams *e);
typedef struct {
const char *FileName;
const char *NewFileName;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterRenameOrMoveFileEventParams;
Unicode (Windows) virtual INT FireAfterRenameOrMoveFile(CBFilterAfterRenameOrMoveFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCWSTR NewFileName;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterRenameOrMoveFileEventParams;
#define EID_CBFILTER_AFTERRENAMEORMOVEFILE 22

virtual INT CBFSFILTER_CALL FireAfterRenameOrMoveFile(LPWSTR &lpszFileName, LPWSTR &lpszNewFileName, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterRenameOrMoveFileEventParams {
public:
  const QString &FileName();

  const QString &NewFileName();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterRenameOrMoveFile(CBFilterAfterRenameOrMoveFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterRenameOrMoveFile(CBFilterAfterRenameOrMoveFileEventParams *e) {...}

Remarks

This event fires after the file or directory specified by FileName is renamed or moved to NewFileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_RENAME flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

A rule's mask is matched against both previous and new file names, and the event will fire when either of the names matches the mask.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetAllocationSize Event (CBFilter Class)

This event fires after a file's allocation size is changed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetAllocationSize(CBFilterAfterSetAllocationSizeEventParams *e);
typedef struct {
const char *FileName;
int64 AllocationSize;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetAllocationSizeEventParams;
Unicode (Windows) virtual INT FireAfterSetAllocationSize(CBFilterAfterSetAllocationSizeEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 AllocationSize;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetAllocationSizeEventParams;
#define EID_CBFILTER_AFTERSETALLOCATIONSIZE 23

virtual INT CBFSFILTER_CALL FireAfterSetAllocationSize(LPWSTR &lpszFileName, LONG64 &lAllocationSize, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetAllocationSizeEventParams {
public:
  const QString &FileName();

  qint64 AllocationSize();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetAllocationSize(CBFilterAfterSetAllocationSizeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetAllocationSize(CBFilterAfterSetAllocationSizeEventParams *e) {...}

Remarks

This event fires after the allocation size of the file specified by FileName is changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_SIZES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The AllocationSize parameter reflects the new allocation size, in bytes. A file's allocation size is typically larger than its actual size because filesystem operations often reserve space on disk before writing additional data to a file.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetEa Event (CBFilter Class)

This event fires after extended attributes of a file are changed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetEa(CBFilterAfterSetEaEventParams *e);
typedef struct {
const char *FileName;
const void *Buffer;
int BufferLength;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetEaEventParams;
Unicode (Windows) virtual INT FireAfterSetEa(CBFilterAfterSetEaEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCVOID Buffer;
INT BufferLength;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetEaEventParams;
#define EID_CBFILTER_AFTERSETEA 24

virtual INT CBFSFILTER_CALL FireAfterSetEa(LPWSTR &lpszFileName, LPVOID &lpBuffer, INT &iBufferLength, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetEaEventParams {
public:
  const QString &FileName();

  const void *Buffer();

  int BufferLength();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetEa(CBFilterAfterSetEaEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetEa(CBFilterAfterSetEaEventParams *e) {...}

Remarks

This event fires after extended attributes are changed for the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If the file is created or opened with extended attributes passed in the request, this event will fire shortly after the AfterCreateFile or AfterOpenFile event.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_EA flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Buffer parameter points to a memory buffer that specifies the extended attribute information. The Length parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetFileAttributes Event (CBFilter Class)

This event fires after a file or directory's attributes or times are changed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetFileAttributes(CBFilterAfterSetFileAttributesEventParams *e);
typedef struct {
const char *FileName;
int64 CreationTime;
int64 LastAccessTime;
int64 LastWriteTime;
int64 ChangeTime;
int Attributes;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetFileAttributesEventParams;
Unicode (Windows) virtual INT FireAfterSetFileAttributes(CBFilterAfterSetFileAttributesEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 CreationTime;
LONG64 LastAccessTime;
LONG64 LastWriteTime;
LONG64 ChangeTime;
INT Attributes;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetFileAttributesEventParams;
#define EID_CBFILTER_AFTERSETFILEATTRIBUTES 25

virtual INT CBFSFILTER_CALL FireAfterSetFileAttributes(LPWSTR &lpszFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, INT &iAttributes, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetFileAttributesEventParams {
public:
  const QString &FileName();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastWriteTime();

  const QDateTime &ChangeTime();

  int Attributes();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetFileAttributes(CBFilterAfterSetFileAttributesEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetFileAttributes(CBFilterAfterSetFileAttributesEventParams *e) {...}

Remarks

This event fires after the attributes or times of the file or directory specified by FileName are changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_ATTRIBUTES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters reflect the new time values, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. A value of 0 indicates that the corresponding time value was not included in the request.

The Attributes parameter reflects the new attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetFileInfo Event (CBFilter Class)

This event fires after information about a file or directory is changed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetFileInfo(CBFilterAfterSetFileInfoEventParams *e);
typedef struct {
const char *FileName;
int FileInformationClass;
const void *Buffer;
int BufferLength;
int ValidBytes;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetFileInfoEventParams;
Unicode (Windows) virtual INT FireAfterSetFileInfo(CBFilterAfterSetFileInfoEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FileInformationClass;
LPCVOID Buffer;
INT BufferLength;
INT ValidBytes;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetFileInfoEventParams;
#define EID_CBFILTER_AFTERSETFILEINFO 26

virtual INT CBFSFILTER_CALL FireAfterSetFileInfo(LPWSTR &lpszFileName, INT &iFileInformationClass, LPVOID &lpBuffer, INT &iBufferLength, INT &iValidBytes, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetFileInfoEventParams {
public:
  const QString &FileName();

  int FileInformationClass();

  const void *Buffer();

  int BufferLength();

  int ValidBytes();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetFileInfo(CBFilterAfterSetFileInfoEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetFileInfo(CBFilterAfterSetFileInfoEventParams *e) {...}

Remarks

This event fires after information about the file or directory specified by FileName is changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtSetInformationFile function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_FILE_INFO flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileInformationClass parameter indicates what kind of file information was set. Please refer to the NtSetInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the new file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtSetInformationFile function's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetFileSecurity Event (CBFilter Class)

This event fires after a file or directory's security attributes are changed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetFileSecurity(CBFilterAfterSetFileSecurityEventParams *e);
typedef struct {
const char *FileName;
int SecurityInformation;
const void *SecurityDescriptor;
int Length;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetFileSecurityEventParams;
Unicode (Windows) virtual INT FireAfterSetFileSecurity(CBFilterAfterSetFileSecurityEventParams *e);
typedef struct {
LPCWSTR FileName;
INT SecurityInformation;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetFileSecurityEventParams;
#define EID_CBFILTER_AFTERSETFILESECURITY 27

virtual INT CBFSFILTER_CALL FireAfterSetFileSecurity(LPWSTR &lpszFileName, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetFileSecurityEventParams {
public:
  const QString &FileName();

  int SecurityInformation();

  const void *SecurityDescriptor();

  int Length();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetFileSecurity(CBFilterAfterSetFileSecurityEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetFileSecurity(CBFilterAfterSetFileSecurityEventParams *e) {...}

Remarks

This event fires after security attributes are changed for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_SECURITY flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, were to be set. Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the new security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetFileSize Event (CBFilter Class)

This event fires after a file is resized.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetFileSize(CBFilterAfterSetFileSizeEventParams *e);
typedef struct {
const char *FileName;
int64 Size;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetFileSizeEventParams;
Unicode (Windows) virtual INT FireAfterSetFileSize(CBFilterAfterSetFileSizeEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Size;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetFileSizeEventParams;
#define EID_CBFILTER_AFTERSETFILESIZE 28

virtual INT CBFSFILTER_CALL FireAfterSetFileSize(LPWSTR &lpszFileName, LONG64 &lSize, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetFileSizeEventParams {
public:
  const QString &FileName();

  qint64 Size();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetFileSize(CBFilterAfterSetFileSizeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetFileSize(CBFilterAfterSetFileSizeEventParams *e) {...}

Remarks

This event fires after the file specified by FileName is resized, whether explicitly (e.g., truncation) or implicitly (i.e., as data are appended). For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_SIZES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Size parameter reflects the new file size, in bytes.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterSetReparsePoint Event (CBFilter Class)

This event fires after the OS creates or updates a reparse point on a file or directory.

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetReparsePoint(CBFilterAfterSetReparsePointEventParams *e);
typedef struct {
const char *FileName;
int64 ReparseTag;
const void *ReparseBuffer;
int BufferLength;
int DataLength;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterSetReparsePointEventParams;
Unicode (Windows) virtual INT FireAfterSetReparsePoint(CBFilterAfterSetReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 ReparseTag;
LPCVOID ReparseBuffer;
INT BufferLength;
INT DataLength;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterSetReparsePointEventParams;
#define EID_CBFILTER_AFTERSETREPARSEPOINT 29

virtual INT CBFSFILTER_CALL FireAfterSetReparsePoint(LPWSTR &lpszFileName, LONG64 &lReparseTag, LPVOID &lpReparseBuffer, INT &iBufferLength, INT &iDataLength, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterSetReparsePointEventParams {
public:
  const QString &FileName();

  qint64 ReparseTag();

  const void *ReparseBuffer();

  int BufferLength();

  int DataLength();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetReparsePoint(CBFilterAfterSetReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterSetReparsePoint(CBFilterAfterSetReparsePointEventParams *e) {...}

Remarks

This event fires after the OS creates or updates a reparse point on a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_SET_REPARSE_POINT flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The ReparseTag parameter contains the reparse tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; the class extracts it and provides it separately for convenience.

The ReparseBuffer parameter points to a memory buffer that specifies the new reparse point information. The DataLength parameter reflects the length of the data contained in the buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterUnlockAll Event (CBFilter Class)

This event fires after all locked byte ranges in a file are unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireAfterUnlockAll(CBFilterAfterUnlockAllEventParams *e);
typedef struct {
const char *FileName;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterUnlockAllEventParams;
Unicode (Windows) virtual INT FireAfterUnlockAll(CBFilterAfterUnlockAllEventParams *e);
typedef struct {
LPCWSTR FileName;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterUnlockAllEventParams;
#define EID_CBFILTER_AFTERUNLOCKALL 30

virtual INT CBFSFILTER_CALL FireAfterUnlockAll(LPWSTR &lpszFileName, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterUnlockAllEventParams {
public:
  const QString &FileName();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterUnlockAll(CBFilterAfterUnlockAllEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterUnlockAll(CBFilterAfterUnlockAllEventParams *e) {...}

Remarks

This event fires after all locked byte ranges in the file specified by FileName are unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterUnlockAllByKey Event (CBFilter Class)

This event fires after all locked byte ranges in a file, associated with a particular key, are unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireAfterUnlockAllByKey(CBFilterAfterUnlockAllByKeyEventParams *e);
typedef struct {
const char *FileName;
int64 Key;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterUnlockAllByKeyEventParams;
Unicode (Windows) virtual INT FireAfterUnlockAllByKey(CBFilterAfterUnlockAllByKeyEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Key;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterUnlockAllByKeyEventParams;
#define EID_CBFILTER_AFTERUNLOCKALLBYKEY 31

virtual INT CBFSFILTER_CALL FireAfterUnlockAllByKey(LPWSTR &lpszFileName, LONG64 &lKey, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterUnlockAllByKeyEventParams {
public:
  const QString &FileName();

  qint64 Key();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterUnlockAllByKey(CBFilterAfterUnlockAllByKeyEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterUnlockAllByKey(CBFilterAfterUnlockAllByKeyEventParams *e) {...}

Remarks

This event fires after all locked byte ranges in the file specified by FileName, and associated with the specified Key, are unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Key parameter contains the key value specified when the byte ranges were locked. Please refer to the AfterLock event's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterUnlockSingle Event (CBFilter Class)

This event fires after a particular locked byte range in a file is unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireAfterUnlockSingle(CBFilterAfterUnlockSingleEventParams *e);
typedef struct {
const char *FileName;
int64 Offset;
int64 Length;
int64 Key;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterUnlockSingleEventParams;
Unicode (Windows) virtual INT FireAfterUnlockSingle(CBFilterAfterUnlockSingleEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Offset;
LONG64 Length;
LONG64 Key;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterUnlockSingleEventParams;
#define EID_CBFILTER_AFTERUNLOCKSINGLE 32

virtual INT CBFSFILTER_CALL FireAfterUnlockSingle(LPWSTR &lpszFileName, LONG64 &lOffset, LONG64 &lLength, LONG64 &lKey, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterUnlockSingleEventParams {
public:
  const QString &FileName();

  qint64 Offset();

  qint64 Length();

  qint64 Key();

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterUnlockSingle(CBFilterAfterUnlockSingleEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterUnlockSingle(CBFilterAfterUnlockSingleEventParams *e) {...}

Remarks

This event fires after a particular locked byte range in the file specified by FileName is unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Offset, Length, and Key parameters contain the starting byte offset, length, and key values (respectively) specified when the byte range was locked. Please refer to the AfterLock event's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterWriteFile Event (CBFilter Class)

This event fires after data are written to a file.

Syntax

ANSI (Cross Platform)
virtual int FireAfterWriteFile(CBFilterAfterWriteFileEventParams *e);
typedef struct {
const char *FileName;
int64 Position;
const void *Buffer;
int BufferLength;
int BytesToWrite;
int Direction;
int BytesWritten;
int Status;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterAfterWriteFileEventParams;
Unicode (Windows) virtual INT FireAfterWriteFile(CBFilterAfterWriteFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Position;
LPCVOID Buffer;
INT BufferLength;
INT BytesToWrite;
INT Direction;
INT BytesWritten;
INT Status;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterAfterWriteFileEventParams;
#define EID_CBFILTER_AFTERWRITEFILE 33

virtual INT CBFSFILTER_CALL FireAfterWriteFile(LPWSTR &lpszFileName, LONG64 &lPosition, LPVOID &lpBuffer, INT &iBufferLength, INT &iBytesToWrite, INT &iDirection, INT &iBytesWritten, INT &iStatus, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterAfterWriteFileEventParams {
public:
  const QString &FileName();

  qint64 Position();

  const void *Buffer();

  int BufferLength();

  int BytesToWrite();

  int Direction();

  int BytesWritten();
  void SetBytesWritten(int iBytesWritten);

  int Status();
  void SetStatus(int iStatus);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterWriteFile(CBFilterAfterWriteFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireAfterWriteFile(CBFilterAfterWriteFileEventParams *e) {...}

Remarks

This event fires after data are written to the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to inspect the data that were written to the file, but must not attempt to alter said data. If, during BeforeWriteFile, an application causes less data than requested to be written to the file, it should use this event to set BytesWritten back to the expected value (i.e., BytesToWrite) to prevent the requestor from behaving unexpectedly.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_AFTER_WRITE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Position parameter reflects the byte offset in the file at which writing started. A value of -1 means "append to the end of the file".

The Buffer parameter points to a memory buffer that contains the data that, if the request was successful, were written to the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToWrite parameter reflects how many bytes were to be written to the file (i.e., how many bytes the requestor expects will be written).

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the user mode application <--> filesystem direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the user mode application <--> system cache direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the system cache <--> filesystem direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the system component <--> system cache direction.

The BytesWritten parameter specifies how many bytes were actually written to the file. This parameter's value must not exceed BufferLength (and should not exceed BytesToWrite; please refer to BeforeWriteFile for more information).

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeCanFileBeDeleted Event (CBFilter Class)

This event fires before the OS attempts to mark a file or directory for deletion or remove such a mark.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeCanFileBeDeleted(CBFilterBeforeCanFileBeDeletedEventParams *e);
typedef struct {
const char *FileName;
int RequestType;
int CanDelete;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeCanFileBeDeletedEventParams;
Unicode (Windows) virtual INT FireBeforeCanFileBeDeleted(CBFilterBeforeCanFileBeDeletedEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestType;
BOOL CanDelete;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeCanFileBeDeletedEventParams;
#define EID_CBFILTER_BEFORECANFILEBEDELETED 34

virtual INT CBFSFILTER_CALL FireBeforeCanFileBeDeleted(LPWSTR &lpszFileName, INT &iRequestType, BOOL &bCanDelete, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeCanFileBeDeletedEventParams {
public:
  const QString &FileName();

  int RequestType();

  bool CanDelete();
  void SetCanDelete(bool bCanDelete);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeCanFileBeDeleted(CBFilterBeforeCanFileBeDeletedEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeCanFileBeDeleted(CBFilterBeforeCanFileBeDeletedEventParams *e) {...}

Remarks

This event fires before the OS marks the file or directory specified by FileName for deletion or removes such a mark. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Files and directories can be deleted in two ways: (1) a file or directory can be opened with the FILE_FLAG_DELETE_ON_CLOSE flag, or (2) some process may call Windows API's NtSetInformationFile function with FILE_DISPOSITION_INFORMATION or FILE_DISPOSITION_INFORMATION_EX structure as a parameter.

If the file or directory is created or opened with the FILE_FLAG_DELETE_ON_CLOSE flag, this event is fired shortly before the BeforeCreateFile or BeforeOpenFile event.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_CAN_DELETE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

DEL_REQ_OPEN_FLAG0x1The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag

DEL_REQ_SET_DISPOSITION0x2The system has sent the IRP_MJ_SET_INFORMATION request with SetFileDisposition structure as a parameter.

This request usually is sent using the NtSetInformationFile() Windows native API function.

The CanDelete parameter specifies whether the file or directory will be deleted. This parameter can be true or false depending on which request the OS has sent. Applications may prevent deletion of the file or directory by setting CanDelete to false. Changing CanDelete from false to true may or may not have the effect on the file being deleted later, so such a change should be avoided.

Note: If the file is opened with FILE_FLAG_DELETE_ON_CLOSE flag set and the event handler permits file deletion, such flag cannot be removed later (even with the call to NtSetInformationFile() API function).

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

The effect of ProcessRequest depends on what operation caused the event to fire:

  • If the event fires during the file open operation where the FILE_FLAG_DELETE_ON_CLOSE flag is set,
    • setting CanDelete to false and ProcessRequest to true causes the FILE_FLAG_DELETE_ON_CLOSE flag to be removed and the file open request to be passed further to the filesystem; and
    • setting CanDelete to false and ProcessRequest to false causes the file open request to fail with ACCESS_DENIED error.
  • If the event fires in the context of the call to NtSetInformationFile Windows API function, setting CanDelete to false causes the DeleteFlag parameter to be set to false and the request to be passed further to the filesystem. This combination effectively resets the file deletion state, known to the filesystem, to the false ("do not delete") value. The value of ProcessRequest in this case does not matter as the new value must reach the filesystem.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the specified file or directory was not opened before the request, both contexts will be absent, in which case these parameters will be NULL.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeCleanupFile Event (CBFilter Class)

This event fires before a file or directory handle is closed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeCleanupFile(CBFilterBeforeCleanupFileEventParams *e);
typedef struct {
const char *FileName;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterBeforeCleanupFileEventParams;
Unicode (Windows) virtual INT FireBeforeCleanupFile(CBFilterBeforeCleanupFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterBeforeCleanupFileEventParams;
#define EID_CBFILTER_BEFORECLEANUPFILE 35

virtual INT CBFSFILTER_CALL FireBeforeCleanupFile(LPWSTR &lpszFileName, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterBeforeCleanupFileEventParams {
public:
  const QString &FileName();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeCleanupFile(CBFilterBeforeCleanupFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeCleanupFile(CBFilterBeforeCleanupFileEventParams *e) {...}

Remarks

This event fires before a handle to the file or directory specified by FileName is closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event differs from BeforeCloseFile in that BeforeCleanupFile fires immediately before an open handle to the specified file or directory is closed by a process, whereas BeforeCloseFile may be fired much later when the OS itself decides that the file or directory can be formally closed.

Other events may fire for the file or directory in the time between when this event fires and when the BeforeCloseFile event fires. For example, system components such as the memory manager or cache manager may cause the BeforeReadFile and BeforeWriteFile events to fire.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_CLEANUP flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeCloseFile Event (CBFilter Class)

This event fires before a file or directory is closed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeCloseFile(CBFilterBeforeCloseFileEventParams *e);
typedef struct {
const char *FileName;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterBeforeCloseFileEventParams;
Unicode (Windows) virtual INT FireBeforeCloseFile(CBFilterBeforeCloseFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterBeforeCloseFileEventParams;
#define EID_CBFILTER_BEFORECLOSEFILE 36

virtual INT CBFSFILTER_CALL FireBeforeCloseFile(LPWSTR &lpszFileName, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterBeforeCloseFileEventParams {
public:
  const QString &FileName();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeCloseFile(CBFilterBeforeCloseFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeCloseFile(CBFilterBeforeCloseFileEventParams *e) {...}

Remarks

This event fires before the file or directory specified by FileName is closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_CLOSE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

If the file or directory was marked for deletion earlier, the BeforeDeleteFile will fire shortly before this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeCreateFile Event (CBFilter Class)

This event fires before a file or directory is created.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeCreateFile(CBFilterBeforeCreateFileEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int Isolate;
char *BackendFileName; int lenBackendFileName;
int DesiredAccess;
int Attributes;
int ShareMode;
int Options;
int CreateDisposition;
void *SecurityDescriptor;
int Length;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeCreateFileEventParams;
Unicode (Windows) virtual INT FireBeforeCreateFile(CBFilterBeforeCreateFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
BOOL Isolate;
LPWSTR BackendFileName; INT lenBackendFileName;
INT DesiredAccess;
INT Attributes;
INT ShareMode;
INT Options;
INT CreateDisposition;
LPVOID SecurityDescriptor;
INT Length;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeCreateFileEventParams;
#define EID_CBFILTER_BEFORECREATEFILE 37

virtual INT CBFSFILTER_CALL FireBeforeCreateFile(LPWSTR &lpszFileName, INT &iExistingAttributes, BOOL &bIsolate, LPWSTR &lpBackendFileName, INT &lenBackendFileName, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeCreateFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  bool Isolate();
  void SetIsolate(bool bIsolate);

  const QString &BackendFileName();
  bool SetBackendFileName(const QString &lpBackendFileName);

  int DesiredAccess();
  void SetDesiredAccess(int iDesiredAccess);

  int Attributes();
  void SetAttributes(int iAttributes);

  int ShareMode();
  void SetShareMode(int iShareMode);

  int Options();
  void SetOptions(int iOptions);

  int CreateDisposition();
  void SetCreateDisposition(int iCreateDisposition);

  void *SecurityDescriptor();

  int Length();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeCreateFile(CBFilterBeforeCreateFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeCreateFile(CBFilterBeforeCreateFileEventParams *e) {...}

Remarks

This event fires before the file or directory specified by FileName is created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or BeforeOpenFile.

Applications may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false; and set Status to the desired NT status (the parameter is set to STATUS_ACCESS_DENIED before the event is fired).

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_CREATE flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory creation requests.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

To redirect file access to another location, or to provide custom file content, set Isolate to true. For instance if Process A and Process B both access a file, isolation allows returning different content to each process. When Isolate is set to true the BackendFileName parameter determines if the file is redirected, and to where.

BackendFileName Value Description
FileName By default BackendFileName is set to the same value as FileName and requests are directed to the original file.
Custom Path Set BackendFileName to the full path of another file on disk to redirect requests to a different file.
"" (empty string) When set to an empty string, file-related events must be handled to provide all information and content for the file. This mode is useful for providing modified content on-the-fly, such as returning decrypted content for specific processes.

When requests are redirected to an existing file on disk a dedicated cache is created for the isolated file by the CBFilter driver. This cache ensures that the data it holds do not interfere with the data read from or written to the file when it is opened without isolation. Please see the File Isolation topic for further details.

To ensure that isolation works properly, on Windows 11, the BypassIORequest event is fired when the OS makes a request to enable BypassIO on this file, giving a way for the application to forbid BypassIO with an application-specific error code and explanation.

Requests may also be redirected to another file or directory via the ReparseFileName event which is fired before this event. In order for the ReparseFileName event to fire, a standard filter rule must exist that includes the FS_CE_REPARSE_FILENAME flag. For more details, please see the ReparseFileName topic.

The initial values of DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE Internet Relay Programming).

DesiredAccess may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to true and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

When the file being created or opened is virtual, the event handler must inspect and handle the value of the ShareMode parameter as a filesystem would normally do it.

CreateDisposition may contain one of the following values:

FILE_DISPOSITION_CREATE_NEW0x00000001Creates a new file, only if it does not already exist.

If the specified file exists, the operation fails with an "already exists" error.

FILE_DISPOSITION_CREATE_ALWAYS0x00000002Creates a new file, always.

If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.

FILE_DISPOSITION_OPEN_EXISTING0x00000003Opens a file, only if it exists

If the specified file does not exist, opening fails.

FILE_DISPOSITION_OPEN_ALWAYS0x00000004Opens a file, always.

If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.

FILE_DISPOSITION_TRUNCATE_EXISTING0x00000005Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the operation fails with a "file not found" error.

When the file being created or opened is virtual, the event handler must inspect and handle the value of the CreateDisposition parameter as a filesystem would normally do it. This includes adjusting the file size and updating the time attributes depending on the flag. For a virtual file, the driver returns the CreationStatus value that is derived from CreateDisposition as follows:
FILE_DISPOSITION_CREATE_NEW=>CREATION_STATUS_CREATED
FILE_DISPOSITION_CREATE_ALWAYS=>CREATION_STATUS_OVERWRITTEN
FILE_DISPOSITION_OPEN_EXISTING=>CREATION_STATUS_OPENED
FILE_DISPOSITION_OPEN_ALWAYS=>CREATION_STATUS_OPENED
FILE_DISPOSITION_TRUNCATE_EXISTING=>CREATION_STATUS_OVERWRITTEN
If the event handler needs to change the returned CreationStatus, it should change the value of the CreateDisposition to the FILE_DISPOSITION_*** value that leads to the desired CreationStatus value (e.g. set the value to FILE_DISPOSITION_OPEN_EXISTING so that the driver returns CREATION_STATUS_OPENED).

Options contains the flags that are described in the CreateOptions parameter of the Native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to Native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present only if it was specified by the calling process; its presence or absence does not indicate the real presence of the attribute on the file or directory on disk.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE;

Note: Files can be deleted in different ways, so do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

To prevent a file or directory from being opened, set the ResultCode parameter to a non-zero value (typically ERROR_ACCESS_DENIED (5)).

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If an application needs to alter the security information, it can do this by placing up to Length bytes of information into the SecurityDescriptor buffer.

Note: Changing the security data is possible only when the PassSecurityInFileOpenEvents configuration setting is enabled.

If the capacity reflected by the Length parameter is not enough to accommodate the security information, set LengthNeeded to the number of bytes necessary to hold the data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the BeforeCanFileBeDeleted event will fire before this event.

If the file is opened with extended attributes passed in the request, the BeforeSetEa event will fire after this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeCreateHardLink Event (CBFilter Class)

This event fires before a hard link is created.

Syntax

Remarks

This event fires before a hard link to the file specified by FileName is created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to Microsoft's Hard Links article for more information about hard links.

Applications may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_CREATE_HARD_LINK flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The LinkName parameter reflects the name of the new hard link.

The ReplaceIfExists parameter specifies what to do if a hard link with the specified LinkName already exists. If this parameter is true, the new hard link will replace the existing hard link; if this parameter is false, the operation will fail.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeDeleteFile Event (CBFilter Class)

This event fires before a file or directory is deleted.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeDeleteFile(CBFilterBeforeDeleteFileEventParams *e);
typedef struct {
const char *FileName;
int RequestType;
void *FileContext;
void *HandleContext;
void *EventContext;
int ResultCode; int reserved; } CBFilterBeforeDeleteFileEventParams;
Unicode (Windows) virtual INT FireBeforeDeleteFile(CBFilterBeforeDeleteFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestType;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterBeforeDeleteFileEventParams;
#define EID_CBFILTER_BEFOREDELETEFILE 39

virtual INT CBFSFILTER_CALL FireBeforeDeleteFile(LPWSTR &lpszFileName, INT &iRequestType, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterBeforeDeleteFileEventParams {
public:
  const QString &FileName();

  int RequestType();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeDeleteFile(CBFilterBeforeDeleteFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeDeleteFile(CBFilterBeforeDeleteFileEventParams *e) {...}

Remarks

This event fires before the file or directory specified by FileName is deleted. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. More specifically, this event is fired before the final IRM_MJ_CLOSE Internet Relay Programming (IRP) is processed by the filesystem and before BeforeCloseFile fires.

Applications may use this event to obtain information about the specified file or directory, which still exists at the time this event fires. This event cannot be used to prevent a deletion; use the BeforeCanFileBeDeleted event instead.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_DELETE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

DEL_REQ_OPEN_FLAG0x1The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag

DEL_REQ_SET_DISPOSITION0x2The system has sent the IRP_MJ_SET_INFORMATION request with SetFileDisposition structure as a parameter.

This request usually is sent using the NtSetInformationFile() Windows native API function.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeDeleteReparsePoint Event (CBFilter Class)

This event fires when the OS wants to delete a reparse point from a file or directory.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeDeleteReparsePoint(CBFilterBeforeDeleteReparsePointEventParams *e);
typedef struct {
const char *FileName;
const void *ReparseBuffer;
int BufferLength;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeDeleteReparsePointEventParams;
Unicode (Windows) virtual INT FireBeforeDeleteReparsePoint(CBFilterBeforeDeleteReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCVOID ReparseBuffer;
INT BufferLength;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeDeleteReparsePointEventParams;
#define EID_CBFILTER_BEFOREDELETEREPARSEPOINT 40

virtual INT CBFSFILTER_CALL FireBeforeDeleteReparsePoint(LPWSTR &lpszFileName, LPVOID &lpReparseBuffer, INT &iBufferLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeDeleteReparsePointEventParams {
public:
  const QString &FileName();

  const void *ReparseBuffer();

  int BufferLength();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeDeleteReparsePoint(CBFilterBeforeDeleteReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeDeleteReparsePoint(CBFilterBeforeDeleteReparsePointEventParams *e) {...}

Remarks

This event fires before the OS deletes a reparse point from a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: The file or directory is not deleted, only the reparse point is.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_DELETE_REPARSE_POINT flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The ReparseBuffer parameter points to a memory buffer that specifies the known reparse point information. This information is provided for convenience. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeEnumerateDirectory Event (CBFilter Class)

This event fires when an enumeration request is sent by the OS.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeEnumerateDirectory(CBFilterBeforeEnumerateDirectoryEventParams *e);
typedef struct {
const char *DirectoryName;
int Flags;
const char *Mask;
int Index;
void *DirectoryContext;
void *HandleContext;
void *EnumerationContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeEnumerateDirectoryEventParams;
Unicode (Windows) virtual INT FireBeforeEnumerateDirectory(CBFilterBeforeEnumerateDirectoryEventParams *e);
typedef struct {
LPCWSTR DirectoryName;
INT Flags;
LPCWSTR Mask;
INT Index;
LPVOID DirectoryContext;
LPVOID HandleContext;
LPVOID EnumerationContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeEnumerateDirectoryEventParams;
#define EID_CBFILTER_BEFOREENUMERATEDIRECTORY 41

virtual INT CBFSFILTER_CALL FireBeforeEnumerateDirectory(LPWSTR &lpszDirectoryName, INT &iFlags, LPWSTR &lpszMask, INT &iIndex, LPVOID &lpDirectoryContext, LPVOID &lpHandleContext, LPVOID &lpEnumerationContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeEnumerateDirectoryEventParams {
public:
  const QString &DirectoryName();

  int Flags();

  const QString &Mask();

  int Index();

  void *DirectoryContext();
  void SetDirectoryContext(void *lpDirectoryContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EnumerationContext();
  void SetEnumerationContext(void *lpEnumerationContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeEnumerateDirectory(CBFilterBeforeEnumerateDirectoryEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeEnumerateDirectory(CBFilterBeforeEnumerateDirectoryEventParams *e) {...}

Remarks

This event fires when the OS sends a request for reading one or more entries of the directory specified by DirectoryName. For more information about the DirectoryName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to record the request and optionally block it.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_ENUMERATE_DIRECTORY flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Flags parameter specifies supplementary information about enumeration. It is a combination of zero or more values:

FS_ENUM_RESTART_SCAN1The requestor specified that directory enumeration must be restarted.

FS_ENUM_RETURN_SINGLE_ENTRY2One entry should be returned.

FS_ENUM_INDEX_SPECIFIED4The requestor specified the index to start enumeration from.

If the Flags parameter contains FS_ENUM_INDEX_SPECIFIED, the Index parameter contains the index as provided by the OS.

The Mask parameter contains the mask for the enumeration. This value may contain any combination of valid file name characters and wildcards (the * and ? characters). Alternatively, it may be an exact file name (i.e., a value without any wildcards), as some applications query file information by specifying an exact file name in an enumeration. When TranslateDOSCharsInEnumMasks is false, this parameter may contain a so-called DOS wildcard (please, refer to the description of this setting for more information). The mask can also be empty in rare cases: this happens when the OS request is a continuation of a previous enumeration with a valid non-zero Index.

The DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration, respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeFilterAttachToVolume Event (CBFilter Class)

This event fires before the filter attaches to a newly mounted filesystem volume.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeFilterAttachToVolume(CBFilterBeforeFilterAttachToVolumeEventParams *e);
typedef struct {
const char *VolumeName;
const char *VolumeNameNT;
int SkipVolume;
int ResultCode; int reserved; } CBFilterBeforeFilterAttachToVolumeEventParams;
Unicode (Windows) virtual INT FireBeforeFilterAttachToVolume(CBFilterBeforeFilterAttachToVolumeEventParams *e);
typedef struct {
LPCWSTR VolumeName;
LPCWSTR VolumeNameNT;
BOOL SkipVolume;
INT ResultCode; INT reserved; } CBFilterBeforeFilterAttachToVolumeEventParams;
#define EID_CBFILTER_BEFOREFILTERATTACHTOVOLUME 42

virtual INT CBFSFILTER_CALL FireBeforeFilterAttachToVolume(LPWSTR &lpszVolumeName, LPWSTR &lpszVolumeNameNT, BOOL &bSkipVolume, INT &iResultCode);
class CBFilterBeforeFilterAttachToVolumeEventParams {
public:
  const QString &VolumeName();

  const QString &VolumeNameNT();

  bool SkipVolume();
  void SetSkipVolume(bool bSkipVolume);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeFilterAttachToVolume(CBFilterBeforeFilterAttachToVolumeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeFilterAttachToVolume(CBFilterBeforeFilterAttachToVolumeEventParams *e) {...}

Remarks

This event fires before the filter attaches to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

The SkipVolume parameter specifies whether the class's system driver should skip the specified volume (i.e., not attach the filter to it). Setting this parameter to true will cause all filesystem operations that target to volume to be completely ignored by the class's system driver. It also will prevent any of the following events from firing for the volume:

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

BeforeFsctl Event (CBFilter Class)

This event fires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeFsctl(CBFilterBeforeFsctlEventParams *e);
typedef struct {
const char *FileName;
int FsControlCode;
const void *InBuffer;
int InBufferLength;
int InBufferValidBytes;
void *OutBuffer;
int OutBufferLength;
int OutBufferValidBytes;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeFsctlEventParams;
Unicode (Windows) virtual INT FireBeforeFsctl(CBFilterBeforeFsctlEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FsControlCode;
LPCVOID InBuffer;
INT InBufferLength;
INT InBufferValidBytes;
LPVOID OutBuffer;
INT OutBufferLength;
INT OutBufferValidBytes;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeFsctlEventParams;
#define EID_CBFILTER_BEFOREFSCTL 43

virtual INT CBFSFILTER_CALL FireBeforeFsctl(LPWSTR &lpszFileName, INT &iFsControlCode, LPVOID &lpInBuffer, INT &iInBufferLength, INT &iInBufferValidBytes, LPVOID &lpOutBuffer, INT &iOutBufferLength, INT &iOutBufferValidBytes, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeFsctlEventParams {
public:
  const QString &FileName();

  int FsControlCode();

  const void *InBuffer();

  int InBufferLength();

  int InBufferValidBytes();
  void SetInBufferValidBytes(int iInBufferValidBytes);

  void *OutBuffer();

  int OutBufferLength();

  int OutBufferValidBytes();
  void SetOutBufferValidBytes(int iOutBufferValidBytes);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeFsctl(CBFilterBeforeFsctlEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeFsctl(CBFilterBeforeFsctlEventParams *e) {...}

Remarks

This event fires before an IRP_MJ_FILE_SYSTEM_CONTROL (FSCTL) request is processed. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwFsControlFile function (kernel mode); please refer to Microsoft's documentation for more information.

Applications may use this event to modify the input data (if there are any) before the request continues onward. Applications that choose to do this must do the following:

  1. Copy no more than InBufferLength bytes into InBuffer.
  2. Update the InBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in InBuffer.

Alternatively, applications may use this event to handle the request (preventing it from continuing onward), in which case they must do the following:

  1. Copy no more than OutBufferLength bytes into OutBuffer.
  2. Update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.
  3. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.
(The first two steps are not applicable if the requested operation is not expected to return data.)

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_FSCTL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileName parameter reflects the file, directory, or volume targeted by the request.

The FsControlCode parameter reflects the requested filesystem control code (FSCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that receives the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation is not expected to return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeGetFileSecurity Event (CBFilter Class)

This event fires before a file or directory's security attributes are retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeGetFileSecurity(CBFilterBeforeGetFileSecurityEventParams *e);
typedef struct {
const char *FileName;
int SecurityInformation;
void *SecurityDescriptor;
int Length;
int LengthNeeded;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeGetFileSecurityEventParams;
Unicode (Windows) virtual INT FireBeforeGetFileSecurity(CBFilterBeforeGetFileSecurityEventParams *e);
typedef struct {
LPCWSTR FileName;
INT SecurityInformation;
LPVOID SecurityDescriptor;
INT Length;
INT LengthNeeded;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeGetFileSecurityEventParams;
#define EID_CBFILTER_BEFOREGETFILESECURITY 44

virtual INT CBFSFILTER_CALL FireBeforeGetFileSecurity(LPWSTR &lpszFileName, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iLengthNeeded, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeGetFileSecurityEventParams {
public:
  const QString &FileName();

  int SecurityInformation();

  void *SecurityDescriptor();

  int Length();

  int LengthNeeded();
  void SetLengthNeeded(int iLengthNeeded);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeGetFileSecurity(CBFilterBeforeGetFileSecurityEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeGetFileSecurity(CBFilterBeforeGetFileSecurityEventParams *e) {...}

Remarks

This event fires before security attributes are retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: This event will not fire every time a file or directory is accessed. To check file security upon each access to a file or directory, implement the file create and open events and perform the necessary checks there instead.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_GET_SECURITY flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The SecurityInformation parameter indicates which pieces of security information are requested. Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that receives the requested security information. The buffer referenced by the SecurityDescriptor parameter may be modified by the event handler if the operation is completed without passing it further to other filters and the filesystem driver. The Length parameter reflects the capacity of the SecurityDescriptor buffer, in bytes.

If the capacity reflected by the Length parameter is not sufficient to accommodate the security information, set LengthNeeded to the number of bytes necessary to hold the data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The returned data will be formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeGetReparsePoint Event (CBFilter Class)

This event fires when the OS wants to read a reparse point for a file or directory.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeGetReparsePoint(CBFilterBeforeGetReparsePointEventParams *e);
typedef struct {
const char *FileName;
void *ReparseBuffer;
int ReparseBufferLength;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeGetReparsePointEventParams;
Unicode (Windows) virtual INT FireBeforeGetReparsePoint(CBFilterBeforeGetReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID ReparseBuffer;
INT ReparseBufferLength;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeGetReparsePointEventParams;
#define EID_CBFILTER_BEFOREGETREPARSEPOINT 45

virtual INT CBFSFILTER_CALL FireBeforeGetReparsePoint(LPWSTR &lpszFileName, LPVOID &lpReparseBuffer, INT &iReparseBufferLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeGetReparsePointEventParams {
public:
  const QString &FileName();

  void *ReparseBuffer();

  int ReparseBufferLength();
  void SetReparseBufferLength(int iReparseBufferLength);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeGetReparsePoint(CBFilterBeforeGetReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeGetReparsePoint(CBFilterBeforeGetReparsePointEventParams *e) {...}

Remarks

This event fires when the OS wants to read a reparse point for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_GET_REPARSE_POINT flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

If an application desires to handle the event and does not pass the request further, it needs to fill ReparseBuffer with the reparse point data associated with the specified file or directory and set ReparseBufferLength to the number of bytes written. The ReparseBufferLength parameter's initial value reflects the capacity of the memory buffer pointed to by ReparseBuffer. If the buffer is too small to hold all of the reparse point data, then the application should write as much data to it as possible, set ReparseBufferLength appropriately, and return the ERROR_MORE_DATA error code via ResultCode.

Please refer to the Reparse Points topic for more information.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Depending on how the request originator accessed the specified file or directory, it may or may not currently be open. The FileContext and HandleContext parameters will be absent if it is not open, in which case they will be NULL.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeIoctl Event (CBFilter Class)

This event fires before an IRP_MJ_DEVICE_CONTROL request is processed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeIoctl(CBFilterBeforeIoctlEventParams *e);
typedef struct {
const char *FileName;
int IoControlCode;
const void *InBuffer;
int InBufferLength;
int InBufferValidBytes;
void *OutBuffer;
int OutBufferLength;
int OutBufferValidBytes;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeIoctlEventParams;
Unicode (Windows) virtual INT FireBeforeIoctl(CBFilterBeforeIoctlEventParams *e);
typedef struct {
LPCWSTR FileName;
INT IoControlCode;
LPCVOID InBuffer;
INT InBufferLength;
INT InBufferValidBytes;
LPVOID OutBuffer;
INT OutBufferLength;
INT OutBufferValidBytes;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeIoctlEventParams;
#define EID_CBFILTER_BEFOREIOCTL 46

virtual INT CBFSFILTER_CALL FireBeforeIoctl(LPWSTR &lpszFileName, INT &iIoControlCode, LPVOID &lpInBuffer, INT &iInBufferLength, INT &iInBufferValidBytes, LPVOID &lpOutBuffer, INT &iOutBufferLength, INT &iOutBufferValidBytes, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeIoctlEventParams {
public:
  const QString &FileName();

  int IoControlCode();

  const void *InBuffer();

  int InBufferLength();

  int InBufferValidBytes();
  void SetInBufferValidBytes(int iInBufferValidBytes);

  void *OutBuffer();

  int OutBufferLength();

  int OutBufferValidBytes();
  void SetOutBufferValidBytes(int iOutBufferValidBytes);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeIoctl(CBFilterBeforeIoctlEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeIoctl(CBFilterBeforeIoctlEventParams *e) {...}

Remarks

This event fires before an IRP_MJ_DEVICE_CONTROL (IOCTL) request is processed. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwDeviceIoControlFile function (kernel mode). Please refer to Microsoft's documentation for more information.

Applications may use this event to modify the input data (if there are any) before the request continues onward. Applications that choose to do this must do the following:

  1. Copy no more than InBufferLength bytes into InBuffer.
  2. Update the InBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in InBuffer.

Alternatively, applications may use this event to handle the request (preventing it from continuing onward), in which case they must do the following:

  1. Copy no more than OutBufferLength bytes into OutBuffer.
  2. Update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.
  3. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.
(The first two steps are not applicable if the requested operation is not expected to return data.)

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_IOCTL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileName parameter reflects the file, directory, or volume targeted by the request.

The IoControlCode parameter reflects the requested I/O control code (IOCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that receives the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation is not expected to return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeLock Event (CBFilter Class)

This event fires before a range of bytes in a file is locked.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeLock(CBFilterBeforeLockEventParams *e);
typedef struct {
const char *FileName;
int64 *pOffset;
int64 *pLength;
int64 Key;
int FailImmediately;
int ExclusiveLock;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeLockEventParams;
Unicode (Windows) virtual INT FireBeforeLock(CBFilterBeforeLockEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pOffset;
LONG64 *pLength;
LONG64 Key;
BOOL FailImmediately;
BOOL ExclusiveLock;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeLockEventParams;
#define EID_CBFILTER_BEFORELOCK 47

virtual INT CBFSFILTER_CALL FireBeforeLock(LPWSTR &lpszFileName, LONG64 &lOffset, LONG64 &lLength, LONG64 &lKey, BOOL &bFailImmediately, BOOL &bExclusiveLock, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeLockEventParams {
public:
  const QString &FileName();

  qint64 Offset();
  void SetOffset(qint64 lOffset);

  qint64 Length();
  void SetLength(qint64 lLength);

  qint64 Key();

  bool FailImmediately();
  void SetFailImmediately(bool bFailImmediately);

  bool ExclusiveLock();
  void SetExclusiveLock(bool bExclusiveLock);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeLock(CBFilterBeforeLockEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeLock(CBFilterBeforeLockEventParams *e) {...}

Remarks

This event fires before a range of bytes in the file specified by FileName is locked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This request is made either by the OS, or on behalf of a user mode application that called the Windows API's LockFile or LockFileEx function.

Applications may use this event to modify the request's parameters.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Offset parameter specifies the byte offset where the byte range lock should start.

The Length parameter specifies the length of the byte range lock.

The Key parameter reflects the key that the byte range lock will be associated with. This key is used to identify the byte range lock in later unlock-by-key requests.

The FailImmediately parameter specifies whether the request should fail if the lock cannot be granted immediately.

The ExclusiveLock parameter specifies whether the byte range lock should be exclusive (true) or shared (false).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeOpenFile Event (CBFilter Class)

This event fires before a file or directory is opened.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeOpenFile(CBFilterBeforeOpenFileEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int Isolate;
char *BackendFileName; int lenBackendFileName;
int DesiredAccess;
int Attributes;
int ShareMode;
int Options;
int CreateDisposition;
void *SecurityDescriptor;
int Length;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeOpenFileEventParams;
Unicode (Windows) virtual INT FireBeforeOpenFile(CBFilterBeforeOpenFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
BOOL Isolate;
LPWSTR BackendFileName; INT lenBackendFileName;
INT DesiredAccess;
INT Attributes;
INT ShareMode;
INT Options;
INT CreateDisposition;
LPVOID SecurityDescriptor;
INT Length;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeOpenFileEventParams;
#define EID_CBFILTER_BEFOREOPENFILE 48

virtual INT CBFSFILTER_CALL FireBeforeOpenFile(LPWSTR &lpszFileName, INT &iExistingAttributes, BOOL &bIsolate, LPWSTR &lpBackendFileName, INT &lenBackendFileName, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeOpenFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  bool Isolate();
  void SetIsolate(bool bIsolate);

  const QString &BackendFileName();
  bool SetBackendFileName(const QString &lpBackendFileName);

  int DesiredAccess();
  void SetDesiredAccess(int iDesiredAccess);

  int Attributes();
  void SetAttributes(int iAttributes);

  int ShareMode();
  void SetShareMode(int iShareMode);

  int Options();
  void SetOptions(int iOptions);

  int CreateDisposition();
  void SetCreateDisposition(int iCreateDisposition);

  void *SecurityDescriptor();

  int Length();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeOpenFile(CBFilterBeforeOpenFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeOpenFile(CBFilterBeforeOpenFileEventParams *e) {...}

Remarks

This event fires before the file or directory specified by FileName is opened. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or BeforeCreateFile.

Applications may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false; and set Status to the desired NT status (the parameter is set to STATUS_ACCESS_DENIED before the event is fired).

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_OPEN flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory open requests.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

To redirect file access to another location, or to provide custom file content, set Isolate to true. For instance if Process A and Process B both access a file, isolation allows returning different content to each process. When Isolate is set to true the BackendFileName parameter determines if the file is redirected, and to where.

BackendFileName Value Description
FileName By default BackendFileName is set to the same value as FileName and requests are directed to the original file.
Custom Path Set BackendFileName to the full path of another file on disk to redirect requests to a different file.
"" (empty string) When set to an empty string, file-related events must be handled to provide all information and content for the file. This mode is useful for providing modified content on-the-fly, such as returning decrypted content for specific processes.

When requests are redirected to an existing file on disk a dedicated cache is created for the isolated file by the CBFilter driver. This cache ensures that the data it holds do not interfere with the data read from or written to the file when it is opened without isolation. Please see the File Isolation topic for further details.

To ensure that isolation works properly, on Windows 11, the BypassIORequest event is fired when the OS makes a request to enable BypassIO on this file, giving a way for the application to forbid BypassIO with an application-specific error code and explanation.

Requests may also be redirected to another file or directory via the ReparseFileName event which is fired before this event. In order for the ReparseFileName event to fire, a standard filter rule must exist that includes the FS_CE_REPARSE_FILENAME flag. For more details, please see the ReparseFileName topic.

The initial values of DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE Internet Relay Programming).

DesiredAccess may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to true and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

When the file being created or opened is virtual, the event handler must inspect and handle the value of the ShareMode parameter as a filesystem would normally do it.

CreateDisposition may contain one of the following values:

FILE_DISPOSITION_CREATE_NEW0x00000001Creates a new file, only if it does not already exist.

If the specified file exists, the operation fails with an "already exists" error.

FILE_DISPOSITION_CREATE_ALWAYS0x00000002Creates a new file, always.

If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.

FILE_DISPOSITION_OPEN_EXISTING0x00000003Opens a file, only if it exists

If the specified file does not exist, opening fails.

FILE_DISPOSITION_OPEN_ALWAYS0x00000004Opens a file, always.

If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.

FILE_DISPOSITION_TRUNCATE_EXISTING0x00000005Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the operation fails with a "file not found" error.

When the file being created or opened is virtual, the event handler must inspect and handle the value of the CreateDisposition parameter as a filesystem would normally do it. This includes adjusting the file size and updating the time attributes depending on the flag. For a virtual file, the driver returns the CreationStatus value that is derived from CreateDisposition as follows:
FILE_DISPOSITION_CREATE_NEW=>CREATION_STATUS_CREATED
FILE_DISPOSITION_CREATE_ALWAYS=>CREATION_STATUS_OVERWRITTEN
FILE_DISPOSITION_OPEN_EXISTING=>CREATION_STATUS_OPENED
FILE_DISPOSITION_OPEN_ALWAYS=>CREATION_STATUS_OPENED
FILE_DISPOSITION_TRUNCATE_EXISTING=>CREATION_STATUS_OVERWRITTEN
If the event handler needs to change the returned CreationStatus, it should change the value of the CreateDisposition to the FILE_DISPOSITION_*** value that leads to the desired CreationStatus value (e.g. set the value to FILE_DISPOSITION_OPEN_EXISTING so that the driver returns CREATION_STATUS_OPENED).

Options contains the flags that are described in the CreateOptions parameter of the Native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to Native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present only if it was specified by the calling process; its presence or absence does not indicate the real presence of the attribute on the file or directory on disk.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE;

Note: Files can be deleted in different ways, so do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

To prevent a file or directory from being opened, set the ResultCode parameter to a non-zero value (typically ERROR_ACCESS_DENIED (5)).

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If an application needs to alter the security information, it can do this by placing up to Length bytes of information into the SecurityDescriptor buffer.

Note: Changing the security data is possible only when the PassSecurityInFileOpenEvents configuration setting is enabled.

If the capacity reflected by the Length parameter is not enough to accommodate the security information, set LengthNeeded to the number of bytes necessary to hold the data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the BeforeCanFileBeDeleted event will fire before this event.

If the file is opened with extended attributes passed in the request, the BeforeSetEa event will fire after this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeQueryEa Event (CBFilter Class)

This event fires before information about extended attributes of a file is retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeQueryEa(CBFilterBeforeQueryEaEventParams *e);
typedef struct {
const char *FileName;
void *Buffer;
int BufferLength;
int ReturnSingleEntry;
void *EaList;
int EaListLength;
int EaIndex;
int RestartScan;
int LengthReturned;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeQueryEaEventParams;
Unicode (Windows) virtual INT FireBeforeQueryEa(CBFilterBeforeQueryEaEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID Buffer;
INT BufferLength;
BOOL ReturnSingleEntry;
LPVOID EaList;
INT EaListLength;
INT EaIndex;
BOOL RestartScan;
INT LengthReturned;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeQueryEaEventParams;
#define EID_CBFILTER_BEFOREQUERYEA 49

virtual INT CBFSFILTER_CALL FireBeforeQueryEa(LPWSTR &lpszFileName, LPVOID &lpBuffer, INT &iBufferLength, BOOL &bReturnSingleEntry, LPVOID &lpEaList, INT &iEaListLength, INT &iEaIndex, BOOL &bRestartScan, INT &iLengthReturned, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeQueryEaEventParams {
public:
  const QString &FileName();

  void *Buffer();

  int BufferLength();

  bool ReturnSingleEntry();
  void SetReturnSingleEntry(bool bReturnSingleEntry);

  void *EaList();

  int EaListLength();
  void SetEaListLength(int iEaListLength);

  int EaIndex();
  void SetEaIndex(int iEaIndex);

  bool RestartScan();
  void SetRestartScan(bool bRestartScan);

  int LengthReturned();
  void SetLengthReturned(int iLengthReturned);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeQueryEa(CBFilterBeforeQueryEaEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeQueryEa(CBFilterBeforeQueryEaEventParams *e) {...}

Remarks

This event fires before information about extended attributes of the file specified by FileName is retrieved using the ZwQueryEaFile or FltQueryEaFile function of the system API. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_QUERY_EA flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Buffer parameter points to a memory buffer, into which, if the request is successful, the filesystem will place the requested information. The data in the buffer are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The BufferLength parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

ReturnSingleEntry specifies that the filesystem had to return only the first entry it has found.

EaList is an optional parameter that points to a caller-supplied memory buffer specifying the extended attributes to be queried. The data in the buffer are formatted as a FILE_GET_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The EaListLength parameter reflects the length of this data, in bytes. If the caller of the FltQueryEaFile function did not specify any value, it will contain 0. The list may be modified by an event handler, if needed, provided that the size of the new or modified data does not exceed the value of the EaListLength parameter.

EaIndex is an optional parameter that specifies the starting index of the attribute, information about which is requested. This parameter is ignored by the filesystem if EaList points to a nonempty list. If the caller of the FltQueryEaFile function did not specify any value, the parameter will contain -1.

The RestartScan parameter instructs the filesystem to restart enumeration of extended attributes from the first entry. If the parameter is false, retrieval of the extended attributes is resumed by the filesystem after a previous request. The parameter may be modified by an event handler if needed.

LengthReturned is an optional parameter that contains the size, in bytes, of the information, returned in the Buffer.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

Applications may use this event to modify the request's data before it continues onward, or to handle the request entirely (preventing it from continuing onward). In these cases, applications must do the following:

  1. Copy no more than BufferLength bytes into Buffer.
  2. Update the LengthReturned parameter's value afterward so that it correctly reflects the amount of data in Buffer.
  3. If the request has been handled and should not continue onward, set ProcessRequest to false.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeQueryFileInfo Event (CBFilter Class)

This event fires before information about a file or directory is retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeQueryFileInfo(CBFilterBeforeQueryFileInfoEventParams *e);
typedef struct {
const char *FileName;
int FileInformationClass;
void *Buffer;
int BufferLength;
int ValidBytes;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeQueryFileInfoEventParams;
Unicode (Windows) virtual INT FireBeforeQueryFileInfo(CBFilterBeforeQueryFileInfoEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FileInformationClass;
LPVOID Buffer;
INT BufferLength;
INT ValidBytes;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeQueryFileInfoEventParams;
#define EID_CBFILTER_BEFOREQUERYFILEINFO 50

virtual INT CBFSFILTER_CALL FireBeforeQueryFileInfo(LPWSTR &lpszFileName, INT &iFileInformationClass, LPVOID &lpBuffer, INT &iBufferLength, INT &iValidBytes, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeQueryFileInfoEventParams {
public:
  const QString &FileName();

  int FileInformationClass();

  void *Buffer();

  int BufferLength();

  int ValidBytes();
  void SetValidBytes(int iValidBytes);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeQueryFileInfo(CBFilterBeforeQueryFileInfoEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeQueryFileInfo(CBFilterBeforeQueryFileInfoEventParams *e) {...}

Remarks

This event fires before information about the file or directory specified by FileName is retrieved. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtQueryInformationFile function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_QUERY_FILE_INFO flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileInformationClass parameter indicates what kind of file information is requested. Please refer to the NtQueryInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that receives the requested file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtQueryInformationFile function's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

Applications may use this event to modify the request's data before it continues onward, or to handle the request entirely (preventing it from continuing onward). In these cases, applications must do the following:

  1. Copy no more than BufferLength bytes into Buffer.
  2. Update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.
  3. If the request has been handled and should not continue onward, set ProcessRequest to false.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeReadFile Event (CBFilter Class)

This event fires before data are read from a file.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeReadFile(CBFilterBeforeReadFileEventParams *e);
typedef struct {
const char *FileName;
int64 *pPosition;
void *Buffer;
int BufferLength;
int BytesToRead;
int Reserved;
int Direction;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeReadFileEventParams;
Unicode (Windows) virtual INT FireBeforeReadFile(CBFilterBeforeReadFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pPosition;
LPVOID Buffer;
INT BufferLength;
INT BytesToRead;
INT Reserved;
INT Direction;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeReadFileEventParams;
#define EID_CBFILTER_BEFOREREADFILE 51

virtual INT CBFSFILTER_CALL FireBeforeReadFile(LPWSTR &lpszFileName, LONG64 &lPosition, LPVOID &lpBuffer, INT &iBufferLength, INT &iBytesToRead, INT &iReserved, INT &iDirection, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeReadFileEventParams {
public:
  const QString &FileName();

  qint64 Position();
  void SetPosition(qint64 lPosition);

  void *Buffer();

  int BufferLength();

  int BytesToRead();
  void SetBytesToRead(int iBytesToRead);

  int Reserved();
  void SetReserved(int iReserved);

  int Direction();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeReadFile(CBFilterBeforeReadFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeReadFile(CBFilterBeforeReadFileEventParams *e) {...}

Remarks

This event fires before data are read from the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications that intend to modify a file's data after it is read may use this event to modify the request's parameters, if necessary (e.g., to ensure that the correct data are read from the file and made available for postprocessing during the AfterReadFile event). Applications may also use this event to block the request entirely by returning an appropriate error code (e.g., ACCESS_DENIED) via ResultCode.

Alternatively, applications may use this event to handle the underlying request, in which case they must do the following:

  1. Enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires).
  2. Copy no more than BufferLength bytes into Buffer.
  3. Update the BytesToRead parameter's value afterward so that it correctly reflects the amount of data in Buffer.
  4. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_READ flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Position parameter specifies the byte offset in the file at which reading should start.

The Buffer parameter points to a memory buffer that receives the data read from the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToRead parameter's initial value reflects how many bytes should be read from the file (i.e., how many bytes the requestor expects will be read). This parameter's value may be changed (for either of the reasons discussed above), but it must not exceed BufferLength.

Note: However, reading more or less data than requested is not expected behavior and likely will cause the requestor to misbehave. Applications that change BytesToRead, for any reason, should use the AfterReadFile event to "cover up" such behavior; please refer to its documentation for more information.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the user mode application <--> filesystem direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the user mode application <--> system cache direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the system cache <--> filesystem direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the system component <--> system cache direction.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeRenameOrMoveFile Event (CBFilter Class)

This event fires before a file or directory is renamed or moved.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeRenameOrMoveFile(CBFilterBeforeRenameOrMoveFileEventParams *e);
typedef struct {
const char *FileName;
const char *NewFileName;
int ReplaceIfExists;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeRenameOrMoveFileEventParams;
Unicode (Windows) virtual INT FireBeforeRenameOrMoveFile(CBFilterBeforeRenameOrMoveFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCWSTR NewFileName;
BOOL ReplaceIfExists;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeRenameOrMoveFileEventParams;
#define EID_CBFILTER_BEFORERENAMEORMOVEFILE 52

virtual INT CBFSFILTER_CALL FireBeforeRenameOrMoveFile(LPWSTR &lpszFileName, LPWSTR &lpszNewFileName, BOOL &bReplaceIfExists, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeRenameOrMoveFileEventParams {
public:
  const QString &FileName();

  const QString &NewFileName();

  bool ReplaceIfExists();
  void SetReplaceIfExists(bool bReplaceIfExists);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeRenameOrMoveFile(CBFilterBeforeRenameOrMoveFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeRenameOrMoveFile(CBFilterBeforeRenameOrMoveFileEventParams *e) {...}

Remarks

This event fires before the file or directory specified by FileName is renamed or moved to NewFileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_RENAME flag. A rule's mask is matched against both previous and new file names, and the event will fire when either of the names matches the mask.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The ReplaceIfExists parameter specifies what to do if a file with the specified NewFileName already exists. If this parameter is true, the existing file will be overwritten by the file being renamed/moved; if this parameter is false, the operation will fail.

Note: Windows only allows files to be overwritten; if the destination is an existing directory, the request will be denied regardless of this parameter's value.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetAllocationSize Event (CBFilter Class)

This event fires before a file's allocation size is changed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetAllocationSize(CBFilterBeforeSetAllocationSizeEventParams *e);
typedef struct {
const char *FileName;
int64 *pAllocationSize;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetAllocationSizeEventParams;
Unicode (Windows) virtual INT FireBeforeSetAllocationSize(CBFilterBeforeSetAllocationSizeEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pAllocationSize;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetAllocationSizeEventParams;
#define EID_CBFILTER_BEFORESETALLOCATIONSIZE 53

virtual INT CBFSFILTER_CALL FireBeforeSetAllocationSize(LPWSTR &lpszFileName, LONG64 &lAllocationSize, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetAllocationSizeEventParams {
public:
  const QString &FileName();

  qint64 AllocationSize();
  void SetAllocationSize(qint64 lAllocationSize);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetAllocationSize(CBFilterBeforeSetAllocationSizeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetAllocationSize(CBFilterBeforeSetAllocationSizeEventParams *e) {...}

Remarks

This event fires before the allocation size of the file specified by FileName is changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the request's parameters.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_SIZES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The AllocationSize parameter specifies the new allocation size, in bytes. A file's allocation size is typically larger than its actual size because filesystem operations often reserve space on disk before writing additional data to a file. Applications may track such situations and avoid reallocating disk space where possible to improve performance.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetEa Event (CBFilter Class)

This event fires before extended attributes of a file are changed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetEa(CBFilterBeforeSetEaEventParams *e);
typedef struct {
const char *FileName;
void *Buffer;
int BufferLength;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetEaEventParams;
Unicode (Windows) virtual INT FireBeforeSetEa(CBFilterBeforeSetEaEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID Buffer;
INT BufferLength;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetEaEventParams;
#define EID_CBFILTER_BEFORESETEA 54

virtual INT CBFSFILTER_CALL FireBeforeSetEa(LPWSTR &lpszFileName, LPVOID &lpBuffer, INT &iBufferLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetEaEventParams {
public:
  const QString &FileName();

  void *Buffer();

  int BufferLength();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetEa(CBFilterBeforeSetEaEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetEa(CBFilterBeforeSetEaEventParams *e) {...}

Remarks

This event fires before extended attributes are changed for the file specified by FileName using the ZwSetEaFile or FltSetEaFile function of the system API. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If the file is created or opened with extended attributes passed in the request, this event will fire shortly after the BeforeCreateFile or BeforeOpenFile event.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_EA flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Buffer parameter points to a memory buffer that specifies the extended attribute information. The buffer referenced by the Buffer parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. The Length parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to Microsoft's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetFileAttributes Event (CBFilter Class)

This event fires before a file or directory's attributes or times are changed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetFileAttributes(CBFilterBeforeSetFileAttributesEventParams *e);
typedef struct {
const char *FileName;
int64 *pCreationTime;
int64 *pLastAccessTime;
int64 *pLastWriteTime;
int64 *pChangeTime;
int Attributes;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetFileAttributesEventParams;
Unicode (Windows) virtual INT FireBeforeSetFileAttributes(CBFilterBeforeSetFileAttributesEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pCreationTime;
LONG64 *pLastAccessTime;
LONG64 *pLastWriteTime;
LONG64 *pChangeTime;
INT Attributes;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetFileAttributesEventParams;
#define EID_CBFILTER_BEFORESETFILEATTRIBUTES 55

virtual INT CBFSFILTER_CALL FireBeforeSetFileAttributes(LPWSTR &lpszFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, INT &iAttributes, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetFileAttributesEventParams {
public:
  const QString &FileName();

  const QDateTime &CreationTime();
  void SetCreationTime(const QDateTime &qdtCreationTime);

  const QDateTime &LastAccessTime();
  void SetLastAccessTime(const QDateTime &qdtLastAccessTime);

  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);

  const QDateTime &ChangeTime();
  void SetChangeTime(const QDateTime &qdtChangeTime);

  int Attributes();
  void SetAttributes(int iAttributes);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetFileAttributes(CBFilterBeforeSetFileAttributesEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetFileAttributes(CBFilterBeforeSetFileAttributesEventParams *e) {...}

Remarks

This event fires before the attributes or times of a file or directory specified by FileName are changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the request's parameters.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_ATTRIBUTES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters specify the new time values, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. A value of 0 indicates that the corresponding time value is not included in the request.

The Attributes parameter specifies the new attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetFileInfo Event (CBFilter Class)

This event fires before information about a file or directory is changed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetFileInfo(CBFilterBeforeSetFileInfoEventParams *e);
typedef struct {
const char *FileName;
int FileInformationClass;
void *Buffer;
int BufferLength;
int ValidBytes;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetFileInfoEventParams;
Unicode (Windows) virtual INT FireBeforeSetFileInfo(CBFilterBeforeSetFileInfoEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FileInformationClass;
LPVOID Buffer;
INT BufferLength;
INT ValidBytes;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetFileInfoEventParams;
#define EID_CBFILTER_BEFORESETFILEINFO 56

virtual INT CBFSFILTER_CALL FireBeforeSetFileInfo(LPWSTR &lpszFileName, INT &iFileInformationClass, LPVOID &lpBuffer, INT &iBufferLength, INT &iValidBytes, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetFileInfoEventParams {
public:
  const QString &FileName();

  int FileInformationClass();

  void *Buffer();

  int BufferLength();

  int ValidBytes();
  void SetValidBytes(int iValidBytes);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetFileInfo(CBFilterBeforeSetFileInfoEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetFileInfo(CBFilterBeforeSetFileInfoEventParams *e) {...}

Remarks

This event fires before information about the file or directory specified by FileName is changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtSetInformationFile function.

Applications may use this event to modify the request's data before it continues onward, in which case they must do the following:

  1. Copy no more than BufferLength bytes into Buffer.
  2. Update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.

Alternatively, applications may use this event to handle the underlying request, preventing it from continuing onward, by setting ProcessRequest to false.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_FILE_INFO flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The FileInformationClass parameter indicates what kind of file information is to be changed. Please refer to the NtSetInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that specifies the new file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains, respectively, in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtSetInformationFile function's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetFileSecurity Event (CBFilter Class)

This event fires before a file or directory's security attributes are changed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetFileSecurity(CBFilterBeforeSetFileSecurityEventParams *e);
typedef struct {
const char *FileName;
int SecurityInformation;
void *SecurityDescriptor;
int Length;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetFileSecurityEventParams;
Unicode (Windows) virtual INT FireBeforeSetFileSecurity(CBFilterBeforeSetFileSecurityEventParams *e);
typedef struct {
LPCWSTR FileName;
INT SecurityInformation;
LPVOID SecurityDescriptor;
INT Length;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetFileSecurityEventParams;
#define EID_CBFILTER_BEFORESETFILESECURITY 57

virtual INT CBFSFILTER_CALL FireBeforeSetFileSecurity(LPWSTR &lpszFileName, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetFileSecurityEventParams {
public:
  const QString &FileName();

  int SecurityInformation();

  void *SecurityDescriptor();

  int Length();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetFileSecurity(CBFilterBeforeSetFileSecurityEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetFileSecurity(CBFilterBeforeSetFileSecurityEventParams *e) {...}

Remarks

This event fires before security attributes are changed for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_SECURITY flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, will be set. Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that specifies the new security information. The buffer referenced by the SecurityDescriptor parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetFileSize Event (CBFilter Class)

This event fires before a file is resized.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetFileSize(CBFilterBeforeSetFileSizeEventParams *e);
typedef struct {
const char *FileName;
int64 *pSize;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetFileSizeEventParams;
Unicode (Windows) virtual INT FireBeforeSetFileSize(CBFilterBeforeSetFileSizeEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pSize;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetFileSizeEventParams;
#define EID_CBFILTER_BEFORESETFILESIZE 58

virtual INT CBFSFILTER_CALL FireBeforeSetFileSize(LPWSTR &lpszFileName, LONG64 &lSize, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetFileSizeEventParams {
public:
  const QString &FileName();

  qint64 Size();
  void SetSize(qint64 lSize);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetFileSize(CBFilterBeforeSetFileSizeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetFileSize(CBFilterBeforeSetFileSizeEventParams *e) {...}

Remarks

This event fires before the file specified by FileName is resized, whether explicitly (e.g., truncation) or implicitly (i.e., as data are appended). For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the request's parameters.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_SIZES flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Size parameter specifies the new file size, in bytes.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeSetReparsePoint Event (CBFilter Class)

This event fires when the OS wants to create or update a reparse point on a file or directory.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetReparsePoint(CBFilterBeforeSetReparsePointEventParams *e);
typedef struct {
const char *FileName;
int64 ReparseTag;
void *ReparseBuffer;
int BufferLength;
int DataLength;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeSetReparsePointEventParams;
Unicode (Windows) virtual INT FireBeforeSetReparsePoint(CBFilterBeforeSetReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 ReparseTag;
LPVOID ReparseBuffer;
INT BufferLength;
INT DataLength;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeSetReparsePointEventParams;
#define EID_CBFILTER_BEFORESETREPARSEPOINT 59

virtual INT CBFSFILTER_CALL FireBeforeSetReparsePoint(LPWSTR &lpszFileName, LONG64 &lReparseTag, LPVOID &lpReparseBuffer, INT &iBufferLength, INT &iDataLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeSetReparsePointEventParams {
public:
  const QString &FileName();

  qint64 ReparseTag();

  void *ReparseBuffer();

  int BufferLength();

  int DataLength();
  void SetDataLength(int iDataLength);

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetReparsePoint(CBFilterBeforeSetReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeSetReparsePoint(CBFilterBeforeSetReparsePointEventParams *e) {...}

Remarks

This event fires before the OS creates or updates a reparse point on a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_SET_REPARSE_POINT flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The ReparseTag is the reparse tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; for convenience, the class extracts it and provides it separately. If the event handler needs to change the reparse tag, it may do so in ReparseBuffer.

The ReparseBuffer parameter points to a memory buffer that specifies the new reparse point information. The buffer referenced by the ReparseBuffer parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. The DataLength parameter initially reflects the length of the data contained in the buffer, in bytes. If the event handler updates the data in the ReparseBuffer, it should adjust DataLength to the size of the new data, placed to the buffer. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeUnlockAll Event (CBFilter Class)

This event fires before all locked byte ranges in a file are unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeUnlockAll(CBFilterBeforeUnlockAllEventParams *e);
typedef struct {
const char *FileName;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeUnlockAllEventParams;
Unicode (Windows) virtual INT FireBeforeUnlockAll(CBFilterBeforeUnlockAllEventParams *e);
typedef struct {
LPCWSTR FileName;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeUnlockAllEventParams;
#define EID_CBFILTER_BEFOREUNLOCKALL 60

virtual INT CBFSFILTER_CALL FireBeforeUnlockAll(LPWSTR &lpszFileName, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeUnlockAllEventParams {
public:
  const QString &FileName();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeUnlockAll(CBFilterBeforeUnlockAllEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeUnlockAll(CBFilterBeforeUnlockAllEventParams *e) {...}

Remarks

This event fires before all locked byte ranges in the file specified by FileName are unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeUnlockAllByKey Event (CBFilter Class)

This event fires before all locked byte ranges in a file, associated with a particular key, are unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeUnlockAllByKey(CBFilterBeforeUnlockAllByKeyEventParams *e);
typedef struct {
const char *FileName;
int64 Key;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeUnlockAllByKeyEventParams;
Unicode (Windows) virtual INT FireBeforeUnlockAllByKey(CBFilterBeforeUnlockAllByKeyEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Key;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeUnlockAllByKeyEventParams;
#define EID_CBFILTER_BEFOREUNLOCKALLBYKEY 61

virtual INT CBFSFILTER_CALL FireBeforeUnlockAllByKey(LPWSTR &lpszFileName, LONG64 &lKey, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeUnlockAllByKeyEventParams {
public:
  const QString &FileName();

  qint64 Key();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeUnlockAllByKey(CBFilterBeforeUnlockAllByKeyEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeUnlockAllByKey(CBFilterBeforeUnlockAllByKeyEventParams *e) {...}

Remarks

This event fires before all locked byte ranges in the file specified by FileName, and associated with the specified Key, are unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Key parameter contains the key value specified when the byte ranges were locked. Please refer to the BeforeLock event's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeUnlockSingle Event (CBFilter Class)

This event fires before a particular locked byte range in a file is unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeUnlockSingle(CBFilterBeforeUnlockSingleEventParams *e);
typedef struct {
const char *FileName;
int64 *pOffset;
int64 *pLength;
int64 Key;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeUnlockSingleEventParams;
Unicode (Windows) virtual INT FireBeforeUnlockSingle(CBFilterBeforeUnlockSingleEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pOffset;
LONG64 *pLength;
LONG64 Key;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeUnlockSingleEventParams;
#define EID_CBFILTER_BEFOREUNLOCKSINGLE 62

virtual INT CBFSFILTER_CALL FireBeforeUnlockSingle(LPWSTR &lpszFileName, LONG64 &lOffset, LONG64 &lLength, LONG64 &lKey, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeUnlockSingleEventParams {
public:
  const QString &FileName();

  qint64 Offset();
  void SetOffset(qint64 lOffset);

  qint64 Length();
  void SetLength(qint64 lLength);

  qint64 Key();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeUnlockSingle(CBFilterBeforeUnlockSingleEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeUnlockSingle(CBFilterBeforeUnlockSingleEventParams *e) {...}

Remarks

This event fires before a particular locked byte range in the file specified by FileName is unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the request's parameters.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_LOCK_CONTROL flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Offset, Length, and Key parameters contain the starting byte offset, length, and key values, respectively, specified when the byte range was locked. Please refer to the BeforeLock event's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeWriteFile Event (CBFilter Class)

This event fires before data are written to a file.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeWriteFile(CBFilterBeforeWriteFileEventParams *e);
typedef struct {
const char *FileName;
int64 *pPosition;
void *Buffer;
int BufferLength;
int BytesToWrite;
int Reserved;
int Direction;
void *FileContext;
void *HandleContext;
void *EventContext;
int Status;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeWriteFileEventParams;
Unicode (Windows) virtual INT FireBeforeWriteFile(CBFilterBeforeWriteFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pPosition;
LPVOID Buffer;
INT BufferLength;
INT BytesToWrite;
INT Reserved;
INT Direction;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
INT Status;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeWriteFileEventParams;
#define EID_CBFILTER_BEFOREWRITEFILE 63

virtual INT CBFSFILTER_CALL FireBeforeWriteFile(LPWSTR &lpszFileName, LONG64 &lPosition, LPVOID &lpBuffer, INT &iBufferLength, INT &iBytesToWrite, INT &iReserved, INT &iDirection, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, INT &iStatus, BOOL &bProcessRequest, INT &iResultCode);
class CBFilterBeforeWriteFileEventParams {
public:
  const QString &FileName();

  qint64 Position();
  void SetPosition(qint64 lPosition);

  void *Buffer();

  int BufferLength();

  int BytesToWrite();
  void SetBytesToWrite(int iBytesToWrite);

  int Reserved();
  void SetReserved(int iReserved);

  int Direction();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int Status();
  void SetStatus(int iStatus);

  bool ProcessRequest();
  void SetProcessRequest(bool bProcessRequest);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeWriteFile(CBFilterBeforeWriteFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBeforeWriteFile(CBFilterBeforeWriteFileEventParams *e) {...}

Remarks

This event fires before data are written to the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications may use this event to modify the request's parameters or data. Applications that choose to modify the request's data must do the following:

  1. Enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires).
  2. Copy no more than BufferLength bytes into Buffer.
  3. Update the BytesToWrite parameter's value afterward so that it correctly reflects the amount of data in Buffer.

Applications may also use this event to block the request entirely by returning an appropriate error code (e.g., ACCESS_DENIED) via ResultCode.

Alternatively, applications may use this event to handle the underlying request, in which case they must do the following:

  1. Write the data pointed to by Buffer to the desired location (after preprocessing it, if necessary).
  2. Update the BytesToWrite parameter's value afterward so that it correctly reflects the amount of data that were written.
  3. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_BEFORE_WRITE flag.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

The Position parameter specifies the byte offset in the file at which writing should start. A value of -1 means "append to the end of the file".

The Buffer parameter points to a memory buffer that contains the data to write to the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToWrite parameter's initial value reflects how many bytes should be written to the file (i.e., how many bytes the requestor expects will be written). This parameter's value may be changed (for either of the reasons discussed above), but it must not exceed BufferLength.

Note: However, writing more or less data than requested is not expected behavior and likely will cause the requestor to misbehave. Applications that change BytesToWrite, for any reason, should use the AfterWriteFile event to "cover up" such behavior; please refer to its documentation for more information.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the user mode application <--> filesystem direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the user mode application <--> system cache direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the system cache <--> filesystem direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the system component <--> system cache direction.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BypassIORequest Event (CBFilter Class)

This event fires when the OS sends one of BypassIO commands.

Syntax

ANSI (Cross Platform)
virtual int FireBypassIORequest(CBFilterBypassIORequestEventParams *e);
typedef struct {
const char *FileName;
int RequestCode;
void *FileContext;
void *HandleContext;
int Status;
char *Reason; int lenReason; int reserved; } CBFilterBypassIORequestEventParams;
Unicode (Windows) virtual INT FireBypassIORequest(CBFilterBypassIORequestEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestCode;
LPVOID FileContext;
LPVOID HandleContext;
INT Status;
LPWSTR Reason; INT lenReason; INT reserved; } CBFilterBypassIORequestEventParams;
#define EID_CBFILTER_BYPASSIOREQUEST 64

virtual INT CBFSFILTER_CALL FireBypassIORequest(LPWSTR &lpszFileName, INT &iRequestCode, LPVOID &lpFileContext, LPVOID &lpHandleContext, INT &iStatus, LPWSTR &lpReason, INT &lenReason);
class CBFilterBypassIORequestEventParams {
public:
  const QString &FileName();

  int RequestCode();

  void *FileContext();

  void *HandleContext();

  int Status();
  void SetStatus(int iStatus);

  const QString &Reason();
  bool SetReason(const QString &lpReason);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BypassIORequest(CBFilterBypassIORequestEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireBypassIORequest(CBFilterBypassIORequestEventParams *e) {...}

Remarks

This event fires when the OS sends a BypassIO request to a file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If BypassIO is enabled successfully future operations on the specified file handle will not be visible to the class. To ensure all future operations on the file are visible to the class BypassIO should not be enabled. BypassIO is present in Windows 11; it is not used in Windows 10 and earlier systems, and also is not used in Server systems.

Applications need to handle this event only if they have added a standard filter rule that includes the any of the following flags: FS_BYPASS_IO (it should be passed among notification flags), FS_CE_BEFORE_READ, FS_CE_AFTER_READ, FS_CE_BEFORE_WRITE, FS_CE_AFTER_WRITE.

The RequestCode parameter contains the code of the request. The code may be the one of the following:

BPIO_OP_ENABLE1Requests that BypassIO be enabled for the given file, which means an application might not see all non-cached reads for that file.

BPIO_OP_DISABLE2Informs that BypassIO is being disabled on the specified file.

BPIO_OP_QUERY3Queries whether BypassIO can be enabled for the given file.

BPIO_OP_VOLUME_STACK_PAUSE4Requests that BypassIO be paused on the specified volume/storage stack.

BPIO_OP_VOLUME_STACK_RESUME5Requests that BypassIO processing be resumed on the given volume.

BPIO_OP_STREAM_PAUSE6Requests that BypassIO processing be paused on a stream.

BPIO_OP_STREAM_RESUME7Requests that BypassIO processing be resumed on a stream.

BPIO_OP_GET_INFO8Requests information about the BypassIO state of the volume.

When the request code is BPIO_OP_ENABLE, an application is able to block BypassIO by specifying a non-zero value for Status and a description of the reason in the Reason parameter. If the application does so, it should return the same status and reason in response to BPIO_OP_QUERY requests to let the caller know that enabling would not be possible. BPIO_OP_QUERY requests are used, in particular, by diagnostics tools. Other operations may not be denied, and when the event is fired for one of those other operations, the class ignores the values returned in the Status and Reason parameters.

The Status value should be one of the NTStatus codes defined in Windows SDK (Windows 11 SDK defines a group of STATUS_NOT_SUPPORTED_WITH_* constants for this).

The Reason should be set to a human-readable text that explains why BypassIO was blocked.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

CleanupContext Event (CBFilter Class)

This event fires when the application-defined data stored in one or more contexts need to be cleaned up.

Syntax

ANSI (Cross Platform)
virtual int FireCleanupContext(CBFilterCleanupContextEventParams *e);
typedef struct {
void *FileContext;
void *HandleContext;
int ResultCode; int reserved; } CBFilterCleanupContextEventParams;
Unicode (Windows) virtual INT FireCleanupContext(CBFilterCleanupContextEventParams *e);
typedef struct {
LPVOID FileContext;
LPVOID HandleContext;
INT ResultCode; INT reserved; } CBFilterCleanupContextEventParams;
#define EID_CBFILTER_CLEANUPCONTEXT 65

virtual INT CBFSFILTER_CALL FireCleanupContext(LPVOID &lpFileContext, LPVOID &lpHandleContext, INT &iResultCode);
class CBFilterCleanupContextEventParams {
public:
  void *FileContext();

  void *HandleContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void CleanupContext(CBFilterCleanupContextEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireCleanupContext(CBFilterCleanupContextEventParams *e) {...}

Remarks

This event fires after a file or directory is closed, just before any contexts related to it are discarded, giving applications a chance to clean up any information stored in them.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

When a handle to some file or directory is closed, this event will fire if the HandleContext associated with that handle is not NULL. When the last handle to the file or directory is closed, this event will fire if the HandleContext associated with that handle or the FileContext associated with that file or directory is not NULL. After this event fires, the applicable contexts are set back to NULL automatically.

Applications that need to know the name of the file or directory this event is firing for should store a copy of that name in the context during an earlier event.

This event is optional; it will fire regardless of whether any filter rules are present, but only if FileContext, HandleContext, or both, are not already NULL. Applications that clean up their contexts (and set them back to NULL) when a file is being closed, or earlier, do not need to handle this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

Error Event (CBFilter Class)

This event fires if an unhandled error occurs during an event.

Syntax

ANSI (Cross Platform)
virtual int FireError(CBFilterErrorEventParams *e);
typedef struct {
int ErrorCode;
const char *Description; int reserved; } CBFilterErrorEventParams;
Unicode (Windows) virtual INT FireError(CBFilterErrorEventParams *e);
typedef struct {
INT ErrorCode;
LPCWSTR Description; INT reserved; } CBFilterErrorEventParams;
#define EID_CBFILTER_ERROR 66

virtual INT CBFSFILTER_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);
class CBFilterErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Error(CBFilterErrorEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireError(CBFilterErrorEventParams *e) {...}

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

FilterStart Event (CBFilter Class)

This event fires once the filter has attached and filtering has started.

Syntax

ANSI (Cross Platform)
virtual int FireFilterStart(CBFilterFilterStartEventParams *e);
typedef struct {
int ResultCode; int reserved; } CBFilterFilterStartEventParams;
Unicode (Windows) virtual INT FireFilterStart(CBFilterFilterStartEventParams *e);
typedef struct {
INT ResultCode; INT reserved; } CBFilterFilterStartEventParams;
#define EID_CBFILTER_FILTERSTART 67

virtual INT CBFSFILTER_CALL FireFilterStart(INT &iResultCode);
class CBFilterFilterStartEventParams {
public:
  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void FilterStart(CBFilterFilterStartEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireFilterStart(CBFilterFilterStartEventParams *e) {...}

Remarks

This event fires once the filter has attached and filtering has started; please refer to the StartFilter method for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

FilterStop Event (CBFilter Class)

This event fires once filtering has stopped and the filter has detached.

Syntax

ANSI (Cross Platform)
virtual int FireFilterStop(CBFilterFilterStopEventParams *e);
typedef struct {
int ResultCode; int reserved; } CBFilterFilterStopEventParams;
Unicode (Windows) virtual INT FireFilterStop(CBFilterFilterStopEventParams *e);
typedef struct {
INT ResultCode; INT reserved; } CBFilterFilterStopEventParams;
#define EID_CBFILTER_FILTERSTOP 68

virtual INT CBFSFILTER_CALL FireFilterStop(INT &iResultCode);
class CBFilterFilterStopEventParams {
public:
  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void FilterStop(CBFilterFilterStopEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireFilterStop(CBFilterFilterStopEventParams *e) {...}

Remarks

This event fires once filtering has stopped and the filter has detached.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

NotifyCanFileBeDeleted Event (CBFilter Class)

This event fires when the OS marks a file or directory for deletion or removes such a mark.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyCanFileBeDeleted(CBFilterNotifyCanFileBeDeletedEventParams *e);
typedef struct {
const char *FileName;
int RequestType;
int CanDelete;
int Status;
int ResultCode; int reserved; } CBFilterNotifyCanFileBeDeletedEventParams;
Unicode (Windows) virtual INT FireNotifyCanFileBeDeleted(CBFilterNotifyCanFileBeDeletedEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestType;
BOOL CanDelete;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyCanFileBeDeletedEventParams;
#define EID_CBFILTER_NOTIFYCANFILEBEDELETED 69

virtual INT CBFSFILTER_CALL FireNotifyCanFileBeDeleted(LPWSTR &lpszFileName, INT &iRequestType, BOOL &bCanDelete, INT &iStatus, INT &iResultCode);
class CBFilterNotifyCanFileBeDeletedEventParams {
public:
  const QString &FileName();

  int RequestType();

  bool CanDelete();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyCanFileBeDeleted(CBFilterNotifyCanFileBeDeletedEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyCanFileBeDeleted(CBFilterNotifyCanFileBeDeletedEventParams *e) {...}

Remarks

This event fires when the OS marks the file or directory specified by FileName for deletion or removes such a mark. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Files and directories can be deleted in two ways: (1) a file or directory can be opened with the FILE_FLAG_DELETE_ON_CLOSE flag, or (2) some process may call Windows API's NtSetInformationFile function with FILE_DISPOSITION_INFORMATION or FILE_DISPOSITION_INFORMATION_EX structure as a parameter.

If the file or directory is created or opened with the FILE_FLAG_DELETE_ON_CLOSE flag, this event is fired shortly after the NotifyCreateFile or NotifyOpenFile event.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_CAN_DELETE flag.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

DEL_REQ_OPEN_FLAG0x1The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag

DEL_REQ_SET_DISPOSITION0x2The system has sent the IRP_MJ_SET_INFORMATION request with SetFileDisposition structure as a parameter.

This request usually is sent using the NtSetInformationFile() Windows native API function.

The CanDelete parameter reflects whether or not the file or directory can be deleted.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCleanupFile Event (CBFilter Class)

This event fires when a file or directory handle has been closed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyCleanupFile(CBFilterNotifyCleanupFileEventParams *e);
typedef struct {
const char *FileName;
int ResultCode; int reserved; } CBFilterNotifyCleanupFileEventParams;
Unicode (Windows) virtual INT FireNotifyCleanupFile(CBFilterNotifyCleanupFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ResultCode; INT reserved; } CBFilterNotifyCleanupFileEventParams;
#define EID_CBFILTER_NOTIFYCLEANUPFILE 70

virtual INT CBFSFILTER_CALL FireNotifyCleanupFile(LPWSTR &lpszFileName, INT &iResultCode);
class CBFilterNotifyCleanupFileEventParams {
public:
  const QString &FileName();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyCleanupFile(CBFilterNotifyCleanupFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyCleanupFile(CBFilterNotifyCleanupFileEventParams *e) {...}

Remarks

This event fires when a handle to the file or directory specified by FileName has been closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event differs from NotifyCloseFile in that NotifyCleanupFile fires when an open handle to the specified file or directory is closed by a process, whereas NotifyCloseFile may be fired much later when the OS itself decides that the file or directory can be formally closed.

Other events may fire for the file or directory in the time between when this event fires and when the NotifyCloseFile event fires. For example, system components, such as the memory manager or cache manager, may cause the NotifyReadFile and NotifyWriteFile events to fire.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_CLEANUP flag.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCloseFile Event (CBFilter Class)

This event fires when a file or directory has been closed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyCloseFile(CBFilterNotifyCloseFileEventParams *e);
typedef struct {
const char *FileName;
int ResultCode; int reserved; } CBFilterNotifyCloseFileEventParams;
Unicode (Windows) virtual INT FireNotifyCloseFile(CBFilterNotifyCloseFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ResultCode; INT reserved; } CBFilterNotifyCloseFileEventParams;
#define EID_CBFILTER_NOTIFYCLOSEFILE 71

virtual INT CBFSFILTER_CALL FireNotifyCloseFile(LPWSTR &lpszFileName, INT &iResultCode);
class CBFilterNotifyCloseFileEventParams {
public:
  const QString &FileName();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyCloseFile(CBFilterNotifyCloseFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyCloseFile(CBFilterNotifyCloseFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_CLOSE flag.

If the file or directory was marked for deletion earlier, the NotifyDeleteFile will fire shortly before this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCreateFile Event (CBFilter Class)

This event fires when a file or directory has been created.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyCreateFile(CBFilterNotifyCreateFileEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int DesiredAccess;
int Attributes;
int ShareMode;
int Options;
int CreateDisposition;
const void *SecurityDescriptor;
int Length;
int Status;
int CreationStatus;
int ResultCode; int reserved; } CBFilterNotifyCreateFileEventParams;
Unicode (Windows) virtual INT FireNotifyCreateFile(CBFilterNotifyCreateFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
INT DesiredAccess;
INT Attributes;
INT ShareMode;
INT Options;
INT CreateDisposition;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
INT CreationStatus;
INT ResultCode; INT reserved; } CBFilterNotifyCreateFileEventParams;
#define EID_CBFILTER_NOTIFYCREATEFILE 72

virtual INT CBFSFILTER_CALL FireNotifyCreateFile(LPWSTR &lpszFileName, INT &iExistingAttributes, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iCreationStatus, INT &iResultCode);
class CBFilterNotifyCreateFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  int DesiredAccess();

  int Attributes();

  int ShareMode();

  int Options();

  int CreateDisposition();

  const void *SecurityDescriptor();

  int Length();

  int Status();

  int CreationStatus();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyCreateFile(CBFilterNotifyCreateFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyCreateFile(CBFilterNotifyCreateFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or NotifyOpenFile.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_CREATE flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory creation requests.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

The DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE IRP).

DesiredAccess may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to true and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

CreateDisposition may contain one of the following values:

FILE_DISPOSITION_CREATE_NEW0x00000001Creates a new file, only if it does not already exist.

If the specified file exists, the operation fails with an "already exists" error.

FILE_DISPOSITION_CREATE_ALWAYS0x00000002Creates a new file, always.

If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.

FILE_DISPOSITION_OPEN_EXISTING0x00000003Opens a file, only if it exists

If the specified file does not exist, opening fails.

FILE_DISPOSITION_OPEN_ALWAYS0x00000004Opens a file, always.

If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.

FILE_DISPOSITION_TRUNCATE_EXISTING0x00000005Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the operation fails with a "file not found" error.

Options contains the flags that are described in the CreateOptions parameter of the native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to the native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request was for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present if it was specified by the calling process or if the existing filesystem entry is a directory.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE; Note: Because files can be deleted in different ways, do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the NotifyCanFileBeDeleted event will fire after this event.

If the file is created with extended attributes passed in the request, the NotifySetEa event will fire after this event.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The CreationStatus parameter indicates whether the file was created or opened and can be one of the following values:

CREATION_STATUS_SUPERSEDED0x00000000An existing file was superseded by the new file.

The previous version of a file may still exist if it had hard links other than the name used in the operation.

CREATION_STATUS_OPENED0x00000001The file existed before the operation and was opened.

CREATION_STATUS_CREATED0x00000002The file didn't exist before the operation and was created.

CREATION_STATUS_OVERWRITTEN0x00000003The file exists, and its contents have been replaced.

CREATION_STATUS_EXISTS0x00000004The file existed before the operation, and no action was taken.

CREATION_STATUS_DOES_NOT_EXIST0x000000055The file did not exist before the operation, and no action was taken.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCreateHardLink Event (CBFilter Class)

This event fires when a hard link has been created.

Syntax

Remarks

This event fires when a hard link to the file specified by FileName has been created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to Microsoft's Hard Links article for more information about hard links.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_CREATE_HARD_LINK flag.

The LinkName parameter reflects the name of the created hard link.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyDeleteFile Event (CBFilter Class)

This event fires when a file or directory has been deleted.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyDeleteFile(CBFilterNotifyDeleteFileEventParams *e);
typedef struct {
const char *FileName;
int RequestType;
int ResultCode; int reserved; } CBFilterNotifyDeleteFileEventParams;
Unicode (Windows) virtual INT FireNotifyDeleteFile(CBFilterNotifyDeleteFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT RequestType;
INT ResultCode; INT reserved; } CBFilterNotifyDeleteFileEventParams;
#define EID_CBFILTER_NOTIFYDELETEFILE 74

virtual INT CBFSFILTER_CALL FireNotifyDeleteFile(LPWSTR &lpszFileName, INT &iRequestType, INT &iResultCode);
class CBFilterNotifyDeleteFileEventParams {
public:
  const QString &FileName();

  int RequestType();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyDeleteFile(CBFilterNotifyDeleteFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyDeleteFile(CBFilterNotifyDeleteFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been deleted. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. More specifically, this event is queued for delivery after the final IRP_MJ_CLOSE I/O request packet (IRP) has been processed by the filesystem (i.e., after the last handle to the file or directory is closed and the file or directory is gone) and before NotifyCloseFile is queued.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_DELETE flag.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

DEL_REQ_OPEN_FLAG0x1The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag

DEL_REQ_SET_DISPOSITION0x2The system has sent the IRP_MJ_SET_INFORMATION request with SetFileDisposition structure as a parameter.

This request usually is sent using the NtSetInformationFile() Windows native API function.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyDeleteReparsePoint Event (CBFilter Class)

This event fires when a file or directory's reparse point has been deleted.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyDeleteReparsePoint(CBFilterNotifyDeleteReparsePointEventParams *e);
typedef struct {
const char *FileName;
int Status;
int ResultCode; int reserved; } CBFilterNotifyDeleteReparsePointEventParams;
Unicode (Windows) virtual INT FireNotifyDeleteReparsePoint(CBFilterNotifyDeleteReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyDeleteReparsePointEventParams;
#define EID_CBFILTER_NOTIFYDELETEREPARSEPOINT 75

virtual INT CBFSFILTER_CALL FireNotifyDeleteReparsePoint(LPWSTR &lpszFileName, INT &iStatus, INT &iResultCode);
class CBFilterNotifyDeleteReparsePointEventParams {
public:
  const QString &FileName();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyDeleteReparsePoint(CBFilterNotifyDeleteReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyDeleteReparsePoint(CBFilterNotifyDeleteReparsePointEventParams *e) {...}

Remarks

This event fires when a reparse point has been deleted from the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: The file or directory was not deleted, only a reparse point was.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_DELETE_REPARSE_POINT flag.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyEnumerateDirectory Event (CBFilter Class)

This event fires when a directory entry has been returned during directory enumeration.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyEnumerateDirectory(CBFilterNotifyEnumerateDirectoryEventParams *e);
typedef struct {
const char *DirectoryName;
int Flags;
int Index;
const char *FileName;
int64 CreationTime;
int64 LastAccessTime;
int64 LastWriteTime;
int64 ChangeTime;
int64 Size;
int64 AllocationSize;
int64 FileId;
int Attributes;
int Status;
int ResultCode; int reserved; } CBFilterNotifyEnumerateDirectoryEventParams;
Unicode (Windows) virtual INT FireNotifyEnumerateDirectory(CBFilterNotifyEnumerateDirectoryEventParams *e);
typedef struct {
LPCWSTR DirectoryName;
INT Flags;
INT Index;
LPCWSTR FileName;
LONG64 CreationTime;
LONG64 LastAccessTime;
LONG64 LastWriteTime;
LONG64 ChangeTime;
LONG64 Size;
LONG64 AllocationSize;
LONG64 FileId;
INT Attributes;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyEnumerateDirectoryEventParams;
#define EID_CBFILTER_NOTIFYENUMERATEDIRECTORY 76

virtual INT CBFSFILTER_CALL FireNotifyEnumerateDirectory(LPWSTR &lpszDirectoryName, INT &iFlags, INT &iIndex, LPWSTR &lpszFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, LONG64 &lSize, LONG64 &lAllocationSize, LONG64 &lFileId, INT &iAttributes, INT &iStatus, INT &iResultCode);
class CBFilterNotifyEnumerateDirectoryEventParams {
public:
  const QString &DirectoryName();

  int Flags();

  int Index();

  const QString &FileName();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastWriteTime();

  const QDateTime &ChangeTime();

  qint64 Size();

  qint64 AllocationSize();

  qint64 FileId();

  int Attributes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyEnumerateDirectory(CBFilterNotifyEnumerateDirectoryEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyEnumerateDirectory(CBFilterNotifyEnumerateDirectoryEventParams *e) {...}

Remarks

This event fires when a directory entry (i.e., file or subdirectory) has been returned during enumeration of the directory specified by DirectoryName. For more information about the DirectoryName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_ENUMERATE_DIRECTORY flag.

The Flags parameter specifies supplementary information about enumeration. It is a combination of zero or more values:

FS_ENUM_RESTART_SCAN1The requestor specified that directory enumeration must be restarted.

FS_ENUM_RETURN_SINGLE_ENTRY2One entry should be returned.

FS_ENUM_INDEX_SPECIFIED4The requestor specified the index to start enumeration from.

If the Flags parameter contains FS_ENUM_INDEX_SPECIFIED, the Index parameter contains the index as provided by the OS.

The FileName parameter reflects the name of the directory entry.

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters reflect the entry's time values, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

The Size parameter reflects the size of the file, in bytes; it is always 0 for subdirectories.

The AllocationSize parameter reflects the amount of space allocated for the file, in bytes; it is always 0 for subdirectories.

The FileId parameter reflects the unique Id of the entry, as reported by the filesystem. This Id is used by the network redirector, and some third-party applications, to open files and directories by Id instead of by name. The root directory always uses the predefined Id 0x7FFFFFFFFFFFFFFF.

The Attributes parameter reflects the entry's attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyFilterAttachToVolume Event (CBFilter Class)

This event fires when the filter has been attached to a newly mounted filesystem volume.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyFilterAttachToVolume(CBFilterNotifyFilterAttachToVolumeEventParams *e);
typedef struct {
const char *VolumeName;
const char *VolumeNameNT;
int ResultCode; int reserved; } CBFilterNotifyFilterAttachToVolumeEventParams;
Unicode (Windows) virtual INT FireNotifyFilterAttachToVolume(CBFilterNotifyFilterAttachToVolumeEventParams *e);
typedef struct {
LPCWSTR VolumeName;
LPCWSTR VolumeNameNT;
INT ResultCode; INT reserved; } CBFilterNotifyFilterAttachToVolumeEventParams;
#define EID_CBFILTER_NOTIFYFILTERATTACHTOVOLUME 77

virtual INT CBFSFILTER_CALL FireNotifyFilterAttachToVolume(LPWSTR &lpszVolumeName, LPWSTR &lpszVolumeNameNT, INT &iResultCode);
class CBFilterNotifyFilterAttachToVolumeEventParams {
public:
  const QString &VolumeName();

  const QString &VolumeNameNT();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyFilterAttachToVolume(CBFilterNotifyFilterAttachToVolumeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyFilterAttachToVolume(CBFilterNotifyFilterAttachToVolumeEventParams *e) {...}

Remarks

This event fires when the filter has been attached to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_NOTIFY flag.

Note: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications that use volume-specific rules should typically add such rules during the AfterFilterAttachToVolume event, which is fired synchronously, rather than this one.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

NotifyFilterDetachFromVolume Event (CBFilter Class)

This event fires when the filter has been detached from a filesystem volume.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyFilterDetachFromVolume(CBFilterNotifyFilterDetachFromVolumeEventParams *e);
typedef struct {
const char *VolumeName;
const char *VolumeNameNT;
int ResultCode; int reserved; } CBFilterNotifyFilterDetachFromVolumeEventParams;
Unicode (Windows) virtual INT FireNotifyFilterDetachFromVolume(CBFilterNotifyFilterDetachFromVolumeEventParams *e);
typedef struct {
LPCWSTR VolumeName;
LPCWSTR VolumeNameNT;
INT ResultCode; INT reserved; } CBFilterNotifyFilterDetachFromVolumeEventParams;
#define EID_CBFILTER_NOTIFYFILTERDETACHFROMVOLUME 78

virtual INT CBFSFILTER_CALL FireNotifyFilterDetachFromVolume(LPWSTR &lpszVolumeName, LPWSTR &lpszVolumeNameNT, INT &iResultCode);
class CBFilterNotifyFilterDetachFromVolumeEventParams {
public:
  const QString &VolumeName();

  const QString &VolumeNameNT();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyFilterDetachFromVolume(CBFilterNotifyFilterDetachFromVolumeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyFilterDetachFromVolume(CBFilterNotifyFilterDetachFromVolumeEventParams *e) {...}

Remarks

This event fires when the filter has been detached from the filesystem volume specified by VolumeNameNT and, when possible, VolumeName, typically as a result of the volume being unmounted. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_NOTIFY flag.

Note: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications that use volume-specific rules typically should remove such rules during the AfterFilterDetachFromVolume event, which is fired synchronously, rather than this one.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

NotifyFsctl Event (CBFilter Class)

This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyFsctl(CBFilterNotifyFsctlEventParams *e);
typedef struct {
const char *FileName;
int FsControlCode;
const void *InBuffer;
int InBufferLength;
int InBufferValidBytes;
const void *OutBuffer;
int OutBufferLength;
int OutBufferValidBytes;
int Status;
int ResultCode; int reserved; } CBFilterNotifyFsctlEventParams;
Unicode (Windows) virtual INT FireNotifyFsctl(CBFilterNotifyFsctlEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FsControlCode;
LPCVOID InBuffer;
INT InBufferLength;
INT InBufferValidBytes;
LPCVOID OutBuffer;
INT OutBufferLength;
INT OutBufferValidBytes;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyFsctlEventParams;
#define EID_CBFILTER_NOTIFYFSCTL 79

virtual INT CBFSFILTER_CALL FireNotifyFsctl(LPWSTR &lpszFileName, INT &iFsControlCode, LPVOID &lpInBuffer, INT &iInBufferLength, INT &iInBufferValidBytes, LPVOID &lpOutBuffer, INT &iOutBufferLength, INT &iOutBufferValidBytes, INT &iStatus, INT &iResultCode);
class CBFilterNotifyFsctlEventParams {
public:
  const QString &FileName();

  int FsControlCode();

  const void *InBuffer();

  int InBufferLength();

  int InBufferValidBytes();

  const void *OutBuffer();

  int OutBufferLength();

  int OutBufferValidBytes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyFsctl(CBFilterNotifyFsctlEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyFsctl(CBFilterNotifyFsctlEventParams *e) {...}

Remarks

This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL (FSCTL) operation has occurred. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwFsControlFile function (kernel mode); please refer to Microsoft's documentation for more information.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_FSCTL flag.

The FileName parameter reflects the file, directory, or volume targeted by the request.

The FsControlCode parameter reflects the requested filesystem control code (FSCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that contains the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation did not return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyGetFileSecurity Event (CBFilter Class)

This event fires when a file or directory's security attributes have been retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyGetFileSecurity(CBFilterNotifyGetFileSecurityEventParams *e);
typedef struct {
const char *FileName;
int SecurityInformation;
const void *SecurityDescriptor;
int Length;
int Status;
int ResultCode; int reserved; } CBFilterNotifyGetFileSecurityEventParams;
Unicode (Windows) virtual INT FireNotifyGetFileSecurity(CBFilterNotifyGetFileSecurityEventParams *e);
typedef struct {
LPCWSTR FileName;
INT SecurityInformation;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyGetFileSecurityEventParams;
#define EID_CBFILTER_NOTIFYGETFILESECURITY 80

virtual INT CBFSFILTER_CALL FireNotifyGetFileSecurity(LPWSTR &lpszFileName, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iResultCode);
class CBFilterNotifyGetFileSecurityEventParams {
public:
  const QString &FileName();

  int SecurityInformation();

  const void *SecurityDescriptor();

  int Length();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyGetFileSecurity(CBFilterNotifyGetFileSecurityEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyGetFileSecurity(CBFilterNotifyGetFileSecurityEventParams *e) {...}

Remarks

This event fires when security attributes have been retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: This event will not fire every time a file or directory is accessed. To check file security upon each access to a file or directory, implement the file create and open events and perform the necessary checks there instead.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_GET_SECURITY flag.

The SecurityInformation parameter indicates which pieces of security information were requested. Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that, if the request was successful, contains the requested security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyGetFileSizes Event (CBFilter Class)

This event fires when a file's size information has been retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyGetFileSizes(CBFilterNotifyGetFileSizesEventParams *e);
typedef struct {
const char *FileName;
int64 Size;
int64 AllocationSize;
int Status;
int ResultCode; int reserved; } CBFilterNotifyGetFileSizesEventParams;
Unicode (Windows) virtual INT FireNotifyGetFileSizes(CBFilterNotifyGetFileSizesEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Size;
LONG64 AllocationSize;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyGetFileSizesEventParams;
#define EID_CBFILTER_NOTIFYGETFILESIZES 81

virtual INT CBFSFILTER_CALL FireNotifyGetFileSizes(LPWSTR &lpszFileName, LONG64 &lSize, LONG64 &lAllocationSize, INT &iStatus, INT &iResultCode);
class CBFilterNotifyGetFileSizesEventParams {
public:
  const QString &FileName();

  qint64 Size();

  qint64 AllocationSize();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyGetFileSizes(CBFilterNotifyGetFileSizesEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyGetFileSizes(CBFilterNotifyGetFileSizesEventParams *e) {...}

Remarks

This event fires when size information has been retrieved for the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_GET_SIZES flag.

The Size parameter reflects the actual size of the file, in bytes.

The AllocationSize parameter reflects the amount of space allocated for the file, in bytes.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyGetReparsePoint Event (CBFilter Class)

This event fires when a file or directory's reparse point information has been retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyGetReparsePoint(CBFilterNotifyGetReparsePointEventParams *e);
typedef struct {
const char *FileName;
int Status;
int ResultCode; int reserved; } CBFilterNotifyGetReparsePointEventParams;
Unicode (Windows) virtual INT FireNotifyGetReparsePoint(CBFilterNotifyGetReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyGetReparsePointEventParams;
#define EID_CBFILTER_NOTIFYGETREPARSEPOINT 82

virtual INT CBFSFILTER_CALL FireNotifyGetReparsePoint(LPWSTR &lpszFileName, INT &iStatus, INT &iResultCode);
class CBFilterNotifyGetReparsePointEventParams {
public:
  const QString &FileName();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyGetReparsePoint(CBFilterNotifyGetReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyGetReparsePoint(CBFilterNotifyGetReparsePointEventParams *e) {...}

Remarks

This event fires when reparse point information has been retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_GET_REPARSE_POINT flag.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyIoctl Event (CBFilter Class)

This event fires when an IRP_MJ_DEVICE_CONTROL operation has occurred.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyIoctl(CBFilterNotifyIoctlEventParams *e);
typedef struct {
const char *FileName;
int IoControlCode;
const void *InBuffer;
int InBufferLength;
int InBufferValidBytes;
const void *OutBuffer;
int OutBufferLength;
int OutBufferValidBytes;
int Status;
int ResultCode; int reserved; } CBFilterNotifyIoctlEventParams;
Unicode (Windows) virtual INT FireNotifyIoctl(CBFilterNotifyIoctlEventParams *e);
typedef struct {
LPCWSTR FileName;
INT IoControlCode;
LPCVOID InBuffer;
INT InBufferLength;
INT InBufferValidBytes;
LPCVOID OutBuffer;
INT OutBufferLength;
INT OutBufferValidBytes;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyIoctlEventParams;
#define EID_CBFILTER_NOTIFYIOCTL 83

virtual INT CBFSFILTER_CALL FireNotifyIoctl(LPWSTR &lpszFileName, INT &iIoControlCode, LPVOID &lpInBuffer, INT &iInBufferLength, INT &iInBufferValidBytes, LPVOID &lpOutBuffer, INT &iOutBufferLength, INT &iOutBufferValidBytes, INT &iStatus, INT &iResultCode);
class CBFilterNotifyIoctlEventParams {
public:
  const QString &FileName();

  int IoControlCode();

  const void *InBuffer();

  int InBufferLength();

  int InBufferValidBytes();

  const void *OutBuffer();

  int OutBufferLength();

  int OutBufferValidBytes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyIoctl(CBFilterNotifyIoctlEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyIoctl(CBFilterNotifyIoctlEventParams *e) {...}

Remarks

This event fires when an IRP_MJ_DEVICE_CONTROL (IOCTL) operation has occurred. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwDeviceIoControlFile function (kernel mode). Please refer to Microsoft's documentation for more information.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_IOCTL flag.

The FileName parameter reflects the file, directory, or volume targeted by the request.

The IoControlCode parameter reflects the requested I/O control code (IOCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that contains the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation did not return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyLock Event (CBFilter Class)

This event fires when a range of bytes in a file has been locked.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyLock(CBFilterNotifyLockEventParams *e);
typedef struct {
const char *FileName;
int64 Offset;
int64 Length;
int64 Key;
int FailImmediately;
int ExclusiveLock;
int Status;
int ResultCode; int reserved; } CBFilterNotifyLockEventParams;
Unicode (Windows) virtual INT FireNotifyLock(CBFilterNotifyLockEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Offset;
LONG64 Length;
LONG64 Key;
BOOL FailImmediately;
BOOL ExclusiveLock;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyLockEventParams;
#define EID_CBFILTER_NOTIFYLOCK 84

virtual INT CBFSFILTER_CALL FireNotifyLock(LPWSTR &lpszFileName, LONG64 &lOffset, LONG64 &lLength, LONG64 &lKey, BOOL &bFailImmediately, BOOL &bExclusiveLock, INT &iStatus, INT &iResultCode);
class CBFilterNotifyLockEventParams {
public:
  const QString &FileName();

  qint64 Offset();

  qint64 Length();

  qint64 Key();

  bool FailImmediately();

  bool ExclusiveLock();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyLock(CBFilterNotifyLockEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyLock(CBFilterNotifyLockEventParams *e) {...}

Remarks

This event fires when a range of bytes in the file specified by FileName has been locked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This request is made either by the OS, or on behalf of a user mode application that called the Windows API's LockFile or LockFileEx function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_LOCK_CONTROL flag.

The Offset parameter reflects the byte offset where the byte range lock starts.

The Length parameter reflects the length of the byte range lock.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock in later unlock-by-key requests.

The FailImmediately parameter indicates whether the request was to fail if the lock could not be granted immediately.

The ExclusiveLock parameter indicates whether the byte range lock was to be exclusive (true) or shared (false).

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyOpenFile Event (CBFilter Class)

This event fires when a file or directory has been opened.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyOpenFile(CBFilterNotifyOpenFileEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int DesiredAccess;
int Attributes;
int ShareMode;
int Options;
int CreateDisposition;
const void *SecurityDescriptor;
int Length;
int Status;
int CreationStatus;
int ResultCode; int reserved; } CBFilterNotifyOpenFileEventParams;
Unicode (Windows) virtual INT FireNotifyOpenFile(CBFilterNotifyOpenFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
INT DesiredAccess;
INT Attributes;
INT ShareMode;
INT Options;
INT CreateDisposition;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
INT CreationStatus;
INT ResultCode; INT reserved; } CBFilterNotifyOpenFileEventParams;
#define EID_CBFILTER_NOTIFYOPENFILE 85

virtual INT CBFSFILTER_CALL FireNotifyOpenFile(LPWSTR &lpszFileName, INT &iExistingAttributes, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iCreationStatus, INT &iResultCode);
class CBFilterNotifyOpenFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  int DesiredAccess();

  int Attributes();

  int ShareMode();

  int Options();

  int CreateDisposition();

  const void *SecurityDescriptor();

  int Length();

  int Status();

  int CreationStatus();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyOpenFile(CBFilterNotifyOpenFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyOpenFile(CBFilterNotifyOpenFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been opened. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or NotifyCreateFile.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_OPEN flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory open requests.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

The DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE IRP).

DesiredAccess may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to true and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:

FILESYS_SHARE_READ0x00000001Enables subsequent open operations on a file or device to request read access.

Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILESYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file or device to request write access.

Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

FILESYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file or device to request delete access.

Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

CreateDisposition may contain one of the following values:

FILE_DISPOSITION_CREATE_NEW0x00000001Creates a new file, only if it does not already exist.

If the specified file exists, the operation fails with an "already exists" error.

FILE_DISPOSITION_CREATE_ALWAYS0x00000002Creates a new file, always.

If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.

FILE_DISPOSITION_OPEN_EXISTING0x00000003Opens a file, only if it exists

If the specified file does not exist, opening fails.

FILE_DISPOSITION_OPEN_ALWAYS0x00000004Opens a file, always.

If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.

FILE_DISPOSITION_TRUNCATE_EXISTING0x00000005Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the operation fails with a "file not found" error.

Options contains the flags that are described in the CreateOptions parameter of the native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to the native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request was for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present if it was specified by the calling process or if the existing filesystem entry is a directory.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE; Note: Because files can be deleted in different ways, do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the NotifyCanFileBeDeleted event will fire after this event.

If the file is opened with extended attributes passed in the request, the NotifySetEa event will fire after this event.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The CreationStatus parameter indicates whether the file was created or opened and can be one of the following values:

CREATION_STATUS_SUPERSEDED0x00000000An existing file was superseded by the new file.

The previous version of a file may still exist if it had hard links other than the name used in the operation.

CREATION_STATUS_OPENED0x00000001The file existed before the operation and was opened.

CREATION_STATUS_CREATED0x00000002The file didn't exist before the operation and was created.

CREATION_STATUS_OVERWRITTEN0x00000003The file exists, and its contents have been replaced.

CREATION_STATUS_EXISTS0x00000004The file existed before the operation, and no action was taken.

CREATION_STATUS_DOES_NOT_EXIST0x000000055The file did not exist before the operation, and no action was taken.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyQueryEa Event (CBFilter Class)

This event fires when information about the extended attributes of a file has been retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyQueryEa(CBFilterNotifyQueryEaEventParams *e);
typedef struct {
const char *FileName;
const void *Buffer;
int BufferLength;
int ReturnSingleEntry;
const void *EaList;
int EaListLength;
int EaIndex;
int RestartScan;
int LengthReturned;
int Status;
int ResultCode; int reserved; } CBFilterNotifyQueryEaEventParams;
Unicode (Windows) virtual INT FireNotifyQueryEa(CBFilterNotifyQueryEaEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCVOID Buffer;
INT BufferLength;
BOOL ReturnSingleEntry;
LPCVOID EaList;
INT EaListLength;
INT EaIndex;
BOOL RestartScan;
INT LengthReturned;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyQueryEaEventParams;
#define EID_CBFILTER_NOTIFYQUERYEA 86

virtual INT CBFSFILTER_CALL FireNotifyQueryEa(LPWSTR &lpszFileName, LPVOID &lpBuffer, INT &iBufferLength, BOOL &bReturnSingleEntry, LPVOID &lpEaList, INT &iEaListLength, INT &iEaIndex, BOOL &bRestartScan, INT &iLengthReturned, INT &iStatus, INT &iResultCode);
class CBFilterNotifyQueryEaEventParams {
public:
  const QString &FileName();

  const void *Buffer();

  int BufferLength();

  bool ReturnSingleEntry();

  const void *EaList();

  int EaListLength();

  int EaIndex();

  bool RestartScan();

  int LengthReturned();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyQueryEa(CBFilterNotifyQueryEaEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyQueryEa(CBFilterNotifyQueryEaEventParams *e) {...}

Remarks

This event fires when information about the extended attributes of a file specified by FileName has been retrieved. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_QUERY_EA flag.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the requested information. The data in the buffer are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The Length parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

ReturnSingleEntry specifies that the filesystem had to return only the first entry it has found.

EaList is an optional parameter that points to a caller-supplied memory buffer specifying the extended attributes to be queried. The data in the buffer are formatted as a FILE_GET_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The EaListLength parameter reflects the length of this data, in bytes. If the caller of the FltQueryEaFile function did not specify any value, it will contain 0.

EaIndex is an optional parameter that specifies the starting index of the attribute, information about which was requested. This parameter is ignored by the filesystem if EaList points to a nonempty list. If the caller of the FltQueryEaFile function did not specify any value, the parameter will contain -1.

The RestartScan parameter instructs the filesystem to restart enumeration of extended attributes from the first entry. If the parameter is false, retrieval of the extended attributes is resumed by the filesystem after a previous request.

LengthReturned is an optional parameter that contains the size, in bytes, of the information, returned in the Buffer.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyQueryFileInfo Event (CBFilter Class)

This event fires when information about a file or directory has been retrieved.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyQueryFileInfo(CBFilterNotifyQueryFileInfoEventParams *e);
typedef struct {
const char *FileName;
int FileInformationClass;
const void *Buffer;
int BufferLength;
int ValidBytes;
int Status;
int ResultCode; int reserved; } CBFilterNotifyQueryFileInfoEventParams;
Unicode (Windows) virtual INT FireNotifyQueryFileInfo(CBFilterNotifyQueryFileInfoEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FileInformationClass;
LPCVOID Buffer;
INT BufferLength;
INT ValidBytes;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyQueryFileInfoEventParams;
#define EID_CBFILTER_NOTIFYQUERYFILEINFO 87

virtual INT CBFSFILTER_CALL FireNotifyQueryFileInfo(LPWSTR &lpszFileName, INT &iFileInformationClass, LPVOID &lpBuffer, INT &iBufferLength, INT &iValidBytes, INT &iStatus, INT &iResultCode);
class CBFilterNotifyQueryFileInfoEventParams {
public:
  const QString &FileName();

  int FileInformationClass();

  const void *Buffer();

  int BufferLength();

  int ValidBytes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyQueryFileInfo(CBFilterNotifyQueryFileInfoEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyQueryFileInfo(CBFilterNotifyQueryFileInfoEventParams *e) {...}

Remarks

This event fires when information about a file or directory specified by FileName has been retrieved. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtQueryInformationFile function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_QUERY_FILE_INFO flag.

The FileInformationClass parameter indicates what kind of file information was requested. Please refer to the NtQueryInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the requested file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtQueryInformationFile function's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyReadFile Event (CBFilter Class)

This event fires when data have been read from a file.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyReadFile(CBFilterNotifyReadFileEventParams *e);
typedef struct {
const char *FileName;
int64 Position;
int BytesToRead;
int Direction;
int BytesRead;
int Status;
int ResultCode; int reserved; } CBFilterNotifyReadFileEventParams;
Unicode (Windows) virtual INT FireNotifyReadFile(CBFilterNotifyReadFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Position;
INT BytesToRead;
INT Direction;
INT BytesRead;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyReadFileEventParams;
#define EID_CBFILTER_NOTIFYREADFILE 88

virtual INT CBFSFILTER_CALL FireNotifyReadFile(LPWSTR &lpszFileName, LONG64 &lPosition, INT &iBytesToRead, INT &iDirection, INT &iBytesRead, INT &iStatus, INT &iResultCode);
class CBFilterNotifyReadFileEventParams {
public:
  const QString &FileName();

  qint64 Position();

  int BytesToRead();

  int Direction();

  int BytesRead();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyReadFile(CBFilterNotifyReadFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyReadFile(CBFilterNotifyReadFileEventParams *e) {...}

Remarks

This event fires when data have been read from a file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_READ flag.

The Position parameter reflects the byte offset in the file at which reading started.

The BytesToRead parameter reflects how many bytes were to be read from the file.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the user mode application <--> filesystem direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the user mode application <--> system cache direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the system cache <--> filesystem direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the system component <--> system cache direction.

The BytesRead parameter reflects how many bytes were actually read from the file.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyRenameOrMoveFile Event (CBFilter Class)

This event fires when a file or directory has been renamed or moved.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyRenameOrMoveFile(CBFilterNotifyRenameOrMoveFileEventParams *e);
typedef struct {
const char *FileName;
const char *NewFileName;
int Status;
int ResultCode; int reserved; } CBFilterNotifyRenameOrMoveFileEventParams;
Unicode (Windows) virtual INT FireNotifyRenameOrMoveFile(CBFilterNotifyRenameOrMoveFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCWSTR NewFileName;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyRenameOrMoveFileEventParams;
#define EID_CBFILTER_NOTIFYRENAMEORMOVEFILE 89

virtual INT CBFSFILTER_CALL FireNotifyRenameOrMoveFile(LPWSTR &lpszFileName, LPWSTR &lpszNewFileName, INT &iStatus, INT &iResultCode);
class CBFilterNotifyRenameOrMoveFileEventParams {
public:
  const QString &FileName();

  const QString &NewFileName();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyRenameOrMoveFile(CBFilterNotifyRenameOrMoveFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyRenameOrMoveFile(CBFilterNotifyRenameOrMoveFileEventParams *e) {...}

Remarks

This event fires when a file or directory specified by FileName has been renamed or moved to NewFileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_RENAME flag. A rule's mask is matched against both previous and new file names, and the event will fire when either of the names matches the mask.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetAllocationSize Event (CBFilter Class)

This event fires when a file's allocation size has been changed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetAllocationSize(CBFilterNotifySetAllocationSizeEventParams *e);
typedef struct {
const char *FileName;
int64 AllocationSize;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetAllocationSizeEventParams;
Unicode (Windows) virtual INT FireNotifySetAllocationSize(CBFilterNotifySetAllocationSizeEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 AllocationSize;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetAllocationSizeEventParams;
#define EID_CBFILTER_NOTIFYSETALLOCATIONSIZE 90

virtual INT CBFSFILTER_CALL FireNotifySetAllocationSize(LPWSTR &lpszFileName, LONG64 &lAllocationSize, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetAllocationSizeEventParams {
public:
  const QString &FileName();

  qint64 AllocationSize();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetAllocationSize(CBFilterNotifySetAllocationSizeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetAllocationSize(CBFilterNotifySetAllocationSizeEventParams *e) {...}

Remarks

This event fires when the allocation size of the file specified by FileName has been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_SET_SIZES flag.

The AllocationSize parameter reflects the new allocation size, in bytes. A file's allocation size is typically larger than its actual size because filesystem operations often reserve space on disk before writing additional data to a file.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetEa Event (CBFilter Class)

This event fires when information about the extended attributes of a file has been changed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetEa(CBFilterNotifySetEaEventParams *e);
typedef struct {
const char *FileName;
const void *Buffer;
int BufferLength;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetEaEventParams;
Unicode (Windows) virtual INT FireNotifySetEa(CBFilterNotifySetEaEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCVOID Buffer;
INT BufferLength;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetEaEventParams;
#define EID_CBFILTER_NOTIFYSETEA 91

virtual INT CBFSFILTER_CALL FireNotifySetEa(LPWSTR &lpszFileName, LPVOID &lpBuffer, INT &iBufferLength, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetEaEventParams {
public:
  const QString &FileName();

  const void *Buffer();

  int BufferLength();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetEa(CBFilterNotifySetEaEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetEa(CBFilterNotifySetEaEventParams *e) {...}

Remarks

This event fires when information about the extended attributes of a file specified by FileName has been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If the file is created or opened with extended attributes passed in the request, this event will fire shortly after the NotifyCreateFile or NotifyOpenFile event.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_SET_EA flag.

The Buffer parameter points to a memory buffer that specifies the extended attribute information. The Length parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetFileAttributes Event (CBFilter Class)

This event fires when a file or directory's attributes or times have been changed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetFileAttributes(CBFilterNotifySetFileAttributesEventParams *e);
typedef struct {
const char *FileName;
int64 CreationTime;
int64 LastAccessTime;
int64 LastWriteTime;
int64 ChangeTime;
int Attributes;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetFileAttributesEventParams;
Unicode (Windows) virtual INT FireNotifySetFileAttributes(CBFilterNotifySetFileAttributesEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 CreationTime;
LONG64 LastAccessTime;
LONG64 LastWriteTime;
LONG64 ChangeTime;
INT Attributes;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetFileAttributesEventParams;
#define EID_CBFILTER_NOTIFYSETFILEATTRIBUTES 92

virtual INT CBFSFILTER_CALL FireNotifySetFileAttributes(LPWSTR &lpszFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, INT &iAttributes, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetFileAttributesEventParams {
public:
  const QString &FileName();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastWriteTime();

  const QDateTime &ChangeTime();

  int Attributes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetFileAttributes(CBFilterNotifySetFileAttributesEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetFileAttributes(CBFilterNotifySetFileAttributesEventParams *e) {...}

Remarks

This event fires when the attributes or times of the file or directory specified by FileName have been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_SET_ATTRIBUTES flag.

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters reflect the new time values, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. A value of 0 indicates that the corresponding time value was not included in the request.

The Attributes parameter reflects the new attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetFileInfo Event (CBFilter Class)

This event fires when information about a file or directory has been changed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetFileInfo(CBFilterNotifySetFileInfoEventParams *e);
typedef struct {
const char *FileName;
int FileInformationClass;
const void *Buffer;
int BufferLength;
int ValidBytes;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetFileInfoEventParams;
Unicode (Windows) virtual INT FireNotifySetFileInfo(CBFilterNotifySetFileInfoEventParams *e);
typedef struct {
LPCWSTR FileName;
INT FileInformationClass;
LPCVOID Buffer;
INT BufferLength;
INT ValidBytes;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetFileInfoEventParams;
#define EID_CBFILTER_NOTIFYSETFILEINFO 93

virtual INT CBFSFILTER_CALL FireNotifySetFileInfo(LPWSTR &lpszFileName, INT &iFileInformationClass, LPVOID &lpBuffer, INT &iBufferLength, INT &iValidBytes, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetFileInfoEventParams {
public:
  const QString &FileName();

  int FileInformationClass();

  const void *Buffer();

  int BufferLength();

  int ValidBytes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetFileInfo(CBFilterNotifySetFileInfoEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetFileInfo(CBFilterNotifySetFileInfoEventParams *e) {...}

Remarks

This event fires when information about a file or directory specified by FileName has been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtSetInformationFile function.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_QUERY_FILE_INFO flag.

The FileInformationClass parameter indicates what kind of file information was set. Please refer to the NtSetInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the new file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtSetInformationFile function's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetFileSecurity Event (CBFilter Class)

This event fires when a file or directory's security attributes have been changed.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetFileSecurity(CBFilterNotifySetFileSecurityEventParams *e);
typedef struct {
const char *FileName;
int SecurityInformation;
const void *SecurityDescriptor;
int Length;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetFileSecurityEventParams;
Unicode (Windows) virtual INT FireNotifySetFileSecurity(CBFilterNotifySetFileSecurityEventParams *e);
typedef struct {
LPCWSTR FileName;
INT SecurityInformation;
LPCVOID SecurityDescriptor;
INT Length;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetFileSecurityEventParams;
#define EID_CBFILTER_NOTIFYSETFILESECURITY 94

virtual INT CBFSFILTER_CALL FireNotifySetFileSecurity(LPWSTR &lpszFileName, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetFileSecurityEventParams {
public:
  const QString &FileName();

  int SecurityInformation();

  const void *SecurityDescriptor();

  int Length();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetFileSecurity(CBFilterNotifySetFileSecurityEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetFileSecurity(CBFilterNotifySetFileSecurityEventParams *e) {...}

Remarks

This event fires when security attributes have been changed for a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_SET_SECURITY flag.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, were to be set. Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the new security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetFileSize Event (CBFilter Class)

This event fires when a file has been resized.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetFileSize(CBFilterNotifySetFileSizeEventParams *e);
typedef struct {
const char *FileName;
int64 Size;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetFileSizeEventParams;
Unicode (Windows) virtual INT FireNotifySetFileSize(CBFilterNotifySetFileSizeEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Size;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetFileSizeEventParams;
#define EID_CBFILTER_NOTIFYSETFILESIZE 95

virtual INT CBFSFILTER_CALL FireNotifySetFileSize(LPWSTR &lpszFileName, LONG64 &lSize, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetFileSizeEventParams {
public:
  const QString &FileName();

  qint64 Size();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetFileSize(CBFilterNotifySetFileSizeEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetFileSize(CBFilterNotifySetFileSizeEventParams *e) {...}

Remarks

This event fires when the file specified by FileName has been resized, whether explicitly (e.g., truncation) or implicitly (i.e., as data are appended). For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_SET_SIZES flag.

The Size parameter reflects the new file size, in bytes.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifySetReparsePoint Event (CBFilter Class)

This event fires when a file or directory's reparse point has been created or updated.

Syntax

ANSI (Cross Platform)
virtual int FireNotifySetReparsePoint(CBFilterNotifySetReparsePointEventParams *e);
typedef struct {
const char *FileName;
int64 ReparseTag;
int Status;
int ResultCode; int reserved; } CBFilterNotifySetReparsePointEventParams;
Unicode (Windows) virtual INT FireNotifySetReparsePoint(CBFilterNotifySetReparsePointEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 ReparseTag;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifySetReparsePointEventParams;
#define EID_CBFILTER_NOTIFYSETREPARSEPOINT 96

virtual INT CBFSFILTER_CALL FireNotifySetReparsePoint(LPWSTR &lpszFileName, LONG64 &lReparseTag, INT &iStatus, INT &iResultCode);
class CBFilterNotifySetReparsePointEventParams {
public:
  const QString &FileName();

  qint64 ReparseTag();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifySetReparsePoint(CBFilterNotifySetReparsePointEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifySetReparsePoint(CBFilterNotifySetReparsePointEventParams *e) {...}

Remarks

This event fires when a reparse point has been created or updated for a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_SET_REPARSE_POINT flag.

The ReparseTag parameter contains the reparse tag, which is the value the system uses to identify the format of the reparse point data.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyUnlockAll Event (CBFilter Class)

This event fires when all locked byte ranges in a file have been unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyUnlockAll(CBFilterNotifyUnlockAllEventParams *e);
typedef struct {
const char *FileName;
int Status;
int ResultCode; int reserved; } CBFilterNotifyUnlockAllEventParams;
Unicode (Windows) virtual INT FireNotifyUnlockAll(CBFilterNotifyUnlockAllEventParams *e);
typedef struct {
LPCWSTR FileName;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyUnlockAllEventParams;
#define EID_CBFILTER_NOTIFYUNLOCKALL 97

virtual INT CBFSFILTER_CALL FireNotifyUnlockAll(LPWSTR &lpszFileName, INT &iStatus, INT &iResultCode);
class CBFilterNotifyUnlockAllEventParams {
public:
  const QString &FileName();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyUnlockAll(CBFilterNotifyUnlockAllEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyUnlockAll(CBFilterNotifyUnlockAllEventParams *e) {...}

Remarks

This event fires when all locked byte ranges in the file specified by FileName have been unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_LOCK_CONTROL flag.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyUnlockAllByKey Event (CBFilter Class)

This event fires when all locked byte ranges in a file, associated with a particular key, have been unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyUnlockAllByKey(CBFilterNotifyUnlockAllByKeyEventParams *e);
typedef struct {
const char *FileName;
int64 Key;
int Status;
int ResultCode; int reserved; } CBFilterNotifyUnlockAllByKeyEventParams;
Unicode (Windows) virtual INT FireNotifyUnlockAllByKey(CBFilterNotifyUnlockAllByKeyEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Key;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyUnlockAllByKeyEventParams;
#define EID_CBFILTER_NOTIFYUNLOCKALLBYKEY 98

virtual INT CBFSFILTER_CALL FireNotifyUnlockAllByKey(LPWSTR &lpszFileName, LONG64 &lKey, INT &iStatus, INT &iResultCode);
class CBFilterNotifyUnlockAllByKeyEventParams {
public:
  const QString &FileName();

  qint64 Key();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyUnlockAllByKey(CBFilterNotifyUnlockAllByKeyEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyUnlockAllByKey(CBFilterNotifyUnlockAllByKeyEventParams *e) {...}

Remarks

This event fires when all locked byte ranges in the file specified by FileName, and associated with the specified Key, have been unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_LOCK_CONTROL flag.

The Key parameter contains the key value specified when the byte ranges were locked. Please refer to the NotifyLock event's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyUnlockSingle Event (CBFilter Class)

This event fires when a particular locked byte range in a file has been unlocked.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyUnlockSingle(CBFilterNotifyUnlockSingleEventParams *e);
typedef struct {
const char *FileName;
int64 Offset;
int64 Length;
int64 Key;
int Status;
int ResultCode; int reserved; } CBFilterNotifyUnlockSingleEventParams;
Unicode (Windows) virtual INT FireNotifyUnlockSingle(CBFilterNotifyUnlockSingleEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Offset;
LONG64 Length;
LONG64 Key;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyUnlockSingleEventParams;
#define EID_CBFILTER_NOTIFYUNLOCKSINGLE 99

virtual INT CBFSFILTER_CALL FireNotifyUnlockSingle(LPWSTR &lpszFileName, LONG64 &lOffset, LONG64 &lLength, LONG64 &lKey, INT &iStatus, INT &iResultCode);
class CBFilterNotifyUnlockSingleEventParams {
public:
  const QString &FileName();

  qint64 Offset();

  qint64 Length();

  qint64 Key();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyUnlockSingle(CBFilterNotifyUnlockSingleEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyUnlockSingle(CBFilterNotifyUnlockSingleEventParams *e) {...}

Remarks

This event fires when a particular locked byte range in a file specified by FileName has been unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_LOCK_CONTROL flag.

The Offset, Length, and Key parameters contain the starting byte offset, length, and key values, respectively, specified when the byte range was locked. Please refer to the NotifyLock event's documentation for more information.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyWriteFile Event (CBFilter Class)

This event fires when data have been written to a file.

Syntax

ANSI (Cross Platform)
virtual int FireNotifyWriteFile(CBFilterNotifyWriteFileEventParams *e);
typedef struct {
const char *FileName;
int64 Position;
int BytesToWrite;
int Direction;
int BytesWritten;
int Status;
int ResultCode; int reserved; } CBFilterNotifyWriteFileEventParams;
Unicode (Windows) virtual INT FireNotifyWriteFile(CBFilterNotifyWriteFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 Position;
INT BytesToWrite;
INT Direction;
INT BytesWritten;
INT Status;
INT ResultCode; INT reserved; } CBFilterNotifyWriteFileEventParams;
#define EID_CBFILTER_NOTIFYWRITEFILE 100

virtual INT CBFSFILTER_CALL FireNotifyWriteFile(LPWSTR &lpszFileName, LONG64 &lPosition, INT &iBytesToWrite, INT &iDirection, INT &iBytesWritten, INT &iStatus, INT &iResultCode);
class CBFilterNotifyWriteFileEventParams {
public:
  const QString &FileName();

  qint64 Position();

  int BytesToWrite();

  int Direction();

  int BytesWritten();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void NotifyWriteFile(CBFilterNotifyWriteFileEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireNotifyWriteFile(CBFilterNotifyWriteFileEventParams *e) {...}

Remarks

This event fires when data have been written to the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_WRITE flag.

The Position parameter reflects the byte offset in the file at which writing started. A value of -1 means "append to the end of the file".

The BytesToWrite parameter reflects how many bytes were to be written to the file.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the user mode application <--> filesystem direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the user mode application <--> system cache direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the system cache <--> filesystem direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the system component <--> system cache direction.

The BytesWritten parameter reflects how many bytes were actually written to the file.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

ReparseFileName Event (CBFilter Class)

This event fires to allow file access to be dynamically redirected to another location.

Syntax

ANSI (Cross Platform)
virtual int FireReparseFileName(CBFilterReparseFileNameEventParams *e);
typedef struct {
const char *FileName;
int DesiredAccess;
const char *ReparsedFileName;
char *NewFileName; int lenNewFileName;
void *EventContext;
int ResultCode; int reserved; } CBFilterReparseFileNameEventParams;
Unicode (Windows) virtual INT FireReparseFileName(CBFilterReparseFileNameEventParams *e);
typedef struct {
LPCWSTR FileName;
INT DesiredAccess;
LPCWSTR ReparsedFileName;
LPWSTR NewFileName; INT lenNewFileName;
LPVOID EventContext;
INT ResultCode; INT reserved; } CBFilterReparseFileNameEventParams;
#define EID_CBFILTER_REPARSEFILENAME 101

virtual INT CBFSFILTER_CALL FireReparseFileName(LPWSTR &lpszFileName, INT &iDesiredAccess, LPWSTR &lpszReparsedFileName, LPWSTR &lpNewFileName, INT &lenNewFileName, LPVOID &lpEventContext, INT &iResultCode);
class CBFilterReparseFileNameEventParams {
public:
  const QString &FileName();

  int DesiredAccess();

  const QString &ReparsedFileName();

  const QString &NewFileName();
  bool SetNewFileName(const QString &lpNewFileName);

  void *EventContext();
  void SetEventContext(void *lpEventContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void ReparseFileName(CBFilterReparseFileNameEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireReparseFileName(CBFilterReparseFileNameEventParams *e) {...}

Remarks

Applications can use this event to dynamically redirect access to the file or directory specified by FileName to another location. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

The event fires before a file or directory is created or opened (before the corresponding BeforeCreateFile or BeforeOpenFile events fire).

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_REPARSE_FILENAME flag.

The DesiredAccess parameter reflects the value that was passed for the similarly named parameter of the Windows API's CreateFile function. Please refer to Microsoft's documentation for more information.

The ReparsedFileName parameter reflects the default redirection destination. If the specified file or directory matches an existing reparse rule, this parameter's value is generated based on said rule; otherwise, this parameter will reflect the same value as FileName.

The NewFileName parameter specifies an application-defined redirection destination. This parameter's value, if set, must be less than 1024 characters in length. Note that the value must be copied to NewFileName; set lenNewFileName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

If the application sets NewFileName to a nonempty value, it will be used as the redirection destination. Otherwise, the value reflected by ReparseFileName will be used as the redirection destination.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The value assigned to EventContext by the event handler will reach BeforeCreateFile/BeforeOpenFile events and other events involved in the opening of the file.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

ReparseWithTag Event (CBFilter Class)

This event fires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point.

Syntax

ANSI (Cross Platform)
virtual int FireReparseWithTag(CBFilterReparseWithTagEventParams *e);
typedef struct {
const char *FileName;
const char *NewFileName;
int ReparseTag;
const void *ReparseBuffer;
int ReparseBufferLength;
void *FileContext;
void *HandleContext;
void *EventContext;
int ReissueIO;
int ResultCode; int reserved; } CBFilterReparseWithTagEventParams;
Unicode (Windows) virtual INT FireReparseWithTag(CBFilterReparseWithTagEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCWSTR NewFileName;
INT ReparseTag;
LPCVOID ReparseBuffer;
INT ReparseBufferLength;
LPVOID FileContext;
LPVOID HandleContext;
LPVOID EventContext;
BOOL ReissueIO;
INT ResultCode; INT reserved; } CBFilterReparseWithTagEventParams;
#define EID_CBFILTER_REPARSEWITHTAG 102

virtual INT CBFSFILTER_CALL FireReparseWithTag(LPWSTR &lpszFileName, LPWSTR &lpszNewFileName, INT &iReparseTag, LPVOID &lpReparseBuffer, INT &iReparseBufferLength, LPVOID &lpFileContext, LPVOID &lpHandleContext, LPVOID &lpEventContext, BOOL &bReissueIO, INT &iResultCode);
class CBFilterReparseWithTagEventParams {
public:
  const QString &FileName();

  const QString &NewFileName();

  int ReparseTag();

  const void *ReparseBuffer();

  int ReparseBufferLength();

  void *FileContext();

  void *HandleContext();

  void *EventContext();

  bool ReissueIO();
  void SetReissueIO(bool bReissueIO);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void ReparseWithTag(CBFilterReparseWithTagEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireReparseWithTag(CBFilterReparseWithTagEventParams *e) {...}

Remarks

This event fires if a STATUS_REPARSE result is returned when the OS attempts to open the file or directory specified by FileName, which indicates that a reparse point is associated with said file or directory or one of its parents. More specifically, it fires immediately after the open operation returns such a result. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

It is possible for applications to add reparse points to specific files/directories so that the filesystem will return STATUS_REPARSE when someone attempts to open them. Such applications can then use this event to perform some operation on the file/directory, assuming that the specified ReparseTag belongs to the application. Please refer to Microsoft's Reparse Point articles for more information.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_CE_REPARSE_TAG flag.

If the reparse tag was recognized by the filesystem or some filesystem filter, NewFileName can contain the new path, to which the request should be sent.

The ReparseTag parameter reflects the reparse point's tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; the class extracts it and provides it separately for convenience.

The ReparseBuffer parameter points to a memory buffer that contains the full reparse point data. The ReparseBufferLength parameter reflects the length of ReparseBuffer. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted using either a REPARSE_GUID_DATA_BUFFER structure or (for certain Microsoft-reserved tags) a REPARSE_DATA_BUFFER structure; please refer to Microsoft's documentation for more information.

If the part of the path contained in FileName constitutes a symbolic link or a junction point (both of which are handled by the filesystem), the structure in ReparseBuffer will contain the new path that is to replace a part of the original path. In such a case, the Reserved field of the REPARSE_DATA_BUFFER structure will contain the length in bytes in the original file name buffer that remains unchanged. This value, divided by 2, is the number of characters at the end of FileName that you must append to the new path, contained in ReparseBuffer.

ReissueIO can be set to true to instruct the OS to resend the original request again from the beginning. This may be necessary if the reparse tag is removed from the file or altered during this event.

Please refer to the Reparse Points topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

WorkerThreadCreation Event (CBFilter Class)

Fires just after a new worker thread is created.

Syntax

ANSI (Cross Platform)
virtual int FireWorkerThreadCreation(CBFilterWorkerThreadCreationEventParams *e);
typedef struct {
int ResultCode; int reserved; } CBFilterWorkerThreadCreationEventParams;
Unicode (Windows) virtual INT FireWorkerThreadCreation(CBFilterWorkerThreadCreationEventParams *e);
typedef struct {
INT ResultCode; INT reserved; } CBFilterWorkerThreadCreationEventParams;
#define EID_CBFILTER_WORKERTHREADCREATION 103

virtual INT CBFSFILTER_CALL FireWorkerThreadCreation(INT &iResultCode);
class CBFilterWorkerThreadCreationEventParams {
public:
  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void WorkerThreadCreation(CBFilterWorkerThreadCreationEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireWorkerThreadCreation(CBFilterWorkerThreadCreationEventParams *e) {...}

Remarks

This event fires just after a worker thread is created, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing when a new worker thread is created, such as allocating per-thread objects.

The class maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

WorkerThreadTermination Event (CBFilter Class)

Fires just before a worker thread is terminated.

Syntax

ANSI (Cross Platform)
virtual int FireWorkerThreadTermination(CBFilterWorkerThreadTerminationEventParams *e);
typedef struct { int reserved; } CBFilterWorkerThreadTerminationEventParams;
Unicode (Windows) virtual INT FireWorkerThreadTermination(CBFilterWorkerThreadTerminationEventParams *e);
typedef struct { INT reserved; } CBFilterWorkerThreadTerminationEventParams;
#define EID_CBFILTER_WORKERTHREADTERMINATION 104

virtual INT CBFSFILTER_CALL FireWorkerThreadTermination();
class CBFilterWorkerThreadTerminationEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void WorkerThreadTermination(CBFilterWorkerThreadTerminationEventParams *e);
// Or, subclass CBFilter and override this emitter function. virtual int FireWorkerThreadTermination(CBFilterWorkerThreadTerminationEventParams *e) {...}

Remarks

This event fires just before a worker thread is terminated, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing before a worker thread is terminated, such as deallocating per-thread objects.

The class maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

Any errors that occur during this event are ignored.

This event is fired synchronously; please refer to the Event Types topic for more information.

FileDefaultRule Type

This type represents a filesystem default rule.

Syntax

CBFSFilterFileDefaultRule (declared in cbfsfilter.h)

Remarks

This type represents a filesystem default rule. Please refer to the Default Rules topic for more information.

The following fields are available:

Fields

AccessFlags
int (read-only)

Default Value: 0

This field indicates the access restrictions enforced by the rule.

This field indicates which access restrictions are enforced by the rule. Please refer to the Default Rules topic for more information. The value of this field is a combination of zero or more of the following:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

Mask
char* (read-only)

Default Value: ""

This field indicates a file mask that determines which files and directories match the rule.

This field reflects the file mask used to determine whether a file or directory matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

Note: When a rule with a drive letter is added, said drive letter is automatically converted to NT Device format. When the ResolveNtDeviceToDriveLetter configuration setting is disabled, this field's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the class attempts to convert the mask back to the DOS format with a drive letter. In some situations, such backward conversion can lead to a path that was different from the original path added.

FileFilterRule Type

This type represents a filesystem filter rule.

Syntax

CBFSFilterFileFilterRule (declared in cbfsfilter.h)

Remarks

This type represents a filesystem filter rule, which may be a standard filter rule, an access rule, or a combination of both. Please refer to the File and Registry Filter Rules and Access Rules topics for more information.

The following fields are available:

Fields

AccessFlags
int (read-only)

Default Value: 0

This field indicates the access restrictions enforced by the rule (CBFilter only).

This field indicates which access restrictions are enforced by the rule. Please refer to the Access Rules topic for more information. The value of this field is a combination of zero or more of the following:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

Note: This field is always 0 for the CBMonitor class, which does not support access rules.

ControlFlags
int64 (read-only)

Default Value: 0

This field indicates which control events the rule causes the class to fire (CBFilter only).

This field indicates which filesystem operations, of those performed on matching files and directories, the class should fire Control Events for. The value of this field is a combination of zero or more of the following:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

Note: This field is always 0 for the CBMonitor class, which does not provide any Control Events for filesystem operations.

EaName
char* (read-only)

Default Value: ""

This field indicates the name of an extended attribute that a file or directory must have to match the rule.

This field reflects the name of an extended attribute that a file or directory must have to qualify as a match for the rule. A value of an empty string indicates that the rule does not use this field as a match qualifier.

ExcludedAttributes
int64 (read-only)

Default Value: 0

This field indicates the file attributes that a file or directory must not have to match the rule.

This field indicates which file attributes a file or directory must not have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this field as a match qualifier.

IncludedAttributes
int64 (read-only)

Default Value: 0

This field indicates the file attributes that a file or directory must have to match the rule.

This field indicates which file attributes a file or directory must have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this field as a match qualifier.

Mask
char* (read-only)

Default Value: ""

This field indicates a file mask that determines which files and directories match the rule.

This field reflects the file mask used to determine whether a file or directory matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

Note: When a rule with a drive letter is added, said drive letter is automatically converted to NT Device format. When the ResolveNtDeviceToDriveLetter configuration setting is disabled, this field's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the class attempts to convert the mask back to the DOS format with a drive letter. In some situations, such backward conversion can lead to a path that was different from the original path added.

MaxSize
int64 (read-only)

Default Value: 0

This field indicates the maximum size a file can be to match the rule.

This field indicates the maximum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this field as a match qualifier.

MinSize
int64 (read-only)

Default Value: 0

This field indicates the minimum size a file can be to match the rule.

This field indicates the minimum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this field as a match qualifier.

NotifyFlags
int64 (read-only)

Default Value: 0

This field indicates which notification events the rule causes the class to fire.

This field indicates which filesystem operations, of those performed on matching files and directories, the class should fire Notification Events for. The value of this field is a combination of zero or more of the following:

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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

FilePassthroughRule Type

This type represents a filesystem passthrough rule.

Syntax

CBFSFilterFilePassthroughRule (declared in cbfsfilter.h)

Remarks

This type represents a filesystem passthrough rule. Please refer to the Passthrough Rules topic for more information.

The following fields are available:

Fields

AccessFlags
int (read-only)

Default Value: 0

This field specifies the access restrictions lifted by the rule (CBFilter only).

This field indicates which access restrictions are lifted by the rule. Please refer to the Passthrough Rules topic for more information. The value of this field is a combination of zero or more of the following:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

Note: This field is always 0 for the CBMonitor class, which does not support access rules.

ControlFlags
int64 (read-only)

Default Value: 0

This field indicates which control events the rule prevents the class from firing (CBFilter only).

This field indicates which filesystem operations, of those performed on matching files and directories, the class should not fire Control Events for. Please refer to the Passthrough Rules topic for more information. The value of this field is a combination of zero or more of the following:

FS_CE_NONE0Don't fire for any filesystem operations.

Control Events will not fire for any filesystem operations.

FS_CE_BEFORE_CREATE0x000000000001LFire before file creation operations.

The BeforeCreateFile event will fire anytime the OS attempts to create a file or directory. In some cases, this event can cause the BeforeOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_CREATE0x000000000002LFire after file creation operations.

The AfterCreateFile event will fire after a file or directory creation request has been processed, before the response is returned. In some cases, this event can cause the AfterOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_OPEN0x000000000004LFire before file open operations.

The BeforeOpenFile event will fire anytime the OS attempts to open a file or directory. In some cases, this event can cause the BeforeCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_AFTER_OPEN0x000000000008LFire after file open operations.

The AfterOpenFile event will fire after a file or directory open request has been processed, before the response is returned. In some cases, this event can cause the AfterCreateFile event to fire; refer to the File Create/Open Events topic for more information.

FS_CE_BEFORE_READ0x000000000010LFire before read operations.

The BeforeReadFile event will fire anytime the OS attempts to read data from a file.

FS_CE_AFTER_READ0x000000000020LFire after read operations.

The AfterReadFile event will fire after a read request has been processed, before the response is returned.

FS_CE_BEFORE_WRITE0x000000000040LFire before write operations.

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

FS_CE_AFTER_WRITE0x000000000080LFire after write operations.

The AfterReadFile event will fire after a write request has been processed, before the response is returned.

FS_CE_BEFORE_LOCK_CONTROL0x000000000100LFire before lock and unlock operations.

The BeforeLock, BeforeUnlockAll, BeforeUnlockAllByKey, and BeforeUnlockSingle events will fire, as applicable, before the OS attempts to lock or unlock a range of bytes in a file.

FS_CE_AFTER_LOCK_CONTROL0x000000000200LFire before and after lock and unlock operations.

The AfterLock, AfterUnlockAll, AfterUnlockAllByKey, and AfterUnlockSingle, events will fire, as applicable, after a lock or unlock request has been processed, before the response is returned.

FS_CE_BEFORE_CLEANUP0x000000000400LFire before file handle cleanup operations.

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

FS_CE_AFTER_CLEANUP0x000000000800LFire after file handle cleanup operations.

The AfterCleanupFile event will fire after a file handle cleanup request has been processed, before the response is returned.

FS_CE_BEFORE_CLOSE0x000000001000LFire before file close operations.

The BeforeCloseFile event will fire anytime the OS closes a file or directory. Also, the AfterCloseEnumeration event will fire anytime the OS closes a directory enumeration (which typically occurs immediately before the directory is closed).

FS_CE_AFTER_CLOSE0x000000002000LFire after file close operations.

The AfterCloseFile event will fire after a file/directory close request has been processed, before the response is returned.

FS_CE_BEFORE_CAN_DELETE0x000000004000LFire before 'can be deleted' operations.

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

FS_CE_AFTER_CAN_DELETE0x000000008000LFire after 'can be deleted' operations.

The AfterCanFileBeDeleted event will fire after a can be deleted request has been processed, before the response is returned.

FS_CE_BEFORE_DELETE0x000000010000LFire before delete operations

The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory.

FS_CE_AFTER_DELETE0x000000020000LFire after delete operations.

The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned.

FS_CE_BEFORE_RENAME0x000000040000LFire before rename/move operations.

The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory.

FS_CE_AFTER_RENAME0x000000080000LFire after rename/move operations.

The AfterRenameOrMoveFile event will fire after a rename or move request has been processed, before the response is returned.

FS_CE_BEFORE_GET_SECURITY0x000000100000LFire before get security operations.

The BeforeGetFileSecurity event will fire before the OS queries the security attributes of a file or directory.

FS_CE_AFTER_GET_SECURITY0x000000200000LFire after get security operations.

The AfterGetFileSecurity events will fire after a get security operation has been processed, before the response is returned.

FS_CE_BEFORE_ENUMERATE_DIRECTORY0x000000400000LFire before directory enumeration operations.

The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries.

FS_CE_AFTER_ENUMERATE_DIRECTORY0x000000800000LFire after directory enumeration operations.

The AfterEnumerateDirectory event will fire after information about a directory entry has been retrieved during directory enumeration, before the response is returned.

FS_CE_BEFORE_QUERY_FILE_INFO0x000001000000LFire before 'query file information' operations.

The BeforeQueryFileInfo event will fire anytime the OS needs to retrieve information about a file or directory.

FS_CE_AFTER_QUERY_FILE_INFO0x000002000000LFire after 'query file information' operations.

The AfterQueryFileInfo event will fire after a file or directory information query request has been processed, before the response is returned.

FS_CE_AFTER_GET_SIZES0x000008000000LFire after get size operations.

The AfterGetFileSizes event will fire after a file's size information is retrieved, before the response is returned.

FS_CE_BEFORE_SET_SECURITY0x000010000000LFire before set security operations.

The BeforeSetFileSecurity event will fire anytime the OS needs to change the security attributes of a file or directory.

FS_CE_AFTER_SET_SECURITY0x000020000000LFire after set security operations.

The AfterSetFileSecurity event will fire after a security attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_ATTRIBUTES0x000040000000LFire before file attribute update operations.

The BeforeSetFileAttributes event will fire anytime the OS attempts to change the attributes of a file or directory.

FS_CE_AFTER_SET_ATTRIBUTES0x000080000000LFire after file attribute update operations.

The AfterSetFileAttributes event will fire after a file attribute change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_SIZES0x000100000000LFire before file resize operations.

The BeforeSetFileSize event will fire anytime the OS attempts to resize a file, and the BeforeSetAllocationSize event will fire anytime the OS attempts to change a file's allocation size.

FS_CE_AFTER_SET_SIZES0x000200000000LFire after file resize operations.

The AfterSetFileSize event will fire after a file resize request has been processed, and the AfterSetAllocationSize event will fire after a file allocation size change request has been processed, before the response is returned.

FS_CE_BEFORE_CREATE_HARD_LINK0x000400000000LFire before hard link creation operations.

The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link.

FS_CE_AFTER_CREATE_HARD_LINK0x000800000000LFire after hard link creation operations.

The AfterCreateHardLink events will fire after a hard link creation request has been processed, before the response is returned.

FS_CE_BEFORE_FSCTL0x001000000000LFire before FSCTL operations.

The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs.

FS_CE_AFTER_FSCTL0x002000000000LFire after FSCTL operations.

The AfterFsctl event will fire after an IRP_MJ_FILE_SYSTEM_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_IOCTL0x004000000000LFire before IOCTL operations.

The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs.

FS_CE_AFTER_IOCTL0x008000000000LFire after IOCTL operations.

The AfterIoctl event will fire after an IRP_MJ_DEVICE_CONTROL request has been processed, before the response is returned.

FS_CE_BEFORE_SET_FILE_INFO0x010000000000LFire before 'set file information' operations.

The BeforeSetFileInfo event will fire anytime the OS needs to change information about a file or directory.

FS_CE_AFTER_SET_FILE_INFO0x020000000000LFire after 'set file information' operations.

The AfterSetFileInfo event will fire after a file or directory information change request has been processed, before the response is returned.

FS_CE_BEFORE_SET_EA0x040000000000LFire before Set Extended Attributes operations.

The BeforeSetEa event will fire anytime the OS needs to set extended attributes of a file.

FS_CE_AFTER_SET_EA0x080000000000LFire after Set Extended Attributes operations.

The AfterSetEa event will fire after the OS request to set extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_QUERY_EA0x100000000000LFire before Query Extended Attributes operations.

The BeforeQueryEa event will fire anytime the OS needs to retrieve extended attributes of a file.

FS_CE_AFTER_QUERY_EA0x200000000000LFire after Query Extended Attributes operations.

The AfterQueryEa event will fire after the OS request to retrieve extended attributes of a file has been processed, before the response is returned.

FS_CE_BEFORE_GET_REPARSE_POINT0x400000000000LFire before Get Reparse Point operations.

The BeforeGetReparsePoint event will fire anytime the OS needs to read a reparse point of a file or directory.

FS_CE_AFTER_GET_REPARSE_POINT0x800000000000LFire after Get Reparse Point operations.

The AfterGetReparsePoint event will fire after the OS request to read a reparse point of a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_SET_REPARSE_POINT0x1000000000000LFire before Set Reparse Point operations.

The BeforeSetReparsePoint event will fire anytime the OS needs to set or update a reparse point for a file or directory.

FS_CE_AFTER_SET_REPARSE_POINT0x2000000000000LFire after Set Reparse Point operations.

The AfterSetReparsePoint event will fire after the OS request to set or update a reparse point for a file or directory has been processed, before the response is returned.

FS_CE_BEFORE_DELETE_REPARSE_POINT0x4000000000000LFire before Delete Reparse Point operations.

The BeforeDeleteReparsePoint event will fire anytime the OS needs to remove reparse point information from a file or directory.

FS_CE_AFTER_DELETE_REPARSE_POINT0x8000000000000LFire after Delete Reparse Point operations.

The AfterDeleteReparsePoint event will fire after the OS request to remove reparse point information from a file or directory has been processed, before the response is returned.

FS_CE_REPARSE_FILENAME0x40000000000000LFire before various operations for the purpose of file redirection.

The ReparseFileName event will fire before any operation that includes a file or directory name, giving the application a chance to redirect it. This event is typically used when an application requires more advanced redirection logic than Reparse Rules can provide; please refer to that topic for more information.

FS_CE_REPARSE_TAG0x80000000000000LFire for reparse operations.

The ReparseWithTag event will fire anytime a file/directory open operation returns a STATUS_REPARSE result, allowing the application to handle the reparse point. Please refer to Microsoft's Reparse Points article for more information.

FS_CE_ALL-1Fire for all filesystem operations.

Control Events will fire for all filesystem operations that the class tracks.

Note: This field is always 0 for the CBMonitor class, which does not provide any Control Events for filesystem operations.

EaName
char* (read-only)

Default Value: ""

This field indicates the name of an extended attribute that a file or directory must have to match the rule.

This field reflects the name of an extended attribute that a file or directory must have to qualify as a match for the rule. A value of an empty string indicates that the rule does not use this field as a match qualifier.

ExcludedAttributes
int64 (read-only)

Default Value: 0

This field indicates the file attributes that a file or directory must not have to match the rule.

This field indicates which file attributes a file or directory must not have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this field as a match qualifier.

IncludedAttributes
int64 (read-only)

Default Value: 0

This field indicates the file attributes that a file or directory must have to match the rule.

This field indicates which file attributes a file or directory must have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this field as a match qualifier.

Mask
char* (read-only)

Default Value: ""

This field indicates a file mask that determines which files and directories match the rule.

This field reflects the file mask used to determine whether a file or directory matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

Note: When a rule with a drive letter is added, said drive letter is automatically converted to NT Device format. When the ResolveNtDeviceToDriveLetter configuration setting is disabled, this field's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the class attempts to convert the mask back to the DOS format with a drive letter. In some situations, such backward conversion can lead to a path that was different from the original path added.

MaxSize
int64 (read-only)

Default Value: 0

This field indicates the maximum size a file can be to match the rule.

This field indicates the maximum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this field as a match qualifier.

MinSize
int64 (read-only)

Default Value: 0

This field indicates the minimum size a file can be to match the rule.

This field indicates the minimum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this field as a match qualifier.

NotifyFlags
int64 (read-only)

Default Value: 0

This field indicates which notification events the rule prevents the class from firing.

This field indicates which filesystem operations, of those performed on matching files and directories, the class should not fire Notification Events for. Please refer to the Passthrough Rules topic for more information. The value of this field is a combination of zero or more of the following:

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 NotifyCreateFile event will fire anytime the OS creates a file or directory. In some cases, this event can cause the NotifyOpenFile event to fire; refer to the File Create/Open Events topic for more information.

FS_NE_OPEN0x00000002LFire for file open operations.

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

FS_NE_READ0x00000004LFire for read operations.

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

FS_NE_WRITE0x00000008LFire for write operations.

The NotifyWriteFile event will fire anytime the OS writes data to a file.

FS_NE_LOCK_CONTROL0x00000010LFire for lock and unlock operations.

The NotifyLock, NotifyUnlockAll, NotifyUnlockAllByKey, and NotifyUnlockSingle 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 NotifyCleanupFile event will fire anytime a process closes a file or directory handle.

FS_NE_CLOSE0x00000040LFire for file close operations.

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

FS_NE_CAN_DELETE0x00000080LFire for 'can be deleted' operations.

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

FS_NE_DELETE0x00000100LFire for delete operations.

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

FS_NE_RENAME0x00000200LFire for rename/move operations.

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

FS_NE_GET_SECURITY0x00000400LFire for get security operations.

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

FS_NE_ENUMERATE_DIRECTORY0x00000800LFire for directory enumeration operations.

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

FS_NE_QUERY_FILE_INFO0x00001000LFire for QueryFileInformation operations.

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

FS_NE_GET_SIZES0x00002000LFire for get size operations.

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

FS_NE_SET_SECURITY0x00004000LFire for set security operations.

The NotifySetFileSecurity 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 NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory.

FS_NE_SET_SIZES0x00010000LFire for file resize operations.

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

FS_NE_CREATE_HARD_LINK0x00020000LFire for hard link creation operations.

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

FS_NE_FSCTL0x00040000LFire for FSCTL operations.

The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs.

FS_NE_IOCTL0x00080000LFire for IOCTL operations.

The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs.

FS_NE_SET_FILE_INFO0x00100000LFire for SetFileInformation operations.

The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory.

FS_NE_SET_EA0x00200000LFire for Set Extended Attributes operations.

The NotifySetEa event will fire anytime the OS sets extended attributes of a file.

FS_NE_QUERY_EA0x00400000LFire for Query Extended Attributes operations.

The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file.

FS_NE_GET_REPARSE_POINT0x00800000LFire for Get Reparse Point operations.

The NotifyGetReparsePoint event will fire anytime the OS reads reparse point information of a file or directory.

FS_NE_SET_REPARSE_POINT0x01000000LFire for Set Reparse Point operations.

The NotifySetReparsePoint event will fire anytime the OS sets or updates reparse point information for a file or directory.

FS_NE_DELETE_REPARSE_POINT0x02000000LFire for Delete Reparse Point operations.

The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory.

FS_BYPASS_IO0x40000000LFire for BypassIO operations.

The BypassIORequest event will fire anytime the OS sends a BypassIO request related to some file. This flag should be passed with notification flags, even though the event is synchronous.

FS_NE_ALL-1Fire for all filesystem operations.

Notification Events will fire for all filesystem operations that the class tracks.

FileReparseRule Type

This type represents a filesystem reparse rule.

Syntax

CBFSFilterFileReparseRule (declared in cbfsfilter.h)

Remarks

This type represents a filesystem reparse rule. Please refer to the Reparse Rules topic for more information.

The following fields are available:

Fields

Mask
char* (read-only)

Default Value: ""

This field indicates a file mask that determines which files and directories match the rule.

This field reflects the file mask used to determine whether a file or directory matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

Note: When a rule with a drive letter is added, said drive letter is automatically converted to NT Device format. When the ResolveNtDeviceToDriveLetter configuration setting is disabled, this field's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the class attempts to convert the mask back to the DOS format with a drive letter. In some situations, such backward conversion can lead to a path that was different from the original path added.

ReparseMask
char* (read-only)

Default Value: ""

This field contains a file mask that specifies where matching files and directories are redirected to.

This field contains a file mask that specifies where files and directories that match Mask are redirected to. Please refer to the Reparse Rules topic for more information.

VirtualFile Type

This type represents a virtual file .

Syntax

CBFSFilterVirtualFile (declared in cbfsfilter.h)

Remarks

This type represents a virtual file , managed by by CBFilter class . The file can be added to the list using the AddVirtualFile method.

The following fields are available:

Fields

Attributes
int (read-only)

Default Value: 0

This field specifies various attributes of a virtual file.

This field specifies the attributes of the virtual file. The initial value is set to the one provided when the file was added to the list using AddVirtualFile. An application may update the values using the UpdateVirtualFile.

Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

ChangeTime
int64 (read-only)

Default Value: 0

This field contains the time of the latest update of the metadata of a virtual file.

This field contains the time of the latest update of the metadata of the virtual file, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. The initial value is set to the one provided when the file was added to the list using AddVirtualFile. An application may update the values using the UpdateVirtualFile.

CreationTime
int64 (read-only)

Default Value: 0

This field contains the time of creation of a virtual file.

This field contains the time of creation of the virtual file, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. The initial value is set to the one provided when the file was added to the list using AddVirtualFile. An application may update the values using the UpdateVirtualFile.

LastAccessTime
int64 (read-only)

Default Value: 0

This field contains the time of the latest access to a virtual file.

This field contains the time of the latest access to the virtual file, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. The initial value is set to the one provided when the file was added to the list using AddVirtualFile. An application may update the values using the UpdateVirtualFile.

LastWriteTime
int64 (read-only)

Default Value: 0

This field contains the time of the latest modification of the data of a virtual file.

This field contains the time of the latest modification of the data of the virtual file, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME. The initial value is set to the one provided when the file was added to the list using AddVirtualFile. An application may update the values using the UpdateVirtualFile.

Name
char* (read-only)

Default Value: ""

This field contains the name name of a virtual file.

This field contains the path and the name of the added file as they were specified in a call to AddVirtualFile. The name is converted to the NT native format internally when the file or directory is added to the list.

NTNativeName
char* (read-only)

Default Value: ""

This field contains the name name of a virtual file in NT native format.

This field contains the path and the name of the added file; the contained path is in the NT native format.

Size
int64 (read-only)

Default Value: 0

This field specifies the size of a virtual file.

This field specifies the size of the virtual file. The initial value is set to the one provided when the file was added to the list using AddVirtualFile. An application may update the values using the UpdateVirtualFile.

Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

CBFSFilterList Type

Syntax

CBFSFilterList<T> (declared in cbfsfilter.h)

Remarks

CBFSFilterList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the CBFilter class.

Methods

GetCount This method returns the current size of the collection.

int GetCount() {}

SetCount This method sets the size of the collection. This method returns 0 if setting the size was successful; or -1 if the collection is ReadOnly. When adding additional objects to a collection call this method to specify the new size. Increasing the size of the collection preserves existing objects in the collection.

int SetCount(int count) {}

Get This method gets the item at the specified position. The index parameter specifies the index of the item in the collection. This method returns NULL if an invalid index is specified.

T* Get(int index) {}

Set This method sets the item at the specified position. The index parameter specifies the index of the item in the collection that is being set. This method returns -1 if an invalid index is specified. Note: Objects created using the new operator must be freed using the delete operator; they will not be automatically freed by the class.

T* Set(int index, T* value) {}

CBFSFilterStream Type

Syntax

CBFSFilterStream (declared in cbfsfilter.h)

Remarks

The CBFSFilterStream type is returned by some of the CBFilter class's methods. All stream types in CBFS Filter share a common API, documented below.

Properties

Length Gets or sets the length of the stream, in bytes.

int64 GetLength();
void SetLength(int64 length);
Position Gets or sets the current position within the stream.

int64 GetPosition();
void SetPosition(int64 position);

Methods

Close Closes the stream, releasing all resources currently allocated for it.

void Close();

This method is called automatically when a CBFSFilterStream object is deleted.

Flush Forces all data held by the stream's buffers to be written out to storage.

void Flush();
GetLastError If the previous operation failed, returns the associated error message, if any.

char* GetLastError();
GetLastErrorCode If the previous operation failed, returns a non-zero error code; otherwise returns zero.

int GetLastErrorCode();

This method will always return -1 after Close has been called.

Read Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read.

int Read(void* buffer, int count);

Buffer specifies the buffer to populate with data from the stream. Count specifies the number of bytes that should be read from the stream.

Returns the total number of bytes read into Buffer. This may be less than Count if that many bytes are not currently available, or may be 0 if the end of the stream has been reached.

Seek Sets the current position within the stream based on a particular point of origin.

int64 Seek(int64 offset, SeekOrigin origin);

enum SeekOrigin { soFromBeginning = 0, soFromCurrent = 1, soFromEnd = 2 };

Offset specifies the offset in the stream to seek to, relative to Origin. SeekOrigin is an enum declared alongside the CBFSFilterStream class as shown above.

Returns the new position within the stream.

Write Writes a sequence of bytes to the stream and advances the current position within the stream by the number of bytes written.

int Write(void* buffer, int count);

Buffer specifies the buffer with data to write to the stream. Count specifies the number of bytes that should be written to the stream.

Returns the total number of bytes written to the stream.

Config Settings (CBFilter Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

CBFilter Config Settings

AllowFileAccessInBeforeOpen:   Whether file access, via the CreateFileDirect method, is allowed in during the BeforeCreateFile and BeforeOpenFile events.

This configuration setting specifies whether the class should allow the CreateFileDirect method to be used to access a file during the BeforeCreateFile and/or BeforeOpenFile event fired for it. When this configuration setting is enabled, the CreateFileDirect method may be called in synchronized mode during the aforementioned methods; please refer to its documentation for more information.

By default, this configuration setting is disabled, because it requires the class's system driver to perform extra system calls when a file is being created or opened (which may negatively affect performance in some cases).

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.

This setting corresponds to the INSTALL_ALWAYS_PREPARE_FILES flag, which is used with the Install method. Please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

AlwaysRequestAttributesOnOpen:   Whether the driver should keep request existing attributes before file create/open operation.

Normally, the driver requests existing attributes of the file or directory that is created or opened only when extended rules are set. This setting is disabled by default.

Enable this setting to tell the driver to always request the existing attributes and pass them to the ExistingAttributes parameter of the events, as related to file creation and opening.

CacheRemoteFilesLocally:   Whether remote files involved in filtered operations should be cached locally rather than remotely.

Applications that need to perform on-the-fly data modifications (e.g., encryption) on remote files should enable this configuration setting; it is disabled by default.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

FilterOwnRequests:   Whether the class's system driver should filter requests made by the application itself.

This configuration setting specifies whether requests made by the application should be filtered through the class's system driver (assuming that they match one of the rules present at the time). When this setting is disabled (default), and the application performs some operation that would match an existing rule, the driver will explicitly ignore it.

Normally, this setting should remain disabled (especially in production) to reduce the possibility of system deadlocks occurring. Certain situations, however, do require it to be enabled, such as for testing purposes (so that event handlers can be tested with single-process tests).

ForceAdminRightsForDefaultRules:   Specifies whether default rules can be added or deleted only by administrators.

This configuration setting specifies whether the access check must be performed when an attempt is made to add or delete a default rule.

By default, the setting is enabled and rules may be added and deleted only by administrators. If, however, an application uses default rules not for security-related purposes, and the risk of a limited user trying to add or remove the rules is low, such application may disable the setting.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

ForceAppPermissionCheck:   Whether the driver should require the controller process to have elevated or system privileges.

This configuration setting corresponds to the INSTALL_FORCE_APP_PERMISSION_CHECK flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

ForceSecurityChecks:   Whether the driver should prevent the controller process from filtering files that it would not normally have access to.

This configuration setting corresponds to the INSTALL_FORCE_SECURITY_CHECKS flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

LoggingEnabled:   Whether extended logging is enabled.

This setting specifies whether extended logging is enabled for this class; it is disabled by default. Please refer to the Error Handling topic for more information.

This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.

MaxWorkerThreadCount:   The maximum number of worker threads to use to fire events.

This setting specifies the maximum number of worker threads the class may create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (If other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: 4 * number_of_processors.

MinWorkerThreadCount:   The minimum number of worker threads to use to fire events.

This setting specifies the minimum number of worker threads the class should create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (In other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: max(number_of_processors, 4). If this setting's value exceeds the MaxWorkerThreadCount value, the latter is used instead.

ModifiableReadWriteBuffers:   Whether the driver should duplicate read/write buffers sent to the user.

This configuration setting specifies whether the driver should duplicate the buffers exposed via the AfterReadFile, BeforeReadFile, and BeforeWriteFile events, allowing them to be modified by the application.

Applications that intend to modify these buffers' contents (e.g., for encryption, compression, or similar purposes) should enable this configuration setting. All other applications should leave this configuration setting disabled (the default) for better performance.

NormalizeShortFileNames:   Whether the driver should attempt to resolve short file names and convert them to regular ones.

This configuration setting specifies how the driver should handle short file names in paths that it deals with. The possible values are

  • 0 - Never: Do nothing in regard to the short file names.
  • 1 - on local file systems: Causes the driver to attempt to resolve short file names, but only for local filesystems.
  • 2 - always: Causes the driver to attempt to resolve short file names for files on all filesystems.
OmitEventFileNames:   Whether the filename parameter should be empty in events.

In some editions of the product, passing an extra string parameter to events involves extra allocation of memory and is an unnecessary expenditure of CPU cycles. Enabling this setting makes the component skip passing the file name to event handlers. Event handlers can obtain the file or directory name by calling the GetEventFileName method.

By default this setting is disabled.

Note: This setting cannot be changed when Active is true, and it cannot be changed within events.

PassAllFileNames:   Whether the driver should pass all known names of a file, including hardlinks and previous names, to event handlers.

While the filter is active, it keeps track of file operations that change the set of names of a file or directory. This includes renaming, deletion, and hardlink creation operations.

When this configuration setting is enabled, all known names (both current and old) are passed to event handlers as described in the Filenames In Events topic. By default, this setting is disabled.

PassSecurityInFileOpenEvents:   Whether security information, associated with the file create/open request, is passed to file creation and opening events.

This setting specifies whether the security descriptor, passed by the originator of file creation or opening request to the CreateFile() or similar Windows API function, should be passed to various *FileCreate/*FileOpen events. This setting is disabled by default for performance reasons.

Note: This setting cannot be changed within events.

PreprocessedRulesCacheSize:   Maximum number of preprocessed rules to keep cached.

This configuration setting specifies the maximum number of preprocessed rules that the class's system driver should keep cached; it is set to 1024 by default.

When a file or directory is first opened, the class's system driver determines which of the currently active rules it matches, if any. The results of this process are collected into a single preprocessed rule internally, which is then cached. These preprocessed rules can provide significant performance improvements, especially if many rules have been added, because they prevent the driver from having to recheck each rule every time an operation occurs.

RecordOperationTime:   Enables collection of operation time.

By default, this configuration setting is disabled and the driver does not record the time of each operation. If the application needs to use the GetOperationTime method, it must enable this setting.

ResolveNtDeviceToDriveLetter:   Whether native device names are translated to drive letters.

This configuration setting specifies whether NT native device names, like \Device\HarddiskVolume1\..., should be translated to DOS-style drive letters, like C:\... when possible. However, please note the following:

  • Such translation will be performed only if a device actually has a corresponding DOS-style drive letter; not all devices do.
  • The BeforeFilterAttachToVolume event always uses NT native device names, because DOS-style drive letters are not assigned until after it fires.

This setting is enabled by default; it can be disabled to improve performance, or if the application needs the native device name.

Note: This setting cannot be changed when Active is true, and it cannot be changed within events.

RetriveLinkNamesOnOpen:   Specifies that the driver should collect all hard links when a file is opened.

If an application performs some protection functions on a per-directory basis and hard links may help a user circumvent such a protection, this setting may be used to collect all names of a file or directory (hard links to it) so that all of the names are matched against the rules.

If an application performs path analysis in event handlers, it needs to enable the PassAllFileNames setting as well in order to receive all collected names.

The setting is disabled by default for performance reasons.

Note: hard links are supported only on some filesystems, but are enabled by default in regular NTFS.

SendRequestsViaDriverStack:   Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers.

This configuration setting corresponds to the INSTALL_REQUESTS_VIA_DRIVER_STACK flag, which is used with the Install method; please refer to the documentation for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

SerializeAccess:   Whether nonintersecting operations against the same file should execute serially or in parallel.

This configuration setting specifies whether the driver should serialize operations related to the same file, i.e. wait for completion of an operation before sending another one to the user mode.

This setting is enabled by default, which means that most operations (with the exception of GetFileInformaiton, SetFileInformation, and, in some cases, ReadFile and WriteFile which are safe for parallel processing.) are marked as exclusive. All exclusive operations are sent to the user mode for handling by an application sequentially, one by one. Other operations have to wait until the first operation completes, until they are marked as safe for parallel processing.

When this setting is disabled, operations are not marked as exclusive. This way, the driver sends an operation to the user mode as soon as the corresponding request is received (assuming that enough worker threads are available to service this operation at the time). Please refer to the Threading and Concurrency topic for more information.

TranslateDOSCharsInEnumMasks:   Whether the DOS wildcard characters should be translated during search.

In addition to * and ?, Windows uses special wildcard characters for compatibility with DOS applications and short (8.3) names. These characters are <, >, and " . Their meanings are described in MSDN and .NET reference source code as follows:

  • DOS_STAR (<) - Matches zero or more characters until encountering and matching the final dot (.) in the name. (Source code comment: "DOS_STAR matches any character except . zero or more times.")
  • DOS_QM (>) - Matches any single character or, upon encountering a period or end of name string, advances the expression to the end of the set of contiguous DOS_QMs. (Source code comment: "A DOS_DOT can match either a period, or zero characters beyond the end of name.")
  • DOS_DOT (") - Matches either a period or zero characters beyond the name string. (Source code comment: "DOS_QM is the most complicated. If the name is finished, we can match zero characters. If this name is a '.', we don't match, but look at the next expression. Otherwise, we match a single character.")

When this setting is enabled (default), the class translates them to * and ?, but such a translation is not able to fully represent all the logic behind DOS_* wildcard characters; however, this translation is usually sufficient for end-user needs.

If your application needs to perform exact matching, disable this setting and implement handling of DOS_* wildcard characters in your application. Further explanation about the characters can be found in the MSDN article. The RtlIsNameInExpression function of Windows API may be used to perform such a matching. Note: as the explanation states, "When you do a case-insensitive search and don't provide a translation table, the name is converted to uppercase."

WorkerInitialStackSize:   The initial stack size to create worker threads with.

This setting specifies the initial size of the stack each worker thread is created with. The system rounds this value to the nearest page.

By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).

Note: This setting cannot be changed when Active is true, and it cannot be changed within events.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).

Trappable Errors (CBFilter Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

The class uses Windows error codes during operations as necessary. Please refer to the Error Handling topic for more information.

Special Use Errors

21   ERROR_NOT_READY: Reported by the methods of the class if Initialize has not been called or did not succeed.
191   ERROR_INVALID_EXE_SIGNATURE: Reported by the Install method when the CAB file signature cannot be validated.
575   ERROR_APP_INIT_FAILURE: Reported by the methods of the class if Initialize has not been called or did not succeed. Differs from ERROR_NOT_READY (21) in that it indicates a specific situation in the internal code.
588   ERROR_FS_DRIVER_REQUIRED: Reported if the required system module was not correctly installed for the given ProductGUID.
614   ERROR_NO_CALLBACK_ACTIVE: Reported by any method that can only be called within event handlers if it is called outside an event handler.
1292   ERROR_IMPLEMENTATION_LIMIT: Reported when the timeout value provided is less than 3 seconds.
1314   ERROR_PRIVILEGE_NOT_HELD: Reported by any method that requires elevated permissions if it is called without such permissions.