CBFilter Component
Properties Methods Events Config Settings Errors
The CBFilter component allows applications to intercept and control filesystem requests.
Syntax
cbfsfilter.CBFilter
Remarks
The CBFilter component 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 component's capabilities, please refer to the product's General Information topics.
Getting Started
- If the component'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.
- Call the Initialize method to initialize the CBFilter component. This must be done each time the application starts.
- Add one or more filter rules using methods like AddFilterRule. (Rules can also be added or removed after the filter is started.)
- Call the StartFilter method to start filtering filesystem requests.
- When finished, call the StopFilter method to stop filtering filesystem requests.
- To uninstall the component's system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
- In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
| Active | This property notes whether the component is active and processing requests. |
| Altitude | This property specifies the altitude the component's system driver should use . |
| DefaultRuleCount | The number of records in the DefaultRule arrays. |
| DefaultRuleAccessFlags | This property indicates the access restrictions enforced by the rule. |
| DefaultRuleMask | This property indicates a file mask that determines which files and directories match the rule. |
| FileFlushingBehavior | This property specifies the file flushing and closing behavior that the component's system driver should enforce. |
| FilterRuleCount | The number of records in the FilterRule arrays. |
| FilterRuleAccessFlags | This property indicates the access restrictions enforced by the rule (CBFilter only). |
| FilterRuleControlFlags | This property indicates which control events the rule causes the component to fire (CBFilter only). |
| FilterRuleEaName | This property indicates the name of an extended attribute that a file or directory must have to match the rule. |
| FilterRuleExcludedAttributes | This property indicates the file attributes that a file or directory must not have to match the rule. |
| FilterRuleIncludedAttributes | This property indicates the file attributes that a file or directory must have to match the rule. |
| FilterRuleMask | This property indicates a file mask that determines which files and directories match the rule. |
| FilterRuleMaxSize | This property indicates the maximum size a file can be to match the rule. |
| FilterRuleMinSize | This property indicates the minimum size a file can be to match the rule. |
| FilterRuleNotifyFlags | This property indicates which notification events the rule causes the component to fire. |
| FireVolumeEvents | This property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system. |
| PassthroughRuleCount | The number of records in the PassthroughRule arrays. |
| PassthroughRuleAccessFlags | This property specifies the access restrictions lifted by the rule (CBFilter only). |
| PassthroughRuleControlFlags | This property indicates which control events the rule prevents the component from firing (CBFilter only). |
| PassthroughRuleEaName | This property indicates the name of an extended attribute that a file or directory must have to match the rule. |
| PassthroughRuleExcludedAttributes | This property indicates the file attributes that a file or directory must not have to match the rule. |
| PassthroughRuleIncludedAttributes | This property indicates the file attributes that a file or directory must have to match the rule. |
| PassthroughRuleMask | This property indicates a file mask that determines which files and directories match the rule. |
| PassthroughRuleMaxSize | This property indicates the maximum size a file can be to match the rule. |
| PassthroughRuleMinSize | This property indicates the minimum size a file can be to match the rule. |
| PassthroughRuleNotifyFlags | This property indicates which notification events the rule prevents the component from firing. |
| ProcessCachedIORequests | This property specifies whether cached file read/write requests should be processed. |
| ProcessFailedRequests | This property specifies whether failed requests should be processed. |
| ReparseRuleCount | The number of records in the ReparseRule arrays. |
| ReparseRuleMask | This property indicates a file mask that determines which files and directories match the rule. |
| ReparseRuleReparseMask | This property contains a file mask that specifies where matching files and directories are redirected to. |
| SerializeEvents | Whether events should be fired on a single worker thread, or many. |
| Tag | This property stores application-defined data specific to a particular instance of the component. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
| AddBytesToWriteBuffer | This method reserves extra space in the file data buffers used in file read/write events. |
| AddDefaultRule | This method adds a default rule. |
| AddFilterRule | This method adds a standard filter rule or access rule. |
| AddFilterRuleEx | This method adds a standard filter rule or access rule with additional match qualifiers. |
| AddPassthroughRule | This method adds a passthrough rule. |
| AddPassthroughRuleEx | This method adds a passthrough rule with additional match qualifiers. |
| AddReparseRule | This method adds a reparse rule. |
| CloseDefaultRulesSnapshot | This method closes the previously created default rules snapshot. |
| CloseReparseRulesSnapshot | This method closes the previously created reparse rules snapshot. |
| Config | Sets or retrieves a configuration setting. |
| CreateDefaultRulesSnapshot | This method creates a snapshot of information about the default rules that have been added. |
| CreateFileDirect | This method creates or opens a file or directory by passing the request directly to the filesystem. |
| CreateFileDirectAsStream | This method creates or opens a file by passing the request directly to the filesystem. |
| CreateReparseRulesSnapshot | This method creates a snapshot of information about the reparse rules that have been added. |
| CreateVirtualFile | This method is under construction. |
| DeleteAllFilterRules | This method deletes all standard filter rules and access rules. |
| DeleteAllPassthroughRules | This method deletes all passthrough rules. |
| DeleteAllReparseRules | This method deletes all reparse rules. |
| DeleteDefaultRule | This method deletes a particular default rule. |
| DeleteFilterRule | This method deletes a particular standard filter rule or access rule. |
| DeletePassthroughRule | This method deletes a particular passthrough rule. |
| DeleteReparseRule | This method deletes a particular reparse rule. |
| FileMatchesMask | This method checks whether a particular file or directory name matches the specified mask. |
| GetDriverStatus | This method retrieves the status of the component's system driver. |
| GetDriverVersion | This method retrieves the version of the component's system driver. |
| GetEventFilename | This method retrieves the name of the file or directory, to which the event applies. |
| GetHandleCreatorProcessId | This method retrieves the Id of the process (PID) that opened the file handle. |
| GetHandleCreatorProcessName | This method retrieves the name of the process that opened the file handle. |
| GetHandleCreatorThreadId | This method retrieves the Id of the thread that opened the file handle. |
| GetHandleCreatorToken | This method retrieves the security token associated with the process that opened the file handle. |
| GetOperationTime | This method returns the time at which the request was received by the filter driver. |
| GetOriginatorProcessId | Retrieves the Id of the process (PID) that initiated the operation. |
| GetOriginatorProcessName | Retrieves the name of the process that initiated the operation. |
| GetOriginatorThreadId | Retrieves the Id of the thread that initiated the operation. |
| GetOriginatorToken | Retrieves the security token associated with the process that initiated the operation. |
| GetRemoteAccessInformation | This method returns networking-related information about the operation. |
| GetReparseRuleByMask | This method retrieves the reparse rule associated with the specified file mask. |
| GetVolumeGUID | This method retrieves the volume GUID of the device targeted by a filesystem operation. |
| Initialize | This method initializes the component. |
| Install | This method installs (or upgrades) the component's system driver. |
| IsFileFiltered | This method checks whether a particular file or directory is covered by any filter rules. |
| NtStatusToWin32Error | This method converts a native status code to a Win32 error code. |
| ResetTimeout | This method resets the timeout duration for the current event handler. |
| SetFileInformationDirect | This method sets the file information of a file opened using CreateFileDirect. |
| SetFileSizeDirect | This method resizes a file by passing the request directly to the filesystem. |
| ShutdownSystem | Shuts down or reboots the operating system. |
| StartFilter | This method starts filtering filesystem operations. |
| StopFilter | This method stops filtering filesystem operations. |
| SuspendDefaultRules | This method suspends all default rules until the application exits. |
| SuspendFileEvents | This method suspends all events for a particular file or directory until all of its handles have been closed. |
| ToggleProcessProtection | This method enables or disables termination protection for the application. |
| Uninstall | This method uninstalls the component's system driver. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
| AfterCanFileBeDeleted | This event fires after the OS marks a file or directory for deletion or removes such a mark. |
| AfterCleanupFile | This event fires after a file or directory handle is closed. |
| AfterCloseEnumeration | This event fires after a directory enumeration operation finishes. |
| AfterCloseFile | This event fires after a file or directory is closed. |
| AfterCreateFile | This event fires after a file or directory is created. |
| AfterCreateHardLink | This event fires after a hard link is created. |
| AfterDeleteFile | This event fires after a file or directory is deleted. |
| AfterDeleteReparsePoint | This event fires after the OS deletes a reparse point from a file or directory. |
| AfterEnumerateDirectory | This event fires after a directory entry is returned during directory enumeration. |
| AfterFilterAttachToVolume | This event fires after the filter attaches to a newly mounted filesystem volume. |
| AfterFilterDetachFromVolume | This event fires after the filter detaches from a filesystem volume. |
| AfterFsctl | This event fires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed. |
| AfterGetFileSecurity | This event fires after a file or directory's security attributes are retrieved. |
| AfterGetFileSizes | This event fires after a file's size information is retrieved. |
| AfterGetReparsePoint | This event fires after a file or directory's reparse point information is retrieved. |
| AfterIoctl | This event fires after an IRP_MJ_DEVICE_CONTROL request is processed. |
| AfterLock | This event fires after a range of bytes in a file is locked. |
| AfterOpenFile | This event fires after a file or directory is opened. |
| AfterQueryEa | This event fires after information about extended attributes of a file is retrieved. |
| AfterQueryFileInfo | This event fires after information about a file or directory is retrieved. |
| AfterReadFile | This event fires after data are read from a file. |
| AfterRenameOrMoveFile | This event fires after a file or directory is renamed or moved. |
| AfterSetAllocationSize | This event fires after a file's allocation size is changed. |
| AfterSetEa | This event fires after extended attributes of a file are changed. |
| AfterSetFileAttributes | This event fires after a file or directory's attributes or times are changed. |
| AfterSetFileInfo | This event fires after information about a file or directory is changed. |
| AfterSetFileSecurity | This event fires after a file or directory's security attributes are changed. |
| AfterSetFileSize | This event fires after a file is resized. |
| AfterSetReparsePoint | This event fires after the OS creates or updates a reparse point on a file or directory. |
| AfterUnlockAll | This event fires after all locked byte ranges in a file are unlocked. |
| AfterUnlockAllByKey | This event fires after all locked byte ranges in a file, associated with a particular key, are unlocked. |
| AfterUnlockSingle | This event fires after a particular locked byte range in a file is unlocked. |
| AfterWriteFile | This event fires after data are written to a file. |
| BeforeCanFileBeDeleted | This event fires before the OS attempts to mark a file or directory for deletion or remove such a mark. |
| BeforeCleanupFile | This event fires before a file or directory handle is closed. |
| BeforeCloseFile | This event fires before a file or directory is closed. |
| BeforeCreateFile | This event fires before a file or directory is created. |
| BeforeCreateHardLink | This event fires before a hard link is created. |
| BeforeDeleteFile | This event fires before a file or directory is deleted. |
| BeforeDeleteReparsePoint | This event fires when the OS wants to delete a reparse point from a file or directory. |
| BeforeEnumerateDirectory | This event fires when an enumeration request is sent by the OS. |
| BeforeFilterAttachToVolume | This event fires before the filter attaches to a newly mounted filesystem volume. |
| BeforeFsctl | This event fires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed. |
| BeforeGetFileSecurity | This event fires before a file or directory's security attributes are retrieved. |
| BeforeGetReparsePoint | This event fires when the OS wants to read a reparse point for a file or directory. |
| BeforeIoctl | This event fires before an IRP_MJ_DEVICE_CONTROL request is processed. |
| BeforeLock | This event fires before a range of bytes in a file is locked. |
| BeforeOpenFile | This event fires before a file or directory is opened. |
| BeforeQueryEa | This event fires before information about extended attributes of a file is retrieved. |
| BeforeQueryFileInfo | This event fires before information about a file or directory is retrieved. |
| BeforeReadFile | This event fires before data are read from a file. |
| BeforeRenameOrMoveFile | This event fires before a file or directory is renamed or moved. |
| BeforeSetAllocationSize | This event fires before a file's allocation size is changed. |
| BeforeSetEa | This event fires before extended attributes of a file are changed. |
| BeforeSetFileAttributes | This event fires before a file or directory's attributes or times are changed. |
| BeforeSetFileInfo | This event fires before information about a file or directory is changed. |
| BeforeSetFileSecurity | This event fires before a file or directory's security attributes are changed. |
| BeforeSetFileSize | This event fires before a file is resized. |
| BeforeSetReparsePoint | This event fires when the OS wants to create or update a reparse point on a file or directory. |
| BeforeUnlockAll | This event fires before all locked byte ranges in a file are unlocked. |
| BeforeUnlockAllByKey | This event fires before all locked byte ranges in a file, associated with a particular key, are unlocked. |
| BeforeUnlockSingle | This event fires before a particular locked byte range in a file is unlocked. |
| BeforeWriteFile | This event fires before data are written to a file. |
| CleanupContext | This event fires when the application-defined data stored in one or more contexts need to be cleaned up. |
| Error | This event fires if an unhandled error occurs during an event. |
| FilterStart | This event fires once the filter has attached and filtering has started. |
| FilterStop | This event fires once filtering has stopped and the filter has detached. |
| NotifyCanFileBeDeleted | This event fires when the OS marks a file or directory for deletion or removes such a mark. |
| NotifyCleanupFile | This event fires when a file or directory handle has been closed. |
| NotifyCloseFile | This event fires when a file or directory has been closed. |
| NotifyCreateFile | This event fires when a file or directory has been created. |
| NotifyCreateHardLink | This event fires when a hard link has been created. |
| NotifyDeleteFile | This event fires when a file or directory has been deleted. |
| NotifyDeleteReparsePoint | This event fires when a file or directory's reparse point has been deleted. |
| NotifyEnumerateDirectory | This event fires when a directory entry has been returned during directory enumeration. |
| NotifyFilterAttachToVolume | This event fires when the filter has been attached to a newly mounted filesystem volume. |
| NotifyFilterDetachFromVolume | This event fires when the filter has been detached from a filesystem volume. |
| NotifyFsctl | This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred. |
| NotifyGetFileSecurity | This event fires when a file or directory's security attributes have been retrieved. |
| NotifyGetFileSizes | This event fires when a file's size information has been retrieved. |
| NotifyGetReparsePoint | This event fires when a file or directory's reparse point information has been retrieved. |
| NotifyIoctl | This event fires when an IRP_MJ_DEVICE_CONTROL operation has occurred. |
| NotifyLock | This event fires when a range of bytes in a file has been locked. |
| NotifyOpenFile | This event fires when a file or directory has been opened. |
| NotifyQueryEa | This event fires when information about the extended attributes of a file has been retrieved. |
| NotifyQueryFileInfo | This event fires when information about a file or directory has been retrieved. |
| NotifyReadFile | This event fires when data have been read from a file. |
| NotifyRenameOrMoveFile | This event fires when a file or directory has been renamed or moved. |
| NotifySetAllocationSize | This event fires when a file's allocation size has been changed. |
| NotifySetEa | This event fires when information about the extended attributes of a file has been changed. |
| NotifySetFileAttributes | This event fires when a file or directory's attributes or times have been changed. |
| NotifySetFileInfo | This event fires when information about a file or directory has been changed. |
| NotifySetFileSecurity | This event fires when a file or directory's security attributes have been changed. |
| NotifySetFileSize | This event fires when a file has been resized. |
| NotifySetReparsePoint | This event fires when a file or directory's reparse point has been created or updated. |
| NotifyUnlockAll | This event fires when all locked byte ranges in a file have been unlocked. |
| NotifyUnlockAllByKey | This event fires when all locked byte ranges in a file, associated with a particular key, have been unlocked. |
| NotifyUnlockSingle | This event fires when a particular locked byte range in a file has been unlocked. |
| NotifyWriteFile | This event fires when data have been written to a file. |
| ReparseFileName | This event fires to allow file access to be dynamically redirected to another location. |
| ReparseWithTag | This event fires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point. |
| WorkerThreadCreation | Fires just after a new worker thread is created. |
| WorkerThreadTermination | Fires just before a worker thread is terminated. |
Config Settings
The following is a list of config settings for the component with short descriptions. Click on the links for further details.
| AllowFileAccessInBeforeOpen | Whether file access, via the CreateFileDirect method, is allowed in during the BeforeCreateFile and BeforeOpenFile events. |
| AlwaysPrepareFiles | Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the component is initialized. |
| AlwaysRequestAttributesOnOpen | Whether the driver should keep request existing attributes before file create/open operation. |
| CacheRemoteFilesLocally | Whether remote files involved in filtered operations should be cached locally rather than remotely. |
| DirectRequestsDownTheStack | Whether requests for handles created with the CreateFileDirect method go down the filter stack and not direct to the filesystem. |
| FilterOwnRequests | Whether the component's system driver should filter requests made by the application itself. |
| ForceAdminRightsForDefaultRules | Specifies whether default rules can be added or deleted only by administrators. |
| ForceAppPermissionCheck | Whether the driver should require the controller process to have elevated or system privileges. |
| ForceSecurityChecks | Whether the driver should prevent the controller process from filtering files that it would not normally have access to. |
| LoggingEnabled | Whether extended logging is enabled. |
| MaxWorkerThreadCount | The maximum number of worker threads to use to fire events. |
| MinWorkerThreadCount | The minimum number of worker threads to use to fire events. |
| ModifiableReadWriteBuffers | Whether the driver should duplicate read/write buffers sent to the user. |
| OmitEventFilenames | Whether the filename parameter should be empty in events. |
| PassSecurityInFileOpenEvents | Whether security information, associated with the file create/open request, is passed to file creation and opening events. |
| PreprocessedRulesCacheSize | Maximum number of preprocessed rules to keep cached. |
| RecordOperationTime | Enables collection of operation time. |
| ResolveNtDeviceToDriveLetter | Whether native device names are translated to drive letters. |
| SendRequestsViaDriverStack | Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers. |
| SerializeAccess | Whether nonintersecting operations against the same file should execute serially or in parallel. |
| TranslateDOSCharsInEnumMasks | Whether the DOS wildcard characters should be translated during search. |
| WorkerInitialStackSize | The initial stack size to create worker threads with. |
| BuildInfo | Information about the product's build. |
| LicenseInfo | Information about the current license. |
Active Property (CBFilter Component)
This property notes whether the component is active and processing requests.
Syntax
func (obj *CBFilter) Active() (bool, error)
Default Value
false
Remarks
This property reflects whether the component 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.
Data Type
bool
Altitude Property (CBFilter Component)
This property specifies the altitude the component's system driver should use .
Syntax
func (obj *CBFilter) Altitude() (string, error)
func (obj *CBFilter) SetAltitude(value string) error
Default Value
""
Remarks
This property specifies the altitude that the component'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
DefaultRuleCount Property (CBFilter Component)
The number of records in the DefaultRule arrays.
Syntax
func (obj *CBFilter) DefaultRuleCount() (int32, error)
Default Value
0
Remarks
This property controls the size of the following arrays:
The array indices start at 0 and end at DefaultRuleCount - 1.This property is read-only.
Data Type
int32
DefaultRuleAccessFlags Property (CBFilter Component)
This property indicates the access restrictions enforced by the rule.
Syntax
func (obj *CBFilter) DefaultRuleAccessFlags(DefaultRuleIndex int32) (int32, error)
Default Value
0
Remarks
This property indicates the access restrictions enforced by the rule.
This property indicates which access restrictions are enforced by the rule. Please refer to the Default Rules topic for more information. The value of this property is a combination of zero or more of the following:
| ACCESS_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
The DefaultRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DefaultRuleCount property.
This property is read-only.
Data Type
int32
DefaultRuleMask Property (CBFilter Component)
This property indicates a file mask that determines which files and directories match the rule.
Syntax
func (obj *CBFilter) DefaultRuleMask(DefaultRuleIndex int32) (string, error)
Default Value
""
Remarks
This property indicates a file mask that determines which files and directories match the rule.
This property 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 property's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the component 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.
The DefaultRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DefaultRuleCount property.
This property is read-only.
Data Type
string
FileFlushingBehavior Property (CBFilter Component)
This property specifies the file flushing and closing behavior that the component's system driver should enforce.
Syntax
func (obj *CBFilter) FileFlushingBehavior() (int32, error)
func (obj *CBFilter) SetFileFlushingBehavior(value int32) error
Default Value
0
Remarks
This property specifies what file flushing and closing behaviors the component'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_OPEN | 1 | Whether memory-mapped file data should be flushed to disk before files are opened.
This flag indicates that the component'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_CLOSE | 2 | Whether file buffers must be flushed when files are closed.
This flag indicates that the component'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_STOPFILTER | 4 | Whether files opened for writing must be closed when the application stops filtering.
This flag indicates that the component'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_STOPFILTER | 8 | Whether file buffers must be flushed when the application stops filtering.
This flag indicates that the component'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_CRASH | 16 | Whether files opened for writing must be closed if the application terminates unexpectedly.
This flag indicates that the component'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_CRASH | 32 | Whether file buffers must be flushed if the application terminates unexpectedly.
This flag indicates that the component'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_ENCRYPTION | 31 | Combination 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
int32
FilterRuleCount Property (CBFilter Component)
The number of records in the FilterRule arrays.
Syntax
func (obj *CBFilter) FilterRuleCount() (int32, error)
Default Value
0
Remarks
This property controls the size of the following arrays:
- FilterRuleAccessFlags
- FilterRuleControlFlags
- FilterRuleEaName
- FilterRuleExcludedAttributes
- FilterRuleIncludedAttributes
- FilterRuleMask
- FilterRuleMaxSize
- FilterRuleMinSize
- FilterRuleNotifyFlags
This property is read-only.
Data Type
int32
FilterRuleAccessFlags Property (CBFilter Component)
This property indicates the access restrictions enforced by the rule (CBFilter only).
Syntax
func (obj *CBFilter) FilterRuleAccessFlags(FilterRuleIndex int32) (int32, error)
Default Value
0
Remarks
This property indicates the access restrictions enforced by the rule (CBFilter only).
This property indicates which access restrictions are enforced by the rule. Please refer to the Access Rules topic for more information. The value of this property is a combination of zero or more of the following:
| ACCESS_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
Note: This property is always 0 for the CBMonitor component, which does not support access rules.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int32
FilterRuleControlFlags Property (CBFilter Component)
This property indicates which control events the rule causes the component to fire (CBFilter only).
Syntax
func (obj *CBFilter) FilterRuleControlFlags(FilterRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates which control events the rule causes the component to fire (CBFilter only).
This property indicates which filesystem operations, of those performed on matching files and directories, the component should fire Control Events for. The value of this property is a combination of zero or more of the following:
| FS_CE_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component tracks. |
Note: This property is always 0 for the CBMonitor component, which does not provide any Control Events for filesystem operations.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int64
FilterRuleEaName Property (CBFilter Component)
This property indicates the name of an extended attribute that a file or directory must have to match the rule.
Syntax
func (obj *CBFilter) FilterRuleEaName(FilterRuleIndex int32) (string, error)
Default Value
""
Remarks
This property indicates the name of an extended attribute that a file or directory must have to match the rule.
This property 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 property as a match qualifier.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
string
FilterRuleExcludedAttributes Property (CBFilter Component)
This property indicates the file attributes that a file or directory must not have to match the rule.
Syntax
func (obj *CBFilter) FilterRuleExcludedAttributes(FilterRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the file attributes that a file or directory must not have to match the rule.
This property 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 property as a match qualifier.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int64
FilterRuleIncludedAttributes Property (CBFilter Component)
This property indicates the file attributes that a file or directory must have to match the rule.
Syntax
func (obj *CBFilter) FilterRuleIncludedAttributes(FilterRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the file attributes that a file or directory must have to match the rule.
This property 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 property as a match qualifier.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int64
FilterRuleMask Property (CBFilter Component)
This property indicates a file mask that determines which files and directories match the rule.
Syntax
func (obj *CBFilter) FilterRuleMask(FilterRuleIndex int32) (string, error)
Default Value
""
Remarks
This property indicates a file mask that determines which files and directories match the rule.
This property 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 property's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the component 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.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
string
FilterRuleMaxSize Property (CBFilter Component)
This property indicates the maximum size a file can be to match the rule.
Syntax
func (obj *CBFilter) FilterRuleMaxSize(FilterRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the maximum size a file can be to match the rule.
This property 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 property as a match qualifier.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int64
FilterRuleMinSize Property (CBFilter Component)
This property indicates the minimum size a file can be to match the rule.
Syntax
func (obj *CBFilter) FilterRuleMinSize(FilterRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the minimum size a file can be to match the rule.
This property 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 property as a match qualifier.
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int64
FilterRuleNotifyFlags Property (CBFilter Component)
This property indicates which notification events the rule causes the component to fire.
Syntax
func (obj *CBFilter) FilterRuleNotifyFlags(FilterRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates which notification events the rule causes the component to fire.
This property indicates which filesystem operations, of those performed on matching files and directories, the component should fire Notification Events for. The value of this property is a combination of zero or more of the following:
| FS_NE_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component tracks. |
The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.
This property is read-only.
Data Type
int64
FireVolumeEvents Property (CBFilter Component)
This property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system.
Syntax
func (obj *CBFilter) FireVolumeEvents() (int32, error)
func (obj *CBFilter) SetFireVolumeEvents(value int32) error
Default Value
0
Remarks
This property specifies the events that the component should fire when a filesystem volume is mounted to or unmounted from the system. Possible values are as follows:
| FS_MOUNT_IGNORE | 0 | Don't fire any events when volumes are mounted or unmounted. |
| FS_MOUNT_NOTIFY | 64 | Fire Notification Events when volumes are mounted or unmounted.
The NotifyFilterAttachToVolume and NotifyFilterDetachFromVolume events will fire, asynchronously, as necessary. |
| FS_MOUNT_CONTROL | 128 | Fire Control Events when volumes are mounted or unmounted.
The BeforeFilterAttachToVolume, AfterFilterAttachToVolume, and AfterFilterDetachFromVolume events will fire, synchronously, as necessary. |
| FS_MOUNT_BOTH | 192 | Fire 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
int32
PassthroughRuleCount Property (CBFilter Component)
The number of records in the PassthroughRule arrays.
Syntax
func (obj *CBFilter) PassthroughRuleCount() (int32, error)
Default Value
0
Remarks
This property controls the size of the following arrays:
- PassthroughRuleAccessFlags
- PassthroughRuleControlFlags
- PassthroughRuleEaName
- PassthroughRuleExcludedAttributes
- PassthroughRuleIncludedAttributes
- PassthroughRuleMask
- PassthroughRuleMaxSize
- PassthroughRuleMinSize
- PassthroughRuleNotifyFlags
This property is read-only.
Data Type
int32
PassthroughRuleAccessFlags Property (CBFilter Component)
This property specifies the access restrictions lifted by the rule (CBFilter only).
Syntax
func (obj *CBFilter) PassthroughRuleAccessFlags(PassthroughRuleIndex int32) (int32, error)
Default Value
0
Remarks
This property specifies the access restrictions lifted by the rule (CBFilter only).
This property indicates which access restrictions are lifted by the rule. Please refer to the Passthrough Rules topic for more information. The value of this property is a combination of zero or more of the following:
| ACCESS_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
Note: This property is always 0 for the CBMonitor component, which does not support access rules.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int32
PassthroughRuleControlFlags Property (CBFilter Component)
This property indicates which control events the rule prevents the component from firing (CBFilter only).
Syntax
func (obj *CBFilter) PassthroughRuleControlFlags(PassthroughRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates which control events the rule prevents the component from firing (CBFilter only).
This property indicates which filesystem operations, of those performed on matching files and directories, the component should not fire Control Events for. Please refer to the Passthrough Rules topic for more information. The value of this property is a combination of zero or more of the following:
| FS_CE_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component tracks. |
Note: This property is always 0 for the CBMonitor component, which does not provide any Control Events for filesystem operations.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int64
PassthroughRuleEaName Property (CBFilter Component)
This property indicates the name of an extended attribute that a file or directory must have to match the rule.
Syntax
func (obj *CBFilter) PassthroughRuleEaName(PassthroughRuleIndex int32) (string, error)
Default Value
""
Remarks
This property indicates the name of an extended attribute that a file or directory must have to match the rule.
This property 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 property as a match qualifier.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
string
PassthroughRuleExcludedAttributes Property (CBFilter Component)
This property indicates the file attributes that a file or directory must not have to match the rule.
Syntax
func (obj *CBFilter) PassthroughRuleExcludedAttributes(PassthroughRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the file attributes that a file or directory must not have to match the rule.
This property 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 property as a match qualifier.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int64
PassthroughRuleIncludedAttributes Property (CBFilter Component)
This property indicates the file attributes that a file or directory must have to match the rule.
Syntax
func (obj *CBFilter) PassthroughRuleIncludedAttributes(PassthroughRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the file attributes that a file or directory must have to match the rule.
This property 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 property as a match qualifier.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int64
PassthroughRuleMask Property (CBFilter Component)
This property indicates a file mask that determines which files and directories match the rule.
Syntax
func (obj *CBFilter) PassthroughRuleMask(PassthroughRuleIndex int32) (string, error)
Default Value
""
Remarks
This property indicates a file mask that determines which files and directories match the rule.
This property 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 property's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the component 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.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
string
PassthroughRuleMaxSize Property (CBFilter Component)
This property indicates the maximum size a file can be to match the rule.
Syntax
func (obj *CBFilter) PassthroughRuleMaxSize(PassthroughRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the maximum size a file can be to match the rule.
This property 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 property as a match qualifier.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int64
PassthroughRuleMinSize Property (CBFilter Component)
This property indicates the minimum size a file can be to match the rule.
Syntax
func (obj *CBFilter) PassthroughRuleMinSize(PassthroughRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates the minimum size a file can be to match the rule.
This property 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 property as a match qualifier.
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int64
PassthroughRuleNotifyFlags Property (CBFilter Component)
This property indicates which notification events the rule prevents the component from firing.
Syntax
func (obj *CBFilter) PassthroughRuleNotifyFlags(PassthroughRuleIndex int32) (int64, error)
Default Value
0
Remarks
This property indicates which notification events the rule prevents the component from firing.
This property indicates which filesystem operations, of those performed on matching files and directories, the component should not fire Notification Events for. Please refer to the Passthrough Rules topic for more information. The value of this property is a combination of zero or more of the following:
| FS_NE_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component tracks. |
The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.
This property is read-only.
Data Type
int64
ProcessCachedIORequests Property (CBFilter Component)
This property specifies whether cached file read/write requests should be processed.
Syntax
func (obj *CBFilter) ProcessCachedIORequests() (bool, error)
func (obj *CBFilter) SetProcessCachedIORequests(value bool) error
Default Value
false
Remarks
This property specifies whether the component'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
bool
ProcessFailedRequests Property (CBFilter Component)
This property specifies whether failed requests should be processed.
Syntax
func (obj *CBFilter) ProcessFailedRequests() (bool, error)
func (obj *CBFilter) SetProcessFailedRequests(value bool) error
Default Value
false
Remarks
This property specifies whether the component'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
bool
ReparseRuleCount Property (CBFilter Component)
The number of records in the ReparseRule arrays.
Syntax
func (obj *CBFilter) ReparseRuleCount() (int32, error)
Default Value
0
Remarks
This property controls the size of the following arrays:
The array indices start at 0 and end at ReparseRuleCount - 1.This property is read-only.
Data Type
int32
ReparseRuleMask Property (CBFilter Component)
This property indicates a file mask that determines which files and directories match the rule.
Syntax
func (obj *CBFilter) ReparseRuleMask(ReparseRuleIndex int32) (string, error)
Default Value
""
Remarks
This property indicates a file mask that determines which files and directories match the rule.
This property 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 property's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the component 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.
The ReparseRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ReparseRuleCount property.
This property is read-only.
Data Type
string
ReparseRuleReparseMask Property (CBFilter Component)
This property contains a file mask that specifies where matching files and directories are redirected to.
Syntax
func (obj *CBFilter) ReparseRuleReparseMask(ReparseRuleIndex int32) (string, error)
Default Value
""
Remarks
This property contains a file mask that specifies where matching files and directories are redirected to.
This property contains a file mask that specifies where files and directories that match ReparseRuleMask are redirected to. Please refer to the Reparse Rules topic for more information.
The ReparseRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ReparseRuleCount property.
This property is read-only.
Data Type
string
SerializeEvents Property (CBFilter Component)
Whether events should be fired on a single worker thread, or many.
Syntax
func (obj *CBFilter) SerializeEvents() (int32, error)
func (obj *CBFilter) SetSerializeEvents(value int32) error
Default Value
0
Remarks
This property specifies whether the component should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:
| 0 (seOnMultipleThreads) | The component 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 component 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
int32
Tag Property (CBFilter Component)
This property stores application-defined data specific to a particular instance of the component.
Syntax
func (obj *CBFilter) Tag() (int64, error)
func (obj *CBFilter) SetTag(value int64) error
Default Value
0
Remarks
This property can be used to store data specific to a particular instance of the component.
Data Type
int64
AddBytesToWriteBuffer Method (CBFilter Component)
This method reserves extra space in the file data buffers used in file read/write events.
Syntax
func (obj *CBFilter) AddBytesToWriteBuffer(ExtraBytes int32) (bool, error)
Remarks
Applications that plan to add additional data when files are being read or written should call this method to specify how much extra space to reserve in the file data buffers used in the BeforeReadFile, AfterReadFile, BeforeWriteFile, and AfterWriteFile events. If successful, this method returns true; otherwise, it returns false.
The ExtraBytes parameter specifies how many bytes to reserve.
Note: The value passed for this parameter must be a multiple of 512.
Note: This method cannot be called when Active is true.
AddDefaultRule Method (CBFilter Component)
This method adds a default rule.
Syntax
func (obj *CBFilter) AddDefaultRule(Mask string, AccessFlags int32, ProductGUID string) (bool, error)
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 component'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 component'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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used 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.
AddFilterRule Method (CBFilter Component)
This method adds a standard filter rule or access rule.
Syntax
func (obj *CBFilter) AddFilterRule(Mask string, AccessFlags int32, ControlFlags int64, NotifyFlags int64) (bool, error)
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 component should fire its events for. Access rules instruct the component'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 component'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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
The ControlFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component tracks. |
The NotifyFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component 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.
AddFilterRuleEx Method (CBFilter Component)
This method adds a standard filter rule or access rule with additional match qualifiers.
Syntax
func (obj *CBFilter) AddFilterRuleEx(Mask string, EaName string, AccessFlags int32, ControlFlags int64, NotifyFlags int64, MinSize int64, MaxSize int64, IncludedAttributes int64, ExcludedAttributes int64) (bool, error)
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 component should fire its events for. Access rules instruct the component'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 component'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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
The ControlFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component tracks. |
The NotifyFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component 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.
AddPassthroughRule Method (CBFilter Component)
This method adds a passthrough rule.
Syntax
func (obj *CBFilter) AddPassthroughRule(Mask string, AccessFlags int32, ControlFlags int64, NotifyFlags int64) (bool, error)
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 component'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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
The ControlFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component tracks. |
The NotifyFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component 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.
AddPassthroughRuleEx Method (CBFilter Component)
This method adds a passthrough rule with additional match qualifiers.
Syntax
func (obj *CBFilter) AddPassthroughRuleEx(Mask string, EaName string, AccessFlags int32, ControlFlags int64, NotifyFlags int64, MinSize int64, MaxSize int64, IncludedAttributes int64, ExcludedAttributes int64) (bool, error)
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 component'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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used to denote all currently set access restriction flags. |
The ControlFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component tracks. |
The NotifyFlags parameter specifies which filesystem operations the component 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_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component 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.
AddReparseRule Method (CBFilter Component)
This method adds a reparse rule.
Syntax
func (obj *CBFilter) AddReparseRule(Mask string, ReparseMask string, ProductGUID string, Flags int32) (bool, error)
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_PATH | 0 | Perform redirection by modifying the path directly using the CBFilter system driver. |
| FS_REPARSE_USE_REPARSE_POINT | 1 | Perform 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.
CloseDefaultRulesSnapshot Method (CBFilter Component)
This method closes the previously created default rules snapshot.
Syntax
func (obj *CBFilter) CloseDefaultRulesSnapshot() error
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.
CloseReparseRulesSnapshot Method (CBFilter Component)
This method closes the previously created reparse rules snapshot.
Syntax
func (obj *CBFilter) CloseReparseRulesSnapshot() error
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.
Config Method (CBFilter Component)
Sets or retrieves a configuration setting.
Syntax
func (obj *CBFilter) Config(ConfigurationString string) (string, error)
Remarks
Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.
CreateDefaultRulesSnapshot Method (CBFilter Component)
This method creates a snapshot of information about the default rules that have been added.
Syntax
func (obj *CBFilter) CreateDefaultRulesSnapshot(ProductGUID string) error
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 component 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.
CreateFileDirect Method (CBFilter Component)
This method creates or opens a file or directory by passing the request directly to the filesystem.
Syntax
func (obj *CBFilter) CreateFileDirect(FileName string, Synchronize bool, DesiredAccess int32, ShareMode int32, CreationDisposition int32, FlagsAndAttributes int32, CloseImmediately bool) (int64, error)
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 it without sending requests through the 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.
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.
Because all requests against the returned file handle are routed directly to the filesystem (bypassing all filter drivers, including the component'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 returned handle can be used with some of the Windows API functions that accept a file handle as a parameter. Support may vary depending on the internal implementation of each function. The following Windows API functions have been tested and proven to work:
- CloseHandle
- GetFileInformationByHandleEx
- GetFileSize
- GetFileType
- GetSecurityInfo (additional process privileges are required)
- ReadFile
- SetSecurityInfo (additional process privileges are required)
- WriteFile
Note: When calling the GetFileInformationByHandleEx function, only the following information classes are currently supported:
- FileAttributeTagInfo
- FileBasicInfo
- FileStandardInfo
- FileStreamInfo
- FileIdInfo
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 ShareMode parameter should be set by ORing together zero or more of the following flags:
| FILESYS_SHARE_NONE | 0x00000000 | Prevents any process from opening a file or device if it requests delete, read, or write access. |
| FILESYS_SHARE_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_CHECK | 0x10000000 | Specifies 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. 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.
If Synchronize is true, this method and all operations with the resulting handle will be execute in the context of the external thread that originated the underlying filesystem request associated with the current event (which is important for on-the-fly file data modification like encryption), and the following restrictions will apply:
- The method may be called from any event handlers with the exception of AfterCloseFile and CleanupContext. Note: To be able to call the method from the BeforeCreateFile and BeforeOpenFile event handlers, set the AllowFileAccessInBeforeOpen configuration setting to true.
- The method should be called only for the file or directory that the event fired for.
- A file will be opened without buffering, which means that applications must comply with all restrictions imposed by the FILE_FLAG_NO_BUFFERING flag when reading and writing file data. Please refer to Microsoft's File Buffering article for more information.
If Synchronize is false, this method and operations with the resulting handle are executed in the context of the thread in which the corresponding call is made, and the restrictions described above do not apply. This provides applications with greater flexibility because the returned file handle can be used in any event (as long as its handler complies with the general restrictions described by the Avoiding Deadlocks and Recursive Calls topics).
In both cases, the component must be active - that is, it must be started using a call to the StartFilter method.
CreateFileDirectAsStream Method (CBFilter Component)
This method creates or opens a file by passing the request directly to the filesystem.
Syntax
func (obj *CBFilter) CreateFileDirectAsStream(FileName string, Synchronize bool, DesiredAccess int32, ShareMode int32, CreationDisposition int32, FlagsAndAttributes int32, Handle *int64) (*CBFSFilterStream, error)
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 it without sending requests through the 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 nil. Upon success, the Handle parameter is populated with the handle value, which can be used to call SetFileSizeDirect or SetFileInformationDirect if needed.
Because all requests against the file are routed directly to the filesystem (bypassing all filter drivers, including the component's), applications can use the returned stream 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 ShareMode parameter should be set by ORing together zero or more of the following flags:
| FILESYS_SHARE_NONE | 0x00000000 | Prevents any process from opening a file or device if it requests delete, read, or write access. |
| FILESYS_SHARE_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_CHECK | 0x10000000 | Specifies 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. 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.
If Synchronize is true, this method and all operations with the resulting handle will be execute in the context of the external thread that originated the underlying filesystem request associated with the current event (which is important for on-the-fly file data modification like encryption), and the following restrictions will apply:
- The method may be called from any event handlers with the exception of AfterCloseFile and CleanupContext. Note: To be able to call the method from the BeforeCreateFile and BeforeOpenFile event handlers, set the AllowFileAccessInBeforeOpen configuration setting to true.
- The method should be called only for the file or directory that the event fired for.
- A file will be opened without buffering, which means that applications must comply with all restrictions imposed by the FILE_FLAG_NO_BUFFERING flag when reading and writing file data. Please refer to Microsoft's File Buffering article for more information.
If Synchronize is false, this method and operations with the resulting handle are executed in the context of the thread in which the corresponding call is made, and the restrictions described above do not apply. This provides applications with greater flexibility because the returned file handle can be used in any event (as long as its handler complies with the general restrictions described by the Avoiding Deadlocks and Recursive Calls topics).
In both cases, the component must be active - that is, it must be started using a call to the StartFilter method.
CreateReparseRulesSnapshot Method (CBFilter Component)
This method creates a snapshot of information about the reparse rules that have been added.
Syntax
func (obj *CBFilter) CreateReparseRulesSnapshot(ProductGUID string) error
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 component 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.
CreateVirtualFile Method (CBFilter Component)
This method is under construction.
Syntax
func (obj *CBFilter) CreateVirtualFile(FileName string, DesiredAccess int32, ShareMode int32, CreationDisposition int32, FlagsAndAttributes int32) (int64, error)
Remarks
This method is under construction.
DeleteAllFilterRules Method (CBFilter Component)
This method deletes all standard filter rules and access rules.
Syntax
func (obj *CBFilter) DeleteAllFilterRules() (bool, error)
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.
DeleteAllPassthroughRules Method (CBFilter Component)
This method deletes all passthrough rules.
Syntax
func (obj *CBFilter) DeleteAllPassthroughRules() (bool, error)
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.
DeleteAllReparseRules Method (CBFilter Component)
This method deletes all reparse rules.
Syntax
func (obj *CBFilter) DeleteAllReparseRules(ProductGUID string) (bool, error)
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.
DeleteDefaultRule Method (CBFilter Component)
This method deletes a particular default rule.
Syntax
func (obj *CBFilter) DeleteDefaultRule(Mask string, AccessFlags int32, ProductGUID string) (bool, error)
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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used 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.
DeleteFilterRule Method (CBFilter Component)
This method deletes a particular standard filter rule or access rule.
Syntax
func (obj *CBFilter) DeleteFilterRule(Mask string, AccessFlags int32, ControlFlags int64, NotifyFlags int64) (bool, error)
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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used 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_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component 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_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component 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.
DeletePassthroughRule Method (CBFilter Component)
This method deletes a particular passthrough rule.
Syntax
func (obj *CBFilter) DeletePassthroughRule(Mask string, AccessFlags int32, ControlFlags int64, NotifyFlags int64) (bool, error)
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_NONE | 0x00 | No access restrictions. |
| ACCESS_READ_ONLY | 0x01 | Read-only access; writing and deleting are prohibited. |
| ACCESS_WRITE_ONLY | 0x02 | Write-only access; reading and deleting are prohibited. |
| ACCESS_DELETE_PROTECT | 0x04 | Deleting and renaming are prohibited. |
| ACCESS_EXECUTE_PROTECT | 0x08 | Execution is prohibited. |
| ACCESS_NO_CHANGE_DAC | 0x10 | Change of security attributes is prohibited. |
| ACCESS_NO_CHANGE_OWNER | 0x20 | Change of owner is prohibited. |
| ACCESS_RENAME_PROTECT | 0x40 | Renaming is prohibited. |
| ACCESS_DELETE_ONLY_PROTECT | 0x80 | Deleting is prohibited (renaming is not affected). |
| ACCESS_REMOTE_ACCESS_PROTECT | 0x100 | Access from other systems is prohibited. |
| ACCESS_DENY_ALL | 0x200 | All access is denied. |
| ACCESS_ALL_FLAGS | -1 | Used 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_NONE | 0 | Don't fire for any filesystem operations.
Control Events will not fire for any filesystem operations. |
| FS_CE_BEFORE_CREATE | 0x000000000001L | Fire 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_CREATE | 0x000000000002L | Fire 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_OPEN | 0x000000000004L | Fire 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_OPEN | 0x000000000008L | Fire 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_READ | 0x000000000010L | Fire before read operations.
The BeforeReadFile event will fire anytime the OS attempts to read data from a file. |
| FS_CE_AFTER_READ | 0x000000000020L | Fire after read operations.
The AfterReadFile event will fire after a read request has been processed, before the response is returned. |
| FS_CE_BEFORE_WRITE | 0x000000000040L | Fire before write operations.
The BeforeWriteFile event will fire anytime the OS attempts to write data to a file. |
| FS_CE_AFTER_WRITE | 0x000000000080L | Fire after write operations.
The AfterReadFile event will fire after a write request has been processed, before the response is returned. |
| FS_CE_BEFORE_LOCK_CONTROL | 0x000000000100L | Fire 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_CONTROL | 0x000000000200L | Fire 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_CLEANUP | 0x000000000400L | Fire before file handle cleanup operations.
The BeforeCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_CE_AFTER_CLEANUP | 0x000000000800L | Fire 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_CLOSE | 0x000000001000L | Fire 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_CLOSE | 0x000000002000L | Fire 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_DELETE | 0x000000004000L | Fire 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_DELETE | 0x000000008000L | Fire 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_DELETE | 0x000000010000L | Fire before delete operations
The BeforeDeleteFile event will fire anytime the OS attempts to delete a file or directory. |
| FS_CE_AFTER_DELETE | 0x000000020000L | Fire after delete operations.
The AfterDeleteFile event will fire after a delete request has been processed, before the response is returned. |
| FS_CE_BEFORE_RENAME | 0x000000040000L | Fire before rename/move operations.
The BeforeRenameOrMoveFile event will fire anytime the OS attempts to rename or move a file or directory. |
| FS_CE_AFTER_RENAME | 0x000000080000L | Fire 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_SECURITY | 0x000000100000L | Fire 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_SECURITY | 0x000000200000L | Fire 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_DIRECTORY | 0x000000400000L | Fire before directory enumeration operations.
The BeforeEnumerateDirectory event will fire anytime the OS needs to read information about directory entries. |
| FS_CE_AFTER_ENUMERATE_DIRECTORY | 0x000000800000L | Fire 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_INFO | 0x000001000000L | Fire 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_INFO | 0x000002000000L | Fire 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_SIZES | 0x000008000000L | Fire 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_SECURITY | 0x000010000000L | Fire 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_SECURITY | 0x000020000000L | Fire 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_ATTRIBUTES | 0x000040000000L | Fire 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_ATTRIBUTES | 0x000080000000L | Fire 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_SIZES | 0x000100000000L | Fire 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_SIZES | 0x000200000000L | Fire 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_LINK | 0x000400000000L | Fire before hard link creation operations.
The BeforeCreateHardLink event will fire anytime the OS attempts to create a hard link. |
| FS_CE_AFTER_CREATE_HARD_LINK | 0x000800000000L | Fire 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_FSCTL | 0x001000000000L | Fire before FSCTL operations.
The BeforeFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL request occurs. |
| FS_CE_AFTER_FSCTL | 0x002000000000L | Fire 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_IOCTL | 0x004000000000L | Fire before IOCTL operations.
The BeforeIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL request occurs. |
| FS_CE_AFTER_IOCTL | 0x008000000000L | Fire 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_INFO | 0x010000000000L | Fire 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_INFO | 0x020000000000L | Fire 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_EA | 0x040000000000L | Fire 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_EA | 0x080000000000L | Fire 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_EA | 0x100000000000L | Fire 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_EA | 0x200000000000L | Fire 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_POINT | 0x400000000000L | Fire 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_POINT | 0x800000000000L | Fire 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_POINT | 0x1000000000000L | Fire 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_POINT | 0x2000000000000L | Fire 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_POINT | 0x4000000000000L | Fire 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_POINT | 0x8000000000000L | Fire 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_FILENAME | 0x40000000000000L | Fire 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_TAG | 0x80000000000000L | Fire 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 | -1 | Fire for all filesystem operations.
Control Events will fire for all filesystem operations that the component 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_NONE | 0 | Don't fire for any filesystem operations.
Notification Events will not fire for any filesystem operations. |
| FS_NE_CREATE | 0x00000001L | Fire 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_OPEN | 0x00000002L | Fire 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_READ | 0x00000004L | Fire for read operations.
The NotifyReadFile event will fire anytime the OS reads data from a file. |
| FS_NE_WRITE | 0x00000008L | Fire for write operations.
The NotifyWriteFile event will fire anytime the OS writes data to a file. |
| FS_NE_LOCK_CONTROL | 0x00000010L | Fire 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_CLEANUP | 0x00000020L | Fire for file handle cleanup operations.
The NotifyCleanupFile event will fire anytime a process closes a file or directory handle. |
| FS_NE_CLOSE | 0x00000040L | Fire for file close operations.
The NotifyCloseFile event will fire anytime the OS closes a file or directory. |
| FS_NE_CAN_DELETE | 0x00000080L | Fire 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_DELETE | 0x00000100L | Fire for delete operations.
The NotifyDeleteFile event will fire anytime the OS deletes a file or directory. |
| FS_NE_RENAME | 0x00000200L | Fire for rename/move operations.
The NotifyRenameOrMoveFile event will fire anytime the OS renames or moves a file or directory. |
| FS_NE_GET_SECURITY | 0x00000400L | Fire for get security operations.
The NotifyGetFileSecurity event will fire anytime the OS queries the security attributes of a file or directory. |
| FS_NE_ENUMERATE_DIRECTORY | 0x00000800L | Fire for directory enumeration operations.
The NotifyEnumerateDirectory event will fire anytime the OS retrieves a directory entry during directory enumeration. |
| FS_NE_QUERY_FILE_INFO | 0x00001000L | Fire for QueryFileInformation operations.
The NotifyQueryFileInfo event will fire anytime the OS retrieves information about a file or directory. |
| FS_NE_GET_SIZES | 0x00002000L | Fire for get size operations.
The NotifyGetFileSizes event will fire anytime the OS retrieves a file's size information. |
| FS_NE_SET_SECURITY | 0x00004000L | Fire for set security operations.
The NotifySetFileSecurity event will fire anytime the OS changes the security attributes of a file or directory. |
| FS_NE_SET_ATTRIBUTES | 0x00008000L | Fire for file attribute update operations.
The NotifySetFileAttributes event will fire anytime the OS changes the attributes of a file or directory. |
| FS_NE_SET_SIZES | 0x00010000L | Fire 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_LINK | 0x00020000L | Fire for hard link creation operations.
The NotifyCreateHardLink event will fire anytime the OS creates a hard link. |
| FS_NE_FSCTL | 0x00040000L | Fire for FSCTL operations.
The NotifyFsctl event will fire anytime an IRP_MJ_FILE_SYSTEM_CONTROL operation occurs. |
| FS_NE_IOCTL | 0x00080000L | Fire for IOCTL operations.
The NotifyIoctl event will fire anytime an IRP_MJ_DEVICE_CONTROL operation occurs. |
| FS_NE_SET_FILE_INFO | 0x00100000L | Fire for SetFileInformation operations.
The NotifySetFileInfo event will fire anytime the OS changes information about a file or directory. |
| FS_NE_SET_EA | 0x00200000L | Fire for Set Extended Attributes operations.
The NotifySetEa event will fire anytime the OS sets extended attributes of a file. |
| FS_NE_QUERY_EA | 0x00400000L | Fire for Query Extended Attributes operations.
The NotifyQueryEa event will fire anytime the OS retrieves extended attributes of a file. |
| FS_NE_GET_REPARSE_POINT | 0x00800000L | Fire 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_POINT | 0x01000000L | Fire 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_POINT | 0x02000000L | Fire for Delete Reparse Point operations.
The NotifyDeleteReparsePoint event will fire anytime the OS deletes reparse point information from a file or directory. |
| FS_NE_ALL | -1 | Fire for all filesystem operations.
Notification Events will fire for all filesystem operations that the component 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.
DeleteReparseRule Method (CBFilter Component)
This method deletes a particular reparse rule.
Syntax
func (obj *CBFilter) DeleteReparseRule(Mask string, ProductGUID string) (bool, error)
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.
FileMatchesMask Method (CBFilter Component)
This method checks whether a particular file or directory name matches the specified mask.
Syntax
func (obj *CBFilter) FileMatchesMask(Mask string, FileName string, CaseSensitive bool) (bool, error)
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."
GetDriverStatus Method (CBFilter Component)
This method retrieves the status of the component's system driver.
Syntax
func (obj *CBFilter) GetDriverStatus(ProductGUID string) (int32, error)
Remarks
This method retrieves the status of the component'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_PRESENT | 0x00000000 | The specified module is not present on the system. |
| MODULE_STATUS_STOPPED | 0x00000001 | The specified module is in the Stopped state. |
| MODULE_STATUS_RUNNING | 0x00000004 | The specified module is loaded and running. |
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:
- Install
- Uninstall
- GetDriverStatus
- GetDriverVersion
- Initialize
This method is available in both the component 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.
GetDriverVersion Method (CBFilter Component)
This method retrieves the version of the component's system driver.
Syntax
func (obj *CBFilter) GetDriverVersion(ProductGUID string) (int64, error)
Remarks
This method retrieves the version of the component'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 component'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:
- Install
- Uninstall
- GetDriverStatus
- GetDriverVersion
- Initialize
This method is available in both the component 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.
GetEventFilename Method (CBFilter Component)
This method retrieves the name of the file or directory, to which the event applies.
Syntax
func (obj *CBFilter) GetEventFilename() (string, error)
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 filename, this method returns an empty string.
GetHandleCreatorProcessId Method (CBFilter Component)
This method retrieves the Id of the process (PID) that opened the file handle.
Syntax
func (obj *CBFilter) GetHandleCreatorProcessId() (int32, error)
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:
- Call this method within the AfterCreateFile or AfterOpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information through the reference stored in HandleContext.
Note: This method cannot be used from CleanupContext event handlers.
GetHandleCreatorProcessName Method (CBFilter Component)
This method retrieves the name of the process that opened the file handle.
Syntax
func (obj *CBFilter) GetHandleCreatorProcessName() (string, error)
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:
- Call this method within the AfterCreateFile or AfterOpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information through the reference stored in HandleContext.
Note: This method cannot be used from CleanupContext event handlers.
GetHandleCreatorThreadId Method (CBFilter Component)
This method retrieves the Id of the thread that opened the file handle.
Syntax
func (obj *CBFilter) GetHandleCreatorThreadId() (int32, error)
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:
- Call this method within the AfterCreateFile or AfterOpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information through the reference stored in HandleContext.
Note: This method cannot be used from CleanupContext event handlers.
GetHandleCreatorToken Method (CBFilter Component)
This method retrieves the security token associated with the process that opened the file handle.
Syntax
func (obj *CBFilter) GetHandleCreatorToken() (int64, error)
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:
- Call this method within the AfterCreateFile or AfterOpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information through the reference stored in HandleContext.
Note: This method cannot be used from CleanupContext event handlers.
GetOperationTime Method (CBFilter Component)
This method returns the time at which the request was received by the filter driver.
Syntax
func (obj *CBFilter) GetOperationTime() (time.Time, error)
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 in UTC.
GetOriginatorProcessId Method (CBFilter Component)
Retrieves the Id of the process (PID) that initiated the operation.
Syntax
func (obj *CBFilter) GetOriginatorProcessId() (int32, error)
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:
- Call this method within the CreateFile or OpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information via the reference stored in HandleContext.
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.
GetOriginatorProcessName Method (CBFilter Component)
Retrieves the name of the process that initiated the operation.
Syntax
func (obj *CBFilter) GetOriginatorProcessName() (string, error)
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:
- Call this method within the CreateFile or OpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information via the reference stored in HandleContext.
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.
GetOriginatorThreadId Method (CBFilter Component)
Retrieves the Id of the thread that initiated the operation.
Syntax
func (obj *CBFilter) GetOriginatorThreadId() (int32, error)
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:
- Call this method within the CreateFile or OpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information via the reference stored in HandleContext.
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.
GetOriginatorToken Method (CBFilter Component)
Retrieves the security token associated with the process that initiated the operation.
Syntax
func (obj *CBFilter) GetOriginatorToken() (int64, error)
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:
- Call this method within the CreateFile or OpenFile event.
- Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
- In a later event, access the information via the reference stored in HandleContext.
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.
GetRemoteAccessInformation Method (CBFilter Component)
This method returns networking-related information about the operation.
Syntax
func (obj *CBFilter) GetRemoteAccessInformation(ShareName *string, ClientSocketAddressBuffer int64, ClientSocketAddressBufferSize *int32) error
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.
GetReparseRuleByMask Method (CBFilter Component)
This method retrieves the reparse rule associated with the specified file mask.
Syntax
func (obj *CBFilter) GetReparseRuleByMask(Mask string, ProductGUID string) (string, error)
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.
GetVolumeGUID Method (CBFilter Component)
This method retrieves the volume GUID of the device targeted by a filesystem operation.
Syntax
func (obj *CBFilter) GetVolumeGUID() (string, error)
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.
Initialize Method (CBFilter Component)
This method initializes the component.
Syntax
func (obj *CBFilter) Initialize(ProductGUID string) error
Remarks
This method initializes the component and must be called each time the application starts before attempting to call any of the component'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 component can be used.
Install Method (CBFilter Component)
This method installs (or upgrades) the component's system driver.
Syntax
func (obj *CBFilter) Install(CabFileName string, ProductGUID string, PathToInstall string, Altitude string, Flags int32) (bool, error)
Remarks
This method is used to install or upgrade the component'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 component'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 component'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_VERSIONS | 0x00000001 | Uninstall drivers from previous component versions (e.g., 2017). |
| INSTALL_KEEP_START_TYPE | 0x00000002 | Keep 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_REQUESTS_VIA_DRIVER_STACK | 0x00000004 | Whether 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_FILES | 0x00010000 | Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the component 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 component 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_CHECK | 0x00020000 | Whether 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_CHECKS | 0x00040000 | Whether 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.
This method is available in both the component 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.
IsFileFiltered Method (CBFilter Component)
This method checks whether a particular file or directory is covered by any filter rules.
Syntax
func (obj *CBFilter) IsFileFiltered(FileName string) (bool, error)
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 component 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 component's CreateFileDirect method rather than the Windows API's CreateFile function, because the latter could trigger recursion and cause a system deadlock.
NtStatusToWin32Error Method (CBFilter Component)
This method converts a native status code to a Win32 error code.
Syntax
func (obj *CBFilter) NtStatusToWin32Error(Status int32) (int32, error)
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).
ResetTimeout Method (CBFilter Component)
This method resets the timeout duration for the current event handler.
Syntax
func (obj *CBFilter) ResetTimeout(Timeout int32) (bool, error)
Remarks
When event timeouts are being enforced, this method can be called within an event handler to inform the component 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.
SetFileInformationDirect Method (CBFilter Component)
This method sets the file information of a file opened using CreateFileDirect.
Syntax
func (obj *CBFilter) SetFileInformationDirect(FileHandle int64, InformationClass int32, FileInformation []byte) error
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.
SetFileSizeDirect Method (CBFilter Component)
This method resizes a file by passing the request directly to the filesystem.
Syntax
func (obj *CBFilter) SetFileSizeDirect(FileHandle int64, Size int64) (bool, error)
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.
ShutdownSystem Method (CBFilter Component)
Shuts down or reboots the operating system.
Syntax
func (obj *CBFilter) ShutdownSystem(ShutdownPrompt string, Timeout int32, ForceCloseApps bool, Reboot bool) (bool, error)
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 component 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.
StartFilter Method (CBFilter Component)
This method starts filtering filesystem operations.
Syntax
func (obj *CBFilter) StartFilter(Timeout int32) error
Remarks
This method attaches the filter, causing the component'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.
The Timeout parameter 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.
This method can fail for a number of reasons, including (but not limited to) the following:
- If the component'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.
StopFilter Method (CBFilter Component)
This method stops filtering filesystem operations.
Syntax
func (obj *CBFilter) StopFilter(Reserved bool) error
Remarks
This method detaches the filter, causing the component'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.
The Reserved parameter is obsolete.
SuspendDefaultRules Method (CBFilter Component)
This method suspends all default rules until the application exits.
Syntax
func (obj *CBFilter) SuspendDefaultRules(ProductGUID string) (bool, error)
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 component's system driver will reactivate the suspended rules and start enforcing them once again.
SuspendFileEvents Method (CBFilter Component)
This method suspends all events for a particular file or directory until all of its handles have been closed.
Syntax
func (obj *CBFilter) SuspendFileEvents() error
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 component 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.
ToggleProcessProtection Method (CBFilter Component)
This method enables or disables termination protection for the application.
Syntax
func (obj *CBFilter) ToggleProcessProtection(Enabled bool) (bool, error)
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.
Uninstall Method (CBFilter Component)
This method uninstalls the component's system driver.
Syntax
func (obj *CBFilter) Uninstall(CabFileName string, ProductGUID string, InstalledPath string, Flags int32) (bool, error)
Remarks
This method is used to uninstall the component'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 component'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 component's system driver should be uninstalled and which should be set by ORing together one or more of the following values:
| UNINSTALL_VERSION_PREVIOUS | 0x00000001 | Uninstall modules from previous product versions. |
| UNINSTALL_VERSION_CURRENT | 0x00000002 | Uninstall modules from the current product version. |
| UNINSTALL_VERSION_ALL | 0x00000003 | Uninstall modules from all product versions. |
This method is available in both the component 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.
AfterCanFileBeDeleted Event (CBFilter Component)
This event fires after the OS marks a file or directory for deletion or removes such a mark.
Syntax
// CBFilterAfterCanFileBeDeletedEventArgs carries the CBFilter AfterCanFileBeDeleted event's parameters.
type CBFilterAfterCanFileBeDeletedEventArgs struct {...}
func (args *CBFilterAfterCanFileBeDeletedEventArgs) FileName() string
func (args *CBFilterAfterCanFileBeDeletedEventArgs) RequestType() int32
func (args *CBFilterAfterCanFileBeDeletedEventArgs) CanDelete() bool
func (args *CBFilterAfterCanFileBeDeletedEventArgs) Status() int32
func (args *CBFilterAfterCanFileBeDeletedEventArgs) SetStatus(value int32)
func (args *CBFilterAfterCanFileBeDeletedEventArgs) FileContext() int64
func (args *CBFilterAfterCanFileBeDeletedEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterCanFileBeDeletedEventArgs) HandleContext() int64
func (args *CBFilterAfterCanFileBeDeletedEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterCanFileBeDeletedEventArgs) ResultCode() int32
func (args *CBFilterAfterCanFileBeDeletedEventArgs) SetResultCode(value int32)
// CBFilterAfterCanFileBeDeletedEvent defines the signature of the CBFilter AfterCanFileBeDeleted event's handler function.
type CBFilterAfterCanFileBeDeletedEvent func(sender *CBFilter, args *CBFilterAfterCanFileBeDeletedEventArgs)
func (obj *CBFilter) GetOnAfterCanFileBeDeletedHandler() CBFilterAfterCanFileBeDeletedEvent
func (obj *CBFilter) SetOnAfterCanFileBeDeletedHandler(handlerFunc CBFilterAfterCanFileBeDeletedEvent)
Remarks
This event fires after the OS marks the file or directory specified by FileName for deletion or removes such a mark.
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_FLAG | 0x1 | The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag |
| DEL_REQ_SET_DISPOSITION | 0x2 | The 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterCleanupFile Event (CBFilter Component)
This event fires after a file or directory handle is closed.
Syntax
// CBFilterAfterCleanupFileEventArgs carries the CBFilter AfterCleanupFile event's parameters.
type CBFilterAfterCleanupFileEventArgs struct {...}
func (args *CBFilterAfterCleanupFileEventArgs) FileName() string
func (args *CBFilterAfterCleanupFileEventArgs) FileContext() int64
func (args *CBFilterAfterCleanupFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterCleanupFileEventArgs) HandleContext() int64
func (args *CBFilterAfterCleanupFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterCleanupFileEventArgs) ResultCode() int32
func (args *CBFilterAfterCleanupFileEventArgs) SetResultCode(value int32)
// CBFilterAfterCleanupFileEvent defines the signature of the CBFilter AfterCleanupFile event's handler function.
type CBFilterAfterCleanupFileEvent func(sender *CBFilter, args *CBFilterAfterCleanupFileEventArgs)
func (obj *CBFilter) GetOnAfterCleanupFileHandler() CBFilterAfterCleanupFileEvent
func (obj *CBFilter) SetOnAfterCleanupFileHandler(handlerFunc CBFilterAfterCleanupFileEvent)
Remarks
This event fires after a handle to the file or directory specified by FileName is closed. 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterCloseEnumeration Event (CBFilter Component)
This event fires after a directory enumeration operation finishes.
Syntax
// CBFilterAfterCloseEnumerationEventArgs carries the CBFilter AfterCloseEnumeration event's parameters.
type CBFilterAfterCloseEnumerationEventArgs struct {...}
func (args *CBFilterAfterCloseEnumerationEventArgs) DirectoryName() string
func (args *CBFilterAfterCloseEnumerationEventArgs) DirectoryContext() int64
func (args *CBFilterAfterCloseEnumerationEventArgs) HandleContext() int64
func (args *CBFilterAfterCloseEnumerationEventArgs) EnumerationContext() int64
func (args *CBFilterAfterCloseEnumerationEventArgs) ResultCode() int32
func (args *CBFilterAfterCloseEnumerationEventArgs) SetResultCode(value int32)
// CBFilterAfterCloseEnumerationEvent defines the signature of the CBFilter AfterCloseEnumeration event's handler function.
type CBFilterAfterCloseEnumerationEvent func(sender *CBFilter, args *CBFilterAfterCloseEnumerationEventArgs)
func (obj *CBFilter) GetOnAfterCloseEnumerationHandler() CBFilterAfterCloseEnumerationEvent
func (obj *CBFilter) SetOnAfterCloseEnumerationHandler(handlerFunc CBFilterAfterCloseEnumerationEvent)
Remarks
This event fires after enumeration of the directory specified by DirectoryName finishes.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterCloseFile Event (CBFilter Component)
This event fires after a file or directory is closed.
Syntax
// CBFilterAfterCloseFileEventArgs carries the CBFilter AfterCloseFile event's parameters.
type CBFilterAfterCloseFileEventArgs struct {...}
func (args *CBFilterAfterCloseFileEventArgs) FileName() string
func (args *CBFilterAfterCloseFileEventArgs) FileContext() int64
func (args *CBFilterAfterCloseFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterCloseFileEventArgs) HandleContext() int64
func (args *CBFilterAfterCloseFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterCloseFileEventArgs) ResultCode() int32
func (args *CBFilterAfterCloseFileEventArgs) SetResultCode(value int32)
// CBFilterAfterCloseFileEvent defines the signature of the CBFilter AfterCloseFile event's handler function.
type CBFilterAfterCloseFileEvent func(sender *CBFilter, args *CBFilterAfterCloseFileEventArgs)
func (obj *CBFilter) GetOnAfterCloseFileHandler() CBFilterAfterCloseFileEvent
func (obj *CBFilter) SetOnAfterCloseFileHandler(handlerFunc CBFilterAfterCloseFileEvent)
Remarks
This event fires after the file or directory specified by FileName is closed.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterCreateFile Event (CBFilter Component)
This event fires after a file or directory is created.
Syntax
// CBFilterAfterCreateFileEventArgs carries the CBFilter AfterCreateFile event's parameters.
type CBFilterAfterCreateFileEventArgs struct {...}
func (args *CBFilterAfterCreateFileEventArgs) FileName() string
func (args *CBFilterAfterCreateFileEventArgs) ExistingAttributes() int32
func (args *CBFilterAfterCreateFileEventArgs) Isolate() bool
func (args *CBFilterAfterCreateFileEventArgs) BackendFileName() string
func (args *CBFilterAfterCreateFileEventArgs) DesiredAccess() int32
func (args *CBFilterAfterCreateFileEventArgs) Attributes() int32
func (args *CBFilterAfterCreateFileEventArgs) ShareMode() int32
func (args *CBFilterAfterCreateFileEventArgs) Options() int32
func (args *CBFilterAfterCreateFileEventArgs) CreateDisposition() int32
func (args *CBFilterAfterCreateFileEventArgs) SecurityDescriptor() []byte
func (args *CBFilterAfterCreateFileEventArgs) Length() int32
func (args *CBFilterAfterCreateFileEventArgs) Status() int32
func (args *CBFilterAfterCreateFileEventArgs) SetStatus(value int32)
func (args *CBFilterAfterCreateFileEventArgs) FileContext() int64
func (args *CBFilterAfterCreateFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterCreateFileEventArgs) HandleContext() int64
func (args *CBFilterAfterCreateFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterCreateFileEventArgs) ResultCode() int32
func (args *CBFilterAfterCreateFileEventArgs) SetResultCode(value int32)
// CBFilterAfterCreateFileEvent defines the signature of the CBFilter AfterCreateFile event's handler function.
type CBFilterAfterCreateFileEvent func(sender *CBFilter, args *CBFilterAfterCreateFileEventArgs)
func (obj *CBFilter) GetOnAfterCreateFileHandler() CBFilterAfterCreateFileEvent
func (obj *CBFilter) SetOnAfterCreateFileHandler(handlerFunc CBFilterAfterCreateFileEvent)
Remarks
This event fires after the file or directory specified by FileName is created. Please refer to the File Create/Open Events topic for more information about how the component 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.
Isolation-related functionality is under construction.
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_DIRECTORY | 0x00000001 | For a directory, the right to list the contents of the directory. |
| DESIRED_ACCESS_FILE_READ_DATA | 0x00000001 | For 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_FILE | 0x00000002 | For a directory, the right to create a file in the directory. |
| DESIRED_ACCESS_FILE_WRITE_DATA | 0x00000002 | For 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_SUBDIRECTORY | 0x00000004 | For a directory, the right to create a subdirectory. |
| DESIRED_ACCESS_FILE_APPEND_DATA | 0x00000004 | For 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_EA | 0x00000008 | The right to read extended file attributes. |
| DESIRED_ACCESS_FILE_WRITE_EA | 0x00000010 | The right to write extended file attributes. |
| DESIRED_ACCESS_FILE_EXECUTE | 0x00000020 | For 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_CHILD | 0x00000040 | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| DESIRED_ACCESS_FILE_READ_ATTRIBUTES | 0x00000080 | The right to read file attributes. |
| DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES | 0x00000100 | The right to write file attributes. |
| DESIRED_ACCESS_READ_CONTROL | 0x00020000 | 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_READ | 0x00020000 | Includes 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_WRITE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_SYNCHRONIZE | 0x00100000 | The 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_ACCESS | 0x001F01FF | All possible access rights for a file. |
| DESIRED_ACCESS_FILE_GENERIC_READ | 0x00120089 | A 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_WRITE | 0x00120116 | A 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_EXECUTE | 0x001200A0 | A 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_ONLY | 0x00000001 | The 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_HIDDEN | 0x00000002 | The file or directory is hidden.
The file is not included in an ordinary directory listing. |
| FILE_SYS_ATTR_SYSTEM | 0x00000004 | A file or directory that the operating system uses a part of, or uses exclusively. |
| FILE_SYS_ATTR_DIRECTORY | 0x00000010 | The entry is a directory. |
| FILE_SYS_ATTR_ARCHIVE | 0x00000020 | The entry is an archive file or directory.
Applications typically use this attribute to mark files for backup or removal. |
| FILE_SYS_ATTR_NORMAL | 0x00000080 | A file doesn't have other attributes set.
This attribute is valid only when used alone. |
| FILE_SYS_ATTR_TEMPORARY | 0x00000100 | A 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_FILE | 0x00000200 | A file that is a sparse file. |
| FILE_SYS_ATTR_REPARSE_POINT | 0x00000400 | A file that is a reparse point or a symbolic link. |
| FILE_SYS_ATTR_COMPRESSED | 0x00000800 | A 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_OFFLINE | 0x00001000 | The 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_INDEXED | 0x00002000 | The file or directory is not to be indexed by the content indexing service. |
| FILE_SYS_ATTR_ENCRYPTED | 0x00004000 | A 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_VIRTUAL | 0x00010000 | Reserved.
Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations. |
| FILE_SYS_ATTR_RECALL_ON_OPEN | 0x00040000 | The 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_NEW | 0x00000001 | Creates 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_ALWAYS | 0x00000002 | Creates 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_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens 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_EXISTING | 0x00000005 | Opens 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 component 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterCreateHardLink Event (CBFilter Component)
This event fires after a hard link is created.
Syntax
// CBFilterAfterCreateHardLinkEventArgs carries the CBFilter AfterCreateHardLink event's parameters.
type CBFilterAfterCreateHardLinkEventArgs struct {...}
func (args *CBFilterAfterCreateHardLinkEventArgs) FileName() string
func (args *CBFilterAfterCreateHardLinkEventArgs) LinkName() string
func (args *CBFilterAfterCreateHardLinkEventArgs) Status() int32
func (args *CBFilterAfterCreateHardLinkEventArgs) SetStatus(value int32)
func (args *CBFilterAfterCreateHardLinkEventArgs) FileContext() int64
func (args *CBFilterAfterCreateHardLinkEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterCreateHardLinkEventArgs) HandleContext() int64
func (args *CBFilterAfterCreateHardLinkEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterCreateHardLinkEventArgs) ResultCode() int32
func (args *CBFilterAfterCreateHardLinkEventArgs) SetResultCode(value int32)
// CBFilterAfterCreateHardLinkEvent defines the signature of the CBFilter AfterCreateHardLink event's handler function.
type CBFilterAfterCreateHardLinkEvent func(sender *CBFilter, args *CBFilterAfterCreateHardLinkEventArgs)
func (obj *CBFilter) GetOnAfterCreateHardLinkHandler() CBFilterAfterCreateHardLinkEvent
func (obj *CBFilter) SetOnAfterCreateHardLinkHandler(handlerFunc CBFilterAfterCreateHardLinkEvent)
Remarks
This event fires after a hard link to the file specified by FileName is created. 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterDeleteFile Event (CBFilter Component)
This event fires after a file or directory is deleted.
Syntax
// CBFilterAfterDeleteFileEventArgs carries the CBFilter AfterDeleteFile event's parameters.
type CBFilterAfterDeleteFileEventArgs struct {...}
func (args *CBFilterAfterDeleteFileEventArgs) FileName() string
func (args *CBFilterAfterDeleteFileEventArgs) RequestType() int32
func (args *CBFilterAfterDeleteFileEventArgs) FileContext() int64
func (args *CBFilterAfterDeleteFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterDeleteFileEventArgs) HandleContext() int64
func (args *CBFilterAfterDeleteFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterDeleteFileEventArgs) ResultCode() int32
func (args *CBFilterAfterDeleteFileEventArgs) SetResultCode(value int32)
// CBFilterAfterDeleteFileEvent defines the signature of the CBFilter AfterDeleteFile event's handler function.
type CBFilterAfterDeleteFileEvent func(sender *CBFilter, args *CBFilterAfterDeleteFileEventArgs)
func (obj *CBFilter) GetOnAfterDeleteFileHandler() CBFilterAfterDeleteFileEvent
func (obj *CBFilter) SetOnAfterDeleteFileHandler(handlerFunc CBFilterAfterDeleteFileEvent)
Remarks
This event fires after the file or directory specified by FileName is deleted. 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_FLAG | 0x1 | The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag |
| DEL_REQ_SET_DISPOSITION | 0x2 | The 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterDeleteReparsePoint Event (CBFilter Component)
This event fires after the OS deletes a reparse point from a file or directory.
Syntax
// CBFilterAfterDeleteReparsePointEventArgs carries the CBFilter AfterDeleteReparsePoint event's parameters.
type CBFilterAfterDeleteReparsePointEventArgs struct {...}
func (args *CBFilterAfterDeleteReparsePointEventArgs) FileName() string
func (args *CBFilterAfterDeleteReparsePointEventArgs) ReparseBuffer() []byte
func (args *CBFilterAfterDeleteReparsePointEventArgs) BufferLength() int32
func (args *CBFilterAfterDeleteReparsePointEventArgs) Status() int32
func (args *CBFilterAfterDeleteReparsePointEventArgs) SetStatus(value int32)
func (args *CBFilterAfterDeleteReparsePointEventArgs) FileContext() int64
func (args *CBFilterAfterDeleteReparsePointEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterDeleteReparsePointEventArgs) HandleContext() int64
func (args *CBFilterAfterDeleteReparsePointEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterDeleteReparsePointEventArgs) ResultCode() int32
func (args *CBFilterAfterDeleteReparsePointEventArgs) SetResultCode(value int32)
// CBFilterAfterDeleteReparsePointEvent defines the signature of the CBFilter AfterDeleteReparsePoint event's handler function.
type CBFilterAfterDeleteReparsePointEvent func(sender *CBFilter, args *CBFilterAfterDeleteReparsePointEventArgs)
func (obj *CBFilter) GetOnAfterDeleteReparsePointHandler() CBFilterAfterDeleteReparsePointEvent
func (obj *CBFilter) SetOnAfterDeleteReparsePointHandler(handlerFunc CBFilterAfterDeleteReparsePointEvent)
Remarks
This event fires after the OS deletes a reparse point from a file or directory specified by FileName.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterEnumerateDirectory Event (CBFilter Component)
This event fires after a directory entry is returned during directory enumeration.
Syntax
// CBFilterAfterEnumerateDirectoryEventArgs carries the CBFilter AfterEnumerateDirectory event's parameters.
type CBFilterAfterEnumerateDirectoryEventArgs struct {...}
func (args *CBFilterAfterEnumerateDirectoryEventArgs) DirectoryName() string
func (args *CBFilterAfterEnumerateDirectoryEventArgs) Flags() int32
func (args *CBFilterAfterEnumerateDirectoryEventArgs) Index() int32
func (args *CBFilterAfterEnumerateDirectoryEventArgs) FileName() string
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetFileName(value string)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) CreationTime() time.Time
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetCreationTime(value time.Time)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) LastAccessTime() time.Time
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetLastAccessTime(value time.Time)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) LastWriteTime() time.Time
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetLastWriteTime(value time.Time)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) ChangeTime() time.Time
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetChangeTime(value time.Time)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) Size() int64
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetSize(value int64)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) AllocationSize() int64
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetAllocationSize(value int64)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) FileId() int64
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetFileId(value int64)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) Attributes() int32
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetAttributes(value int32)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) Status() int32
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetStatus(value int32)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) DirectoryContext() int64
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetDirectoryContext(value int64)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) HandleContext() int64
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) EnumerationContext() int64
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetEnumerationContext(value int64)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) ProcessRequest() bool
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetProcessRequest(value bool)
func (args *CBFilterAfterEnumerateDirectoryEventArgs) ResultCode() int32
func (args *CBFilterAfterEnumerateDirectoryEventArgs) SetResultCode(value int32)
// CBFilterAfterEnumerateDirectoryEvent defines the signature of the CBFilter AfterEnumerateDirectory event's handler function.
type CBFilterAfterEnumerateDirectoryEvent func(sender *CBFilter, args *CBFilterAfterEnumerateDirectoryEventArgs)
func (obj *CBFilter) GetOnAfterEnumerateDirectoryHandler() CBFilterAfterEnumerateDirectoryEvent
func (obj *CBFilter) SetOnAfterEnumerateDirectoryHandler(handlerFunc CBFilterAfterEnumerateDirectoryEvent)
Remarks
This event fires after a directory entry (i.e., a file or subdirectory) is returned during enumeration of the directory specified by DirectoryName.
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_SCAN | 1 | The requestor specified that directory enumeration must be restarted. |
| FS_ENUM_RETURN_SINGLE_ENTRY | 2 | One entry should be returned. |
| FS_ENUM_INDEX_SPECIFIED | 4 | The 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 in UTC.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterFilterAttachToVolume Event (CBFilter Component)
This event fires after the filter attaches to a newly mounted filesystem volume.
Syntax
// CBFilterAfterFilterAttachToVolumeEventArgs carries the CBFilter AfterFilterAttachToVolume event's parameters.
type CBFilterAfterFilterAttachToVolumeEventArgs struct {...}
func (args *CBFilterAfterFilterAttachToVolumeEventArgs) VolumeName() string
func (args *CBFilterAfterFilterAttachToVolumeEventArgs) ResultCode() int32
func (args *CBFilterAfterFilterAttachToVolumeEventArgs) SetResultCode(value int32)
// CBFilterAfterFilterAttachToVolumeEvent defines the signature of the CBFilter AfterFilterAttachToVolume event's handler function.
type CBFilterAfterFilterAttachToVolumeEvent func(sender *CBFilter, args *CBFilterAfterFilterAttachToVolumeEventArgs)
func (obj *CBFilter) GetOnAfterFilterAttachToVolumeHandler() CBFilterAfterFilterAttachToVolumeEvent
func (obj *CBFilter) SetOnAfterFilterAttachToVolumeHandler(handlerFunc CBFilterAfterFilterAttachToVolumeEvent)
Remarks
This event fires after the filter attaches to the newly mounted filesystem volume specified by 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.
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.
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 format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterFilterDetachFromVolume Event (CBFilter Component)
This event fires after the filter detaches from a filesystem volume.
Syntax
// CBFilterAfterFilterDetachFromVolumeEventArgs carries the CBFilter AfterFilterDetachFromVolume event's parameters.
type CBFilterAfterFilterDetachFromVolumeEventArgs struct {...}
func (args *CBFilterAfterFilterDetachFromVolumeEventArgs) VolumeName() string
func (args *CBFilterAfterFilterDetachFromVolumeEventArgs) ResultCode() int32
func (args *CBFilterAfterFilterDetachFromVolumeEventArgs) SetResultCode(value int32)
// CBFilterAfterFilterDetachFromVolumeEvent defines the signature of the CBFilter AfterFilterDetachFromVolume event's handler function.
type CBFilterAfterFilterDetachFromVolumeEvent func(sender *CBFilter, args *CBFilterAfterFilterDetachFromVolumeEventArgs)
func (obj *CBFilter) GetOnAfterFilterDetachFromVolumeHandler() CBFilterAfterFilterDetachFromVolumeEvent
func (obj *CBFilter) SetOnAfterFilterDetachFromVolumeHandler(handlerFunc CBFilterAfterFilterDetachFromVolumeEvent)
Remarks
This event fires after the filter detaches from the filesystem volume specified by 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.
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 format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterFsctl Event (CBFilter Component)
This event fires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
Syntax
// CBFilterAfterFsctlEventArgs carries the CBFilter AfterFsctl event's parameters.
type CBFilterAfterFsctlEventArgs struct {...}
func (args *CBFilterAfterFsctlEventArgs) FileName() string
func (args *CBFilterAfterFsctlEventArgs) FsControlCode() int32
func (args *CBFilterAfterFsctlEventArgs) InBuffer() []byte
func (args *CBFilterAfterFsctlEventArgs) InBufferLength() int32
func (args *CBFilterAfterFsctlEventArgs) InBufferValidBytes() int32
func (args *CBFilterAfterFsctlEventArgs) OutBuffer() []byte
func (args *CBFilterAfterFsctlEventArgs) SetOutBuffer(value []byte)
func (args *CBFilterAfterFsctlEventArgs) OutBufferLength() int32
func (args *CBFilterAfterFsctlEventArgs) OutBufferValidBytes() int32
func (args *CBFilterAfterFsctlEventArgs) SetOutBufferValidBytes(value int32)
func (args *CBFilterAfterFsctlEventArgs) Status() int32
func (args *CBFilterAfterFsctlEventArgs) SetStatus(value int32)
func (args *CBFilterAfterFsctlEventArgs) FileContext() int64
func (args *CBFilterAfterFsctlEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterFsctlEventArgs) HandleContext() int64
func (args *CBFilterAfterFsctlEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterFsctlEventArgs) ResultCode() int32
func (args *CBFilterAfterFsctlEventArgs) SetResultCode(value int32)
// CBFilterAfterFsctlEvent defines the signature of the CBFilter AfterFsctl event's handler function.
type CBFilterAfterFsctlEvent func(sender *CBFilter, args *CBFilterAfterFsctlEventArgs)
func (obj *CBFilter) GetOnAfterFsctlHandler() CBFilterAfterFsctlEvent
func (obj *CBFilter) SetOnAfterFsctlHandler(handlerFunc CBFilterAfterFsctlEvent)
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:
- copy no more than OutBufferLength bytes into OutBuffer; and
- 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterGetFileSecurity Event (CBFilter Component)
This event fires after a file or directory's security attributes are retrieved.
Syntax
// CBFilterAfterGetFileSecurityEventArgs carries the CBFilter AfterGetFileSecurity event's parameters.
type CBFilterAfterGetFileSecurityEventArgs struct {...}
func (args *CBFilterAfterGetFileSecurityEventArgs) FileName() string
func (args *CBFilterAfterGetFileSecurityEventArgs) SecurityInformation() int32
func (args *CBFilterAfterGetFileSecurityEventArgs) SecurityDescriptor() []byte
func (args *CBFilterAfterGetFileSecurityEventArgs) SetSecurityDescriptor(value []byte)
func (args *CBFilterAfterGetFileSecurityEventArgs) Length() int32
func (args *CBFilterAfterGetFileSecurityEventArgs) LengthNeeded() int32
func (args *CBFilterAfterGetFileSecurityEventArgs) SetLengthNeeded(value int32)
func (args *CBFilterAfterGetFileSecurityEventArgs) Status() int32
func (args *CBFilterAfterGetFileSecurityEventArgs) SetStatus(value int32)
func (args *CBFilterAfterGetFileSecurityEventArgs) FileContext() int64
func (args *CBFilterAfterGetFileSecurityEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterGetFileSecurityEventArgs) HandleContext() int64
func (args *CBFilterAfterGetFileSecurityEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterGetFileSecurityEventArgs) ResultCode() int32
func (args *CBFilterAfterGetFileSecurityEventArgs) SetResultCode(value int32)
// CBFilterAfterGetFileSecurityEvent defines the signature of the CBFilter AfterGetFileSecurity event's handler function.
type CBFilterAfterGetFileSecurityEvent func(sender *CBFilter, args *CBFilterAfterGetFileSecurityEventArgs)
func (obj *CBFilter) GetOnAfterGetFileSecurityHandler() CBFilterAfterGetFileSecurityEvent
func (obj *CBFilter) SetOnAfterGetFileSecurityHandler(handlerFunc CBFilterAfterGetFileSecurityEvent)
Remarks
This event fires after security attributes are retrieved for the file or directory specified by FileName.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterGetFileSizes Event (CBFilter Component)
This event fires after a file's size information is retrieved.
Syntax
// CBFilterAfterGetFileSizesEventArgs carries the CBFilter AfterGetFileSizes event's parameters.
type CBFilterAfterGetFileSizesEventArgs struct {...}
func (args *CBFilterAfterGetFileSizesEventArgs) FileName() string
func (args *CBFilterAfterGetFileSizesEventArgs) Size() int64
func (args *CBFilterAfterGetFileSizesEventArgs) SetSize(value int64)
func (args *CBFilterAfterGetFileSizesEventArgs) AllocationSize() int64
func (args *CBFilterAfterGetFileSizesEventArgs) SetAllocationSize(value int64)
func (args *CBFilterAfterGetFileSizesEventArgs) Status() int32
func (args *CBFilterAfterGetFileSizesEventArgs) SetStatus(value int32)
func (args *CBFilterAfterGetFileSizesEventArgs) FileContext() int64
func (args *CBFilterAfterGetFileSizesEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterGetFileSizesEventArgs) HandleContext() int64
func (args *CBFilterAfterGetFileSizesEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterGetFileSizesEventArgs) ResultCode() int32
func (args *CBFilterAfterGetFileSizesEventArgs) SetResultCode(value int32)
// CBFilterAfterGetFileSizesEvent defines the signature of the CBFilter AfterGetFileSizes event's handler function.
type CBFilterAfterGetFileSizesEvent func(sender *CBFilter, args *CBFilterAfterGetFileSizesEventArgs)
func (obj *CBFilter) GetOnAfterGetFileSizesHandler() CBFilterAfterGetFileSizesEvent
func (obj *CBFilter) SetOnAfterGetFileSizesHandler(handlerFunc CBFilterAfterGetFileSizesEvent)
Remarks
This event fires after size information is retrieved for the file specified by FileName.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterGetReparsePoint Event (CBFilter Component)
This event fires after a file or directory's reparse point information is retrieved.
Syntax
// CBFilterAfterGetReparsePointEventArgs carries the CBFilter AfterGetReparsePoint event's parameters.
type CBFilterAfterGetReparsePointEventArgs struct {...}
func (args *CBFilterAfterGetReparsePointEventArgs) FileName() string
func (args *CBFilterAfterGetReparsePointEventArgs) ReparseBuffer() []byte
func (args *CBFilterAfterGetReparsePointEventArgs) SetReparseBuffer(value []byte)
func (args *CBFilterAfterGetReparsePointEventArgs) BufferLength() int32
func (args *CBFilterAfterGetReparsePointEventArgs) DataLength() int32
func (args *CBFilterAfterGetReparsePointEventArgs) SetDataLength(value int32)
func (args *CBFilterAfterGetReparsePointEventArgs) LengthNeeded() int32
func (args *CBFilterAfterGetReparsePointEventArgs) SetLengthNeeded(value int32)
func (args *CBFilterAfterGetReparsePointEventArgs) Status() int32
func (args *CBFilterAfterGetReparsePointEventArgs) SetStatus(value int32)
func (args *CBFilterAfterGetReparsePointEventArgs) FileContext() int64
func (args *CBFilterAfterGetReparsePointEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterGetReparsePointEventArgs) HandleContext() int64
func (args *CBFilterAfterGetReparsePointEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterGetReparsePointEventArgs) ResultCode() int32
func (args *CBFilterAfterGetReparsePointEventArgs) SetResultCode(value int32)
// CBFilterAfterGetReparsePointEvent defines the signature of the CBFilter AfterGetReparsePoint event's handler function.
type CBFilterAfterGetReparsePointEvent func(sender *CBFilter, args *CBFilterAfterGetReparsePointEventArgs)
func (obj *CBFilter) GetOnAfterGetReparsePointHandler() CBFilterAfterGetReparsePointEvent
func (obj *CBFilter) SetOnAfterGetReparsePointHandler(handlerFunc CBFilterAfterGetReparsePointEvent)
Remarks
This event fires after reparse point information is retrieved for the file or directory specified by FileName.
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 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 nil.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterIoctl Event (CBFilter Component)
This event fires after an IRP_MJ_DEVICE_CONTROL request is processed.
Syntax
// CBFilterAfterIoctlEventArgs carries the CBFilter AfterIoctl event's parameters.
type CBFilterAfterIoctlEventArgs struct {...}
func (args *CBFilterAfterIoctlEventArgs) FileName() string
func (args *CBFilterAfterIoctlEventArgs) IoControlCode() int32
func (args *CBFilterAfterIoctlEventArgs) InBuffer() []byte
func (args *CBFilterAfterIoctlEventArgs) InBufferLength() int32
func (args *CBFilterAfterIoctlEventArgs) InBufferValidBytes() int32
func (args *CBFilterAfterIoctlEventArgs) OutBuffer() []byte
func (args *CBFilterAfterIoctlEventArgs) SetOutBuffer(value []byte)
func (args *CBFilterAfterIoctlEventArgs) OutBufferLength() int32
func (args *CBFilterAfterIoctlEventArgs) OutBufferValidBytes() int32
func (args *CBFilterAfterIoctlEventArgs) SetOutBufferValidBytes(value int32)
func (args *CBFilterAfterIoctlEventArgs) Status() int32
func (args *CBFilterAfterIoctlEventArgs) SetStatus(value int32)
func (args *CBFilterAfterIoctlEventArgs) FileContext() int64
func (args *CBFilterAfterIoctlEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterIoctlEventArgs) HandleContext() int64
func (args *CBFilterAfterIoctlEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterIoctlEventArgs) ResultCode() int32
func (args *CBFilterAfterIoctlEventArgs) SetResultCode(value int32)
// CBFilterAfterIoctlEvent defines the signature of the CBFilter AfterIoctl event's handler function.
type CBFilterAfterIoctlEvent func(sender *CBFilter, args *CBFilterAfterIoctlEventArgs)
func (obj *CBFilter) GetOnAfterIoctlHandler() CBFilterAfterIoctlEvent
func (obj *CBFilter) SetOnAfterIoctlHandler(handlerFunc CBFilterAfterIoctlEvent)
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:
- copy no more than OutBufferLength bytes into OutBuffer; and
- 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterLock Event (CBFilter Component)
This event fires after a range of bytes in a file is locked.
Syntax
// CBFilterAfterLockEventArgs carries the CBFilter AfterLock event's parameters.
type CBFilterAfterLockEventArgs struct {...}
func (args *CBFilterAfterLockEventArgs) FileName() string
func (args *CBFilterAfterLockEventArgs) Offset() int64
func (args *CBFilterAfterLockEventArgs) Length() int64
func (args *CBFilterAfterLockEventArgs) Key() int64
func (args *CBFilterAfterLockEventArgs) FailImmediately() bool
func (args *CBFilterAfterLockEventArgs) ExclusiveLock() bool
func (args *CBFilterAfterLockEventArgs) Status() int32
func (args *CBFilterAfterLockEventArgs) SetStatus(value int32)
func (args *CBFilterAfterLockEventArgs) FileContext() int64
func (args *CBFilterAfterLockEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterLockEventArgs) HandleContext() int64
func (args *CBFilterAfterLockEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterLockEventArgs) ResultCode() int32
func (args *CBFilterAfterLockEventArgs) SetResultCode(value int32)
// CBFilterAfterLockEvent defines the signature of the CBFilter AfterLock event's handler function.
type CBFilterAfterLockEvent func(sender *CBFilter, args *CBFilterAfterLockEventArgs)
func (obj *CBFilter) GetOnAfterLockHandler() CBFilterAfterLockEvent
func (obj *CBFilter) SetOnAfterLockHandler(handlerFunc CBFilterAfterLockEvent)
Remarks
This event fires after a range of bytes in the file specified by FileName is locked; 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterOpenFile Event (CBFilter Component)
This event fires after a file or directory is opened.
Syntax
// CBFilterAfterOpenFileEventArgs carries the CBFilter AfterOpenFile event's parameters.
type CBFilterAfterOpenFileEventArgs struct {...}
func (args *CBFilterAfterOpenFileEventArgs) FileName() string
func (args *CBFilterAfterOpenFileEventArgs) ExistingAttributes() int32
func (args *CBFilterAfterOpenFileEventArgs) Isolate() bool
func (args *CBFilterAfterOpenFileEventArgs) BackendFileName() string
func (args *CBFilterAfterOpenFileEventArgs) DesiredAccess() int32
func (args *CBFilterAfterOpenFileEventArgs) Attributes() int32
func (args *CBFilterAfterOpenFileEventArgs) ShareMode() int32
func (args *CBFilterAfterOpenFileEventArgs) Options() int32
func (args *CBFilterAfterOpenFileEventArgs) CreateDisposition() int32
func (args *CBFilterAfterOpenFileEventArgs) SecurityDescriptor() []byte
func (args *CBFilterAfterOpenFileEventArgs) Length() int32
func (args *CBFilterAfterOpenFileEventArgs) Status() int32
func (args *CBFilterAfterOpenFileEventArgs) SetStatus(value int32)
func (args *CBFilterAfterOpenFileEventArgs) FileContext() int64
func (args *CBFilterAfterOpenFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterOpenFileEventArgs) HandleContext() int64
func (args *CBFilterAfterOpenFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterOpenFileEventArgs) ResultCode() int32
func (args *CBFilterAfterOpenFileEventArgs) SetResultCode(value int32)
// CBFilterAfterOpenFileEvent defines the signature of the CBFilter AfterOpenFile event's handler function.
type CBFilterAfterOpenFileEvent func(sender *CBFilter, args *CBFilterAfterOpenFileEventArgs)
func (obj *CBFilter) GetOnAfterOpenFileHandler() CBFilterAfterOpenFileEvent
func (obj *CBFilter) SetOnAfterOpenFileHandler(handlerFunc CBFilterAfterOpenFileEvent)
Remarks
This event fires after the file or directory specified by FileName is opened. Please refer to the File Create/Open Events topic for more information about how the component 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.
Isolation-related functionality is under construction.
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_DIRECTORY | 0x00000001 | For a directory, the right to list the contents of the directory. |
| DESIRED_ACCESS_FILE_READ_DATA | 0x00000001 | For 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_FILE | 0x00000002 | For a directory, the right to create a file in the directory. |
| DESIRED_ACCESS_FILE_WRITE_DATA | 0x00000002 | For 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_SUBDIRECTORY | 0x00000004 | For a directory, the right to create a subdirectory. |
| DESIRED_ACCESS_FILE_APPEND_DATA | 0x00000004 | For 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_EA | 0x00000008 | The right to read extended file attributes. |
| DESIRED_ACCESS_FILE_WRITE_EA | 0x00000010 | The right to write extended file attributes. |
| DESIRED_ACCESS_FILE_EXECUTE | 0x00000020 | For 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_CHILD | 0x00000040 | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| DESIRED_ACCESS_FILE_READ_ATTRIBUTES | 0x00000080 | The right to read file attributes. |
| DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES | 0x00000100 | The right to write file attributes. |
| DESIRED_ACCESS_READ_CONTROL | 0x00020000 | 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_READ | 0x00020000 | Includes 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_WRITE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_SYNCHRONIZE | 0x00100000 | The 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_ACCESS | 0x001F01FF | All possible access rights for a file. |
| DESIRED_ACCESS_FILE_GENERIC_READ | 0x00120089 | A 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_WRITE | 0x00120116 | A 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_EXECUTE | 0x001200A0 | A 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_ONLY | 0x00000001 | The 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_HIDDEN | 0x00000002 | The file or directory is hidden.
The file is not included in an ordinary directory listing. |
| FILE_SYS_ATTR_SYSTEM | 0x00000004 | A file or directory that the operating system uses a part of, or uses exclusively. |
| FILE_SYS_ATTR_DIRECTORY | 0x00000010 | The entry is a directory. |
| FILE_SYS_ATTR_ARCHIVE | 0x00000020 | The entry is an archive file or directory.
Applications typically use this attribute to mark files for backup or removal. |
| FILE_SYS_ATTR_NORMAL | 0x00000080 | A file doesn't have other attributes set.
This attribute is valid only when used alone. |
| FILE_SYS_ATTR_TEMPORARY | 0x00000100 | A 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_FILE | 0x00000200 | A file that is a sparse file. |
| FILE_SYS_ATTR_REPARSE_POINT | 0x00000400 | A file that is a reparse point or a symbolic link. |
| FILE_SYS_ATTR_COMPRESSED | 0x00000800 | A 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_OFFLINE | 0x00001000 | The 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_INDEXED | 0x00002000 | The file or directory is not to be indexed by the content indexing service. |
| FILE_SYS_ATTR_ENCRYPTED | 0x00004000 | A 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_VIRTUAL | 0x00010000 | Reserved.
Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations. |
| FILE_SYS_ATTR_RECALL_ON_OPEN | 0x00040000 | The 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_NEW | 0x00000001 | Creates 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_ALWAYS | 0x00000002 | Creates 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_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens 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_EXISTING | 0x00000005 | Opens 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 component 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterQueryEa Event (CBFilter Component)
This event fires after information about extended attributes of a file is retrieved.
Syntax
// CBFilterAfterQueryEaEventArgs carries the CBFilter AfterQueryEa event's parameters.
type CBFilterAfterQueryEaEventArgs struct {...}
func (args *CBFilterAfterQueryEaEventArgs) FileName() string
func (args *CBFilterAfterQueryEaEventArgs) Buffer() []byte
func (args *CBFilterAfterQueryEaEventArgs) SetBuffer(value []byte)
func (args *CBFilterAfterQueryEaEventArgs) BufferLength() int32
func (args *CBFilterAfterQueryEaEventArgs) ReturnSingleEntry() bool
func (args *CBFilterAfterQueryEaEventArgs) EaList() []byte
func (args *CBFilterAfterQueryEaEventArgs) EaListLength() int32
func (args *CBFilterAfterQueryEaEventArgs) EaIndex() int32
func (args *CBFilterAfterQueryEaEventArgs) RestartScan() bool
func (args *CBFilterAfterQueryEaEventArgs) LengthReturned() int32
func (args *CBFilterAfterQueryEaEventArgs) SetLengthReturned(value int32)
func (args *CBFilterAfterQueryEaEventArgs) Status() int32
func (args *CBFilterAfterQueryEaEventArgs) SetStatus(value int32)
func (args *CBFilterAfterQueryEaEventArgs) FileContext() int64
func (args *CBFilterAfterQueryEaEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterQueryEaEventArgs) HandleContext() int64
func (args *CBFilterAfterQueryEaEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterQueryEaEventArgs) ResultCode() int32
func (args *CBFilterAfterQueryEaEventArgs) SetResultCode(value int32)
// CBFilterAfterQueryEaEvent defines the signature of the CBFilter AfterQueryEa event's handler function.
type CBFilterAfterQueryEaEvent func(sender *CBFilter, args *CBFilterAfterQueryEaEventArgs)
func (obj *CBFilter) GetOnAfterQueryEaHandler() CBFilterAfterQueryEaEvent
func (obj *CBFilter) SetOnAfterQueryEaHandler(handlerFunc CBFilterAfterQueryEaEvent)
Remarks
This event fires after information about extended attributes of the file specified by FileName is retrieved using the FltQueryEaFile function of the system API.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterQueryFileInfo Event (CBFilter Component)
This event fires after information about a file or directory is retrieved.
Syntax
// CBFilterAfterQueryFileInfoEventArgs carries the CBFilter AfterQueryFileInfo event's parameters.
type CBFilterAfterQueryFileInfoEventArgs struct {...}
func (args *CBFilterAfterQueryFileInfoEventArgs) FileName() string
func (args *CBFilterAfterQueryFileInfoEventArgs) FileInformationClass() int32
func (args *CBFilterAfterQueryFileInfoEventArgs) Buffer() []byte
func (args *CBFilterAfterQueryFileInfoEventArgs) SetBuffer(value []byte)
func (args *CBFilterAfterQueryFileInfoEventArgs) BufferLength() int32
func (args *CBFilterAfterQueryFileInfoEventArgs) ValidBytes() int32
func (args *CBFilterAfterQueryFileInfoEventArgs) SetValidBytes(value int32)
func (args *CBFilterAfterQueryFileInfoEventArgs) Status() int32
func (args *CBFilterAfterQueryFileInfoEventArgs) SetStatus(value int32)
func (args *CBFilterAfterQueryFileInfoEventArgs) FileContext() int64
func (args *CBFilterAfterQueryFileInfoEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterQueryFileInfoEventArgs) HandleContext() int64
func (args *CBFilterAfterQueryFileInfoEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterQueryFileInfoEventArgs) ResultCode() int32
func (args *CBFilterAfterQueryFileInfoEventArgs) SetResultCode(value int32)
// CBFilterAfterQueryFileInfoEvent defines the signature of the CBFilter AfterQueryFileInfo event's handler function.
type CBFilterAfterQueryFileInfoEvent func(sender *CBFilter, args *CBFilterAfterQueryFileInfoEventArgs)
func (obj *CBFilter) GetOnAfterQueryFileInfoHandler() CBFilterAfterQueryFileInfoEvent
func (obj *CBFilter) SetOnAfterQueryFileInfoHandler(handlerFunc CBFilterAfterQueryFileInfoEvent)
Remarks
This event fires after information about the file or directory specified by FileName is retrieved; 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:
- copy no more than BufferLength bytes into Buffer; and
- 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterReadFile Event (CBFilter Component)
This event fires after data are read from a file.
Syntax
// CBFilterAfterReadFileEventArgs carries the CBFilter AfterReadFile event's parameters.
type CBFilterAfterReadFileEventArgs struct {...}
func (args *CBFilterAfterReadFileEventArgs) FileName() string
func (args *CBFilterAfterReadFileEventArgs) Position() int64
func (args *CBFilterAfterReadFileEventArgs) Buffer() []byte
func (args *CBFilterAfterReadFileEventArgs) SetBuffer(value []byte)
func (args *CBFilterAfterReadFileEventArgs) BufferLength() int32
func (args *CBFilterAfterReadFileEventArgs) BytesToRead() int32
func (args *CBFilterAfterReadFileEventArgs) Reserved() int32
func (args *CBFilterAfterReadFileEventArgs) Direction() int32
func (args *CBFilterAfterReadFileEventArgs) BytesRead() int32
func (args *CBFilterAfterReadFileEventArgs) SetBytesRead(value int32)
func (args *CBFilterAfterReadFileEventArgs) Status() int32
func (args *CBFilterAfterReadFileEventArgs) SetStatus(value int32)
func (args *CBFilterAfterReadFileEventArgs) FileContext() int64
func (args *CBFilterAfterReadFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterReadFileEventArgs) HandleContext() int64
func (args *CBFilterAfterReadFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterReadFileEventArgs) ResultCode() int32
func (args *CBFilterAfterReadFileEventArgs) SetResultCode(value int32)
// CBFilterAfterReadFileEvent defines the signature of the CBFilter AfterReadFile event's handler function.
type CBFilterAfterReadFileEvent func(sender *CBFilter, args *CBFilterAfterReadFileEventArgs)
func (obj *CBFilter) GetOnAfterReadFileHandler() CBFilterAfterReadFileEvent
func (obj *CBFilter) SetOnAfterReadFileHandler(handlerFunc CBFilterAfterReadFileEvent)
Remarks
This event fires after data are read from the file specified by FileName.
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:
- enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires);
- copy no more than BytesToRead bytes into Buffer; and
- 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_NONCACHED | 0 | Operations performed in the user mode application <--> filesystem direction. |
| FS_REQUEST_DIR_USER_CACHED | 1 | Operations performed in the user mode application <--> system cache direction. |
| FS_REQUEST_DIR_SYSTEM_NONCACHED | 2 | Operations performed in the system cache <--> filesystem direction. |
| FS_REQUEST_DIR_SYSTEM_CACHED | 3 | Operations 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 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 nil.)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterRenameOrMoveFile Event (CBFilter Component)
This event fires after a file or directory is renamed or moved.
Syntax
// CBFilterAfterRenameOrMoveFileEventArgs carries the CBFilter AfterRenameOrMoveFile event's parameters.
type CBFilterAfterRenameOrMoveFileEventArgs struct {...}
func (args *CBFilterAfterRenameOrMoveFileEventArgs) FileName() string
func (args *CBFilterAfterRenameOrMoveFileEventArgs) NewFileName() string
func (args *CBFilterAfterRenameOrMoveFileEventArgs) Status() int32
func (args *CBFilterAfterRenameOrMoveFileEventArgs) SetStatus(value int32)
func (args *CBFilterAfterRenameOrMoveFileEventArgs) FileContext() int64
func (args *CBFilterAfterRenameOrMoveFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterRenameOrMoveFileEventArgs) HandleContext() int64
func (args *CBFilterAfterRenameOrMoveFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterRenameOrMoveFileEventArgs) ResultCode() int32
func (args *CBFilterAfterRenameOrMoveFileEventArgs) SetResultCode(value int32)
// CBFilterAfterRenameOrMoveFileEvent defines the signature of the CBFilter AfterRenameOrMoveFile event's handler function.
type CBFilterAfterRenameOrMoveFileEvent func(sender *CBFilter, args *CBFilterAfterRenameOrMoveFileEventArgs)
func (obj *CBFilter) GetOnAfterRenameOrMoveFileHandler() CBFilterAfterRenameOrMoveFileEvent
func (obj *CBFilter) SetOnAfterRenameOrMoveFileHandler(handlerFunc CBFilterAfterRenameOrMoveFileEvent)
Remarks
This event fires after the file or directory specified by FileName is renamed or moved to NewFileName.
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 filenames, 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetAllocationSize Event (CBFilter Component)
This event fires after a file's allocation size is changed.
Syntax
// CBFilterAfterSetAllocationSizeEventArgs carries the CBFilter AfterSetAllocationSize event's parameters.
type CBFilterAfterSetAllocationSizeEventArgs struct {...}
func (args *CBFilterAfterSetAllocationSizeEventArgs) FileName() string
func (args *CBFilterAfterSetAllocationSizeEventArgs) AllocationSize() int64
func (args *CBFilterAfterSetAllocationSizeEventArgs) Status() int32
func (args *CBFilterAfterSetAllocationSizeEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetAllocationSizeEventArgs) FileContext() int64
func (args *CBFilterAfterSetAllocationSizeEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetAllocationSizeEventArgs) HandleContext() int64
func (args *CBFilterAfterSetAllocationSizeEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetAllocationSizeEventArgs) ResultCode() int32
func (args *CBFilterAfterSetAllocationSizeEventArgs) SetResultCode(value int32)
// CBFilterAfterSetAllocationSizeEvent defines the signature of the CBFilter AfterSetAllocationSize event's handler function.
type CBFilterAfterSetAllocationSizeEvent func(sender *CBFilter, args *CBFilterAfterSetAllocationSizeEventArgs)
func (obj *CBFilter) GetOnAfterSetAllocationSizeHandler() CBFilterAfterSetAllocationSizeEvent
func (obj *CBFilter) SetOnAfterSetAllocationSizeHandler(handlerFunc CBFilterAfterSetAllocationSizeEvent)
Remarks
This event fires after the allocation size of the file specified by FileName is changed.
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 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 nil.)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetEa Event (CBFilter Component)
This event fires after extended attributes of a file are changed.
Syntax
// CBFilterAfterSetEaEventArgs carries the CBFilter AfterSetEa event's parameters.
type CBFilterAfterSetEaEventArgs struct {...}
func (args *CBFilterAfterSetEaEventArgs) FileName() string
func (args *CBFilterAfterSetEaEventArgs) Buffer() []byte
func (args *CBFilterAfterSetEaEventArgs) BufferLength() int32
func (args *CBFilterAfterSetEaEventArgs) Status() int32
func (args *CBFilterAfterSetEaEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetEaEventArgs) FileContext() int64
func (args *CBFilterAfterSetEaEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetEaEventArgs) HandleContext() int64
func (args *CBFilterAfterSetEaEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetEaEventArgs) ResultCode() int32
func (args *CBFilterAfterSetEaEventArgs) SetResultCode(value int32)
// CBFilterAfterSetEaEvent defines the signature of the CBFilter AfterSetEa event's handler function.
type CBFilterAfterSetEaEvent func(sender *CBFilter, args *CBFilterAfterSetEaEventArgs)
func (obj *CBFilter) GetOnAfterSetEaHandler() CBFilterAfterSetEaEvent
func (obj *CBFilter) SetOnAfterSetEaHandler(handlerFunc CBFilterAfterSetEaEvent)
Remarks
This event fires after extended attributes are changed for the file specified by FileName.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetFileAttributes Event (CBFilter Component)
This event fires after a file or directory's attributes or times are changed.
Syntax
// CBFilterAfterSetFileAttributesEventArgs carries the CBFilter AfterSetFileAttributes event's parameters.
type CBFilterAfterSetFileAttributesEventArgs struct {...}
func (args *CBFilterAfterSetFileAttributesEventArgs) FileName() string
func (args *CBFilterAfterSetFileAttributesEventArgs) CreationTime() time.Time
func (args *CBFilterAfterSetFileAttributesEventArgs) LastAccessTime() time.Time
func (args *CBFilterAfterSetFileAttributesEventArgs) LastWriteTime() time.Time
func (args *CBFilterAfterSetFileAttributesEventArgs) ChangeTime() time.Time
func (args *CBFilterAfterSetFileAttributesEventArgs) Attributes() int32
func (args *CBFilterAfterSetFileAttributesEventArgs) Status() int32
func (args *CBFilterAfterSetFileAttributesEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetFileAttributesEventArgs) FileContext() int64
func (args *CBFilterAfterSetFileAttributesEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetFileAttributesEventArgs) HandleContext() int64
func (args *CBFilterAfterSetFileAttributesEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetFileAttributesEventArgs) ResultCode() int32
func (args *CBFilterAfterSetFileAttributesEventArgs) SetResultCode(value int32)
// CBFilterAfterSetFileAttributesEvent defines the signature of the CBFilter AfterSetFileAttributes event's handler function.
type CBFilterAfterSetFileAttributesEvent func(sender *CBFilter, args *CBFilterAfterSetFileAttributesEventArgs)
func (obj *CBFilter) GetOnAfterSetFileAttributesHandler() CBFilterAfterSetFileAttributesEvent
func (obj *CBFilter) SetOnAfterSetFileAttributesHandler(handlerFunc CBFilterAfterSetFileAttributesEvent)
Remarks
This event fires after the attributes or times of the file or directory specified by FileName are changed.
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 in UTC. A value of January 1, 1601 00:00:00 UTC 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetFileInfo Event (CBFilter Component)
This event fires after information about a file or directory is changed.
Syntax
// CBFilterAfterSetFileInfoEventArgs carries the CBFilter AfterSetFileInfo event's parameters.
type CBFilterAfterSetFileInfoEventArgs struct {...}
func (args *CBFilterAfterSetFileInfoEventArgs) FileName() string
func (args *CBFilterAfterSetFileInfoEventArgs) FileInformationClass() int32
func (args *CBFilterAfterSetFileInfoEventArgs) Buffer() []byte
func (args *CBFilterAfterSetFileInfoEventArgs) BufferLength() int32
func (args *CBFilterAfterSetFileInfoEventArgs) ValidBytes() int32
func (args *CBFilterAfterSetFileInfoEventArgs) Status() int32
func (args *CBFilterAfterSetFileInfoEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetFileInfoEventArgs) FileContext() int64
func (args *CBFilterAfterSetFileInfoEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetFileInfoEventArgs) HandleContext() int64
func (args *CBFilterAfterSetFileInfoEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetFileInfoEventArgs) ResultCode() int32
func (args *CBFilterAfterSetFileInfoEventArgs) SetResultCode(value int32)
// CBFilterAfterSetFileInfoEvent defines the signature of the CBFilter AfterSetFileInfo event's handler function.
type CBFilterAfterSetFileInfoEvent func(sender *CBFilter, args *CBFilterAfterSetFileInfoEventArgs)
func (obj *CBFilter) GetOnAfterSetFileInfoHandler() CBFilterAfterSetFileInfoEvent
func (obj *CBFilter) SetOnAfterSetFileInfoHandler(handlerFunc CBFilterAfterSetFileInfoEvent)
Remarks
This event fires after information about the file or directory specified by FileName is changed; 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetFileSecurity Event (CBFilter Component)
This event fires after a file or directory's security attributes are changed.
Syntax
// CBFilterAfterSetFileSecurityEventArgs carries the CBFilter AfterSetFileSecurity event's parameters.
type CBFilterAfterSetFileSecurityEventArgs struct {...}
func (args *CBFilterAfterSetFileSecurityEventArgs) FileName() string
func (args *CBFilterAfterSetFileSecurityEventArgs) SecurityInformation() int32
func (args *CBFilterAfterSetFileSecurityEventArgs) SecurityDescriptor() []byte
func (args *CBFilterAfterSetFileSecurityEventArgs) Length() int32
func (args *CBFilterAfterSetFileSecurityEventArgs) Status() int32
func (args *CBFilterAfterSetFileSecurityEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetFileSecurityEventArgs) FileContext() int64
func (args *CBFilterAfterSetFileSecurityEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetFileSecurityEventArgs) HandleContext() int64
func (args *CBFilterAfterSetFileSecurityEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetFileSecurityEventArgs) ResultCode() int32
func (args *CBFilterAfterSetFileSecurityEventArgs) SetResultCode(value int32)
// CBFilterAfterSetFileSecurityEvent defines the signature of the CBFilter AfterSetFileSecurity event's handler function.
type CBFilterAfterSetFileSecurityEvent func(sender *CBFilter, args *CBFilterAfterSetFileSecurityEventArgs)
func (obj *CBFilter) GetOnAfterSetFileSecurityHandler() CBFilterAfterSetFileSecurityEvent
func (obj *CBFilter) SetOnAfterSetFileSecurityHandler(handlerFunc CBFilterAfterSetFileSecurityEvent)
Remarks
This event fires after security attributes are changed for the file or directory specified by FileName.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetFileSize Event (CBFilter Component)
This event fires after a file is resized.
Syntax
// CBFilterAfterSetFileSizeEventArgs carries the CBFilter AfterSetFileSize event's parameters.
type CBFilterAfterSetFileSizeEventArgs struct {...}
func (args *CBFilterAfterSetFileSizeEventArgs) FileName() string
func (args *CBFilterAfterSetFileSizeEventArgs) Size() int64
func (args *CBFilterAfterSetFileSizeEventArgs) Status() int32
func (args *CBFilterAfterSetFileSizeEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetFileSizeEventArgs) FileContext() int64
func (args *CBFilterAfterSetFileSizeEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetFileSizeEventArgs) HandleContext() int64
func (args *CBFilterAfterSetFileSizeEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetFileSizeEventArgs) ResultCode() int32
func (args *CBFilterAfterSetFileSizeEventArgs) SetResultCode(value int32)
// CBFilterAfterSetFileSizeEvent defines the signature of the CBFilter AfterSetFileSize event's handler function.
type CBFilterAfterSetFileSizeEvent func(sender *CBFilter, args *CBFilterAfterSetFileSizeEventArgs)
func (obj *CBFilter) GetOnAfterSetFileSizeHandler() CBFilterAfterSetFileSizeEvent
func (obj *CBFilter) SetOnAfterSetFileSizeHandler(handlerFunc CBFilterAfterSetFileSizeEvent)
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).
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 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 nil.)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterSetReparsePoint Event (CBFilter Component)
This event fires after the OS creates or updates a reparse point on a file or directory.
Syntax
// CBFilterAfterSetReparsePointEventArgs carries the CBFilter AfterSetReparsePoint event's parameters.
type CBFilterAfterSetReparsePointEventArgs struct {...}
func (args *CBFilterAfterSetReparsePointEventArgs) FileName() string
func (args *CBFilterAfterSetReparsePointEventArgs) ReparseTag() int64
func (args *CBFilterAfterSetReparsePointEventArgs) ReparseBuffer() []byte
func (args *CBFilterAfterSetReparsePointEventArgs) BufferLength() int32
func (args *CBFilterAfterSetReparsePointEventArgs) DataLength() int32
func (args *CBFilterAfterSetReparsePointEventArgs) Status() int32
func (args *CBFilterAfterSetReparsePointEventArgs) SetStatus(value int32)
func (args *CBFilterAfterSetReparsePointEventArgs) FileContext() int64
func (args *CBFilterAfterSetReparsePointEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterSetReparsePointEventArgs) HandleContext() int64
func (args *CBFilterAfterSetReparsePointEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterSetReparsePointEventArgs) ResultCode() int32
func (args *CBFilterAfterSetReparsePointEventArgs) SetResultCode(value int32)
// CBFilterAfterSetReparsePointEvent defines the signature of the CBFilter AfterSetReparsePoint event's handler function.
type CBFilterAfterSetReparsePointEvent func(sender *CBFilter, args *CBFilterAfterSetReparsePointEventArgs)
func (obj *CBFilter) GetOnAfterSetReparsePointHandler() CBFilterAfterSetReparsePointEvent
func (obj *CBFilter) SetOnAfterSetReparsePointHandler(handlerFunc CBFilterAfterSetReparsePointEvent)
Remarks
This event fires after the OS creates or updates a reparse point on a file or directory specified by FileName.
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 component 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterUnlockAll Event (CBFilter Component)
This event fires after all locked byte ranges in a file are unlocked.
Syntax
// CBFilterAfterUnlockAllEventArgs carries the CBFilter AfterUnlockAll event's parameters.
type CBFilterAfterUnlockAllEventArgs struct {...}
func (args *CBFilterAfterUnlockAllEventArgs) FileName() string
func (args *CBFilterAfterUnlockAllEventArgs) Status() int32
func (args *CBFilterAfterUnlockAllEventArgs) SetStatus(value int32)
func (args *CBFilterAfterUnlockAllEventArgs) FileContext() int64
func (args *CBFilterAfterUnlockAllEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterUnlockAllEventArgs) HandleContext() int64
func (args *CBFilterAfterUnlockAllEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterUnlockAllEventArgs) ResultCode() int32
func (args *CBFilterAfterUnlockAllEventArgs) SetResultCode(value int32)
// CBFilterAfterUnlockAllEvent defines the signature of the CBFilter AfterUnlockAll event's handler function.
type CBFilterAfterUnlockAllEvent func(sender *CBFilter, args *CBFilterAfterUnlockAllEventArgs)
func (obj *CBFilter) GetOnAfterUnlockAllHandler() CBFilterAfterUnlockAllEvent
func (obj *CBFilter) SetOnAfterUnlockAllHandler(handlerFunc CBFilterAfterUnlockAllEvent)
Remarks
This event fires after all locked byte ranges in the file specified by FileName are unlocked.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterUnlockAllByKey Event (CBFilter Component)
This event fires after all locked byte ranges in a file, associated with a particular key, are unlocked.
Syntax
// CBFilterAfterUnlockAllByKeyEventArgs carries the CBFilter AfterUnlockAllByKey event's parameters.
type CBFilterAfterUnlockAllByKeyEventArgs struct {...}
func (args *CBFilterAfterUnlockAllByKeyEventArgs) FileName() string
func (args *CBFilterAfterUnlockAllByKeyEventArgs) Key() int64
func (args *CBFilterAfterUnlockAllByKeyEventArgs) Status() int32
func (args *CBFilterAfterUnlockAllByKeyEventArgs) SetStatus(value int32)
func (args *CBFilterAfterUnlockAllByKeyEventArgs) FileContext() int64
func (args *CBFilterAfterUnlockAllByKeyEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterUnlockAllByKeyEventArgs) HandleContext() int64
func (args *CBFilterAfterUnlockAllByKeyEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterUnlockAllByKeyEventArgs) ResultCode() int32
func (args *CBFilterAfterUnlockAllByKeyEventArgs) SetResultCode(value int32)
// CBFilterAfterUnlockAllByKeyEvent defines the signature of the CBFilter AfterUnlockAllByKey event's handler function.
type CBFilterAfterUnlockAllByKeyEvent func(sender *CBFilter, args *CBFilterAfterUnlockAllByKeyEventArgs)
func (obj *CBFilter) GetOnAfterUnlockAllByKeyHandler() CBFilterAfterUnlockAllByKeyEvent
func (obj *CBFilter) SetOnAfterUnlockAllByKeyHandler(handlerFunc CBFilterAfterUnlockAllByKeyEvent)
Remarks
This event fires after all locked byte ranges in the file specified by FileName, and associated with the specified Key, are unlocked.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterUnlockSingle Event (CBFilter Component)
This event fires after a particular locked byte range in a file is unlocked.
Syntax
// CBFilterAfterUnlockSingleEventArgs carries the CBFilter AfterUnlockSingle event's parameters.
type CBFilterAfterUnlockSingleEventArgs struct {...}
func (args *CBFilterAfterUnlockSingleEventArgs) FileName() string
func (args *CBFilterAfterUnlockSingleEventArgs) Offset() int64
func (args *CBFilterAfterUnlockSingleEventArgs) Length() int64
func (args *CBFilterAfterUnlockSingleEventArgs) Key() int64
func (args *CBFilterAfterUnlockSingleEventArgs) Status() int32
func (args *CBFilterAfterUnlockSingleEventArgs) SetStatus(value int32)
func (args *CBFilterAfterUnlockSingleEventArgs) FileContext() int64
func (args *CBFilterAfterUnlockSingleEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterUnlockSingleEventArgs) HandleContext() int64
func (args *CBFilterAfterUnlockSingleEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterUnlockSingleEventArgs) ResultCode() int32
func (args *CBFilterAfterUnlockSingleEventArgs) SetResultCode(value int32)
// CBFilterAfterUnlockSingleEvent defines the signature of the CBFilter AfterUnlockSingle event's handler function.
type CBFilterAfterUnlockSingleEvent func(sender *CBFilter, args *CBFilterAfterUnlockSingleEventArgs)
func (obj *CBFilter) GetOnAfterUnlockSingleHandler() CBFilterAfterUnlockSingleEvent
func (obj *CBFilter) SetOnAfterUnlockSingleHandler(handlerFunc CBFilterAfterUnlockSingleEvent)
Remarks
This event fires after a particular locked byte range in the file specified by FileName is unlocked.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
AfterWriteFile Event (CBFilter Component)
This event fires after data are written to a file.
Syntax
// CBFilterAfterWriteFileEventArgs carries the CBFilter AfterWriteFile event's parameters.
type CBFilterAfterWriteFileEventArgs struct {...}
func (args *CBFilterAfterWriteFileEventArgs) FileName() string
func (args *CBFilterAfterWriteFileEventArgs) Position() int64
func (args *CBFilterAfterWriteFileEventArgs) Buffer() []byte
func (args *CBFilterAfterWriteFileEventArgs) BufferLength() int32
func (args *CBFilterAfterWriteFileEventArgs) BytesToWrite() int32
func (args *CBFilterAfterWriteFileEventArgs) Direction() int32
func (args *CBFilterAfterWriteFileEventArgs) BytesWritten() int32
func (args *CBFilterAfterWriteFileEventArgs) SetBytesWritten(value int32)
func (args *CBFilterAfterWriteFileEventArgs) Status() int32
func (args *CBFilterAfterWriteFileEventArgs) SetStatus(value int32)
func (args *CBFilterAfterWriteFileEventArgs) FileContext() int64
func (args *CBFilterAfterWriteFileEventArgs) SetFileContext(value int64)
func (args *CBFilterAfterWriteFileEventArgs) HandleContext() int64
func (args *CBFilterAfterWriteFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterAfterWriteFileEventArgs) ResultCode() int32
func (args *CBFilterAfterWriteFileEventArgs) SetResultCode(value int32)
// CBFilterAfterWriteFileEvent defines the signature of the CBFilter AfterWriteFile event's handler function.
type CBFilterAfterWriteFileEvent func(sender *CBFilter, args *CBFilterAfterWriteFileEventArgs)
func (obj *CBFilter) GetOnAfterWriteFileHandler() CBFilterAfterWriteFileEvent
func (obj *CBFilter) SetOnAfterWriteFileHandler(handlerFunc CBFilterAfterWriteFileEvent)
Remarks
This event fires after data are written to the file specified by FileName.
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_NONCACHED | 0 | Operations performed in the user mode application <--> filesystem direction. |
| FS_REQUEST_DIR_USER_CACHED | 1 | Operations performed in the user mode application <--> system cache direction. |
| FS_REQUEST_DIR_SYSTEM_NONCACHED | 2 | Operations performed in the system cache <--> filesystem direction. |
| FS_REQUEST_DIR_SYSTEM_CACHED | 3 | Operations 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 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 nil.)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeCanFileBeDeleted Event (CBFilter Component)
This event fires before the OS attempts to mark a file or directory for deletion or remove such a mark.
Syntax
// CBFilterBeforeCanFileBeDeletedEventArgs carries the CBFilter BeforeCanFileBeDeleted event's parameters.
type CBFilterBeforeCanFileBeDeletedEventArgs struct {...}
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) FileName() string
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) RequestType() int32
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) CanDelete() bool
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) SetCanDelete(value bool)
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) FileContext() int64
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) HandleContext() int64
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) ResultCode() int32
func (args *CBFilterBeforeCanFileBeDeletedEventArgs) SetResultCode(value int32)
// CBFilterBeforeCanFileBeDeletedEvent defines the signature of the CBFilter BeforeCanFileBeDeleted event's handler function.
type CBFilterBeforeCanFileBeDeletedEvent func(sender *CBFilter, args *CBFilterBeforeCanFileBeDeletedEventArgs)
func (obj *CBFilter) GetOnBeforeCanFileBeDeletedHandler() CBFilterBeforeCanFileBeDeletedEvent
func (obj *CBFilter) SetOnBeforeCanFileBeDeletedHandler(handlerFunc CBFilterBeforeCanFileBeDeletedEvent)
Remarks
This event fires before the OS marks the file or directory specified by FileName for deletion or removes such a mark.
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_FLAG | 0x1 | The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag |
| DEL_REQ_SET_DISPOSITION | 0x2 | The 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.
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 nil.)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeCleanupFile Event (CBFilter Component)
This event fires before a file or directory handle is closed.
Syntax
// CBFilterBeforeCleanupFileEventArgs carries the CBFilter BeforeCleanupFile event's parameters.
type CBFilterBeforeCleanupFileEventArgs struct {...}
func (args *CBFilterBeforeCleanupFileEventArgs) FileName() string
func (args *CBFilterBeforeCleanupFileEventArgs) FileContext() int64
func (args *CBFilterBeforeCleanupFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeCleanupFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeCleanupFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeCleanupFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeCleanupFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeCleanupFileEvent defines the signature of the CBFilter BeforeCleanupFile event's handler function.
type CBFilterBeforeCleanupFileEvent func(sender *CBFilter, args *CBFilterBeforeCleanupFileEventArgs)
func (obj *CBFilter) GetOnBeforeCleanupFileHandler() CBFilterBeforeCleanupFileEvent
func (obj *CBFilter) SetOnBeforeCleanupFileHandler(handlerFunc CBFilterBeforeCleanupFileEvent)
Remarks
This event fires before a handle to the file or directory specified by FileName is closed. 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeCloseFile Event (CBFilter Component)
This event fires before a file or directory is closed.
Syntax
// CBFilterBeforeCloseFileEventArgs carries the CBFilter BeforeCloseFile event's parameters.
type CBFilterBeforeCloseFileEventArgs struct {...}
func (args *CBFilterBeforeCloseFileEventArgs) FileName() string
func (args *CBFilterBeforeCloseFileEventArgs) FileContext() int64
func (args *CBFilterBeforeCloseFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeCloseFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeCloseFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeCloseFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeCloseFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeCloseFileEvent defines the signature of the CBFilter BeforeCloseFile event's handler function.
type CBFilterBeforeCloseFileEvent func(sender *CBFilter, args *CBFilterBeforeCloseFileEventArgs)
func (obj *CBFilter) GetOnBeforeCloseFileHandler() CBFilterBeforeCloseFileEvent
func (obj *CBFilter) SetOnBeforeCloseFileHandler(handlerFunc CBFilterBeforeCloseFileEvent)
Remarks
This event fires before the file or directory specified by FileName is closed.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeCreateFile Event (CBFilter Component)
This event fires before a file or directory is created.
Syntax
// CBFilterBeforeCreateFileEventArgs carries the CBFilter BeforeCreateFile event's parameters.
type CBFilterBeforeCreateFileEventArgs struct {...}
func (args *CBFilterBeforeCreateFileEventArgs) FileName() string
func (args *CBFilterBeforeCreateFileEventArgs) ExistingAttributes() int32
func (args *CBFilterBeforeCreateFileEventArgs) Isolate() bool
func (args *CBFilterBeforeCreateFileEventArgs) SetIsolate(value bool)
func (args *CBFilterBeforeCreateFileEventArgs) BackendFileName() string
func (args *CBFilterBeforeCreateFileEventArgs) SetBackendFileName(value string)
func (args *CBFilterBeforeCreateFileEventArgs) DesiredAccess() int32
func (args *CBFilterBeforeCreateFileEventArgs) SetDesiredAccess(value int32)
func (args *CBFilterBeforeCreateFileEventArgs) Attributes() int32
func (args *CBFilterBeforeCreateFileEventArgs) SetAttributes(value int32)
func (args *CBFilterBeforeCreateFileEventArgs) ShareMode() int32
func (args *CBFilterBeforeCreateFileEventArgs) SetShareMode(value int32)
func (args *CBFilterBeforeCreateFileEventArgs) Options() int32
func (args *CBFilterBeforeCreateFileEventArgs) SetOptions(value int32)
func (args *CBFilterBeforeCreateFileEventArgs) CreateDisposition() int32
func (args *CBFilterBeforeCreateFileEventArgs) SetCreateDisposition(value int32)
func (args *CBFilterBeforeCreateFileEventArgs) SecurityDescriptor() []byte
func (args *CBFilterBeforeCreateFileEventArgs) SetSecurityDescriptor(value []byte)
func (args *CBFilterBeforeCreateFileEventArgs) Length() int32
func (args *CBFilterBeforeCreateFileEventArgs) FileContext() int64
func (args *CBFilterBeforeCreateFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeCreateFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeCreateFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeCreateFileEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeCreateFileEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeCreateFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeCreateFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeCreateFileEvent defines the signature of the CBFilter BeforeCreateFile event's handler function.
type CBFilterBeforeCreateFileEvent func(sender *CBFilter, args *CBFilterBeforeCreateFileEventArgs)
func (obj *CBFilter) GetOnBeforeCreateFileHandler() CBFilterBeforeCreateFileEvent
func (obj *CBFilter) SetOnBeforeCreateFileHandler(handlerFunc CBFilterBeforeCreateFileEvent)
Remarks
This event fires before the file or directory specified by FileName is created. Please refer to the File Create/Open Events topic for more information about how the component 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; this has the same effect as returning ACCESS_DENIED.
Requests may 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.
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.
Isolation-related functionality is under construction.
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_DIRECTORY | 0x00000001 | For a directory, the right to list the contents of the directory. |
| DESIRED_ACCESS_FILE_READ_DATA | 0x00000001 | For 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_FILE | 0x00000002 | For a directory, the right to create a file in the directory. |
| DESIRED_ACCESS_FILE_WRITE_DATA | 0x00000002 | For 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_SUBDIRECTORY | 0x00000004 | For a directory, the right to create a subdirectory. |
| DESIRED_ACCESS_FILE_APPEND_DATA | 0x00000004 | For 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_EA | 0x00000008 | The right to read extended file attributes. |
| DESIRED_ACCESS_FILE_WRITE_EA | 0x00000010 | The right to write extended file attributes. |
| DESIRED_ACCESS_FILE_EXECUTE | 0x00000020 | For 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_CHILD | 0x00000040 | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| DESIRED_ACCESS_FILE_READ_ATTRIBUTES | 0x00000080 | The right to read file attributes. |
| DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES | 0x00000100 | The right to write file attributes. |
| DESIRED_ACCESS_READ_CONTROL | 0x00020000 | 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_READ | 0x00020000 | Includes 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_WRITE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_SYNCHRONIZE | 0x00100000 | The 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_ACCESS | 0x001F01FF | All possible access rights for a file. |
| DESIRED_ACCESS_FILE_GENERIC_READ | 0x00120089 | A 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_WRITE | 0x00120116 | A 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_EXECUTE | 0x001200A0 | A 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_ONLY | 0x00000001 | The 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_HIDDEN | 0x00000002 | The file or directory is hidden.
The file is not included in an ordinary directory listing. |
| FILE_SYS_ATTR_SYSTEM | 0x00000004 | A file or directory that the operating system uses a part of, or uses exclusively. |
| FILE_SYS_ATTR_DIRECTORY | 0x00000010 | The entry is a directory. |
| FILE_SYS_ATTR_ARCHIVE | 0x00000020 | The entry is an archive file or directory.
Applications typically use this attribute to mark files for backup or removal. |
| FILE_SYS_ATTR_NORMAL | 0x00000080 | A file doesn't have other attributes set.
This attribute is valid only when used alone. |
| FILE_SYS_ATTR_TEMPORARY | 0x00000100 | A 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_FILE | 0x00000200 | A file that is a sparse file. |
| FILE_SYS_ATTR_REPARSE_POINT | 0x00000400 | A file that is a reparse point or a symbolic link. |
| FILE_SYS_ATTR_COMPRESSED | 0x00000800 | A 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_OFFLINE | 0x00001000 | The 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_INDEXED | 0x00002000 | The file or directory is not to be indexed by the content indexing service. |
| FILE_SYS_ATTR_ENCRYPTED | 0x00004000 | A 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_VIRTUAL | 0x00010000 | Reserved.
Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations. |
| FILE_SYS_ATTR_RECALL_ON_OPEN | 0x00040000 | The 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_NEW | 0x00000001 | Creates 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_ALWAYS | 0x00000002 | Creates 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_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens 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_EXISTING | 0x00000005 | Opens 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 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 component 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeCreateHardLink Event (CBFilter Component)
This event fires before a hard link is created.
Syntax
// CBFilterBeforeCreateHardLinkEventArgs carries the CBFilter BeforeCreateHardLink event's parameters.
type CBFilterBeforeCreateHardLinkEventArgs struct {...}
func (args *CBFilterBeforeCreateHardLinkEventArgs) FileName() string
func (args *CBFilterBeforeCreateHardLinkEventArgs) LinkName() string
func (args *CBFilterBeforeCreateHardLinkEventArgs) ReplaceIfExists() bool
func (args *CBFilterBeforeCreateHardLinkEventArgs) SetReplaceIfExists(value bool)
func (args *CBFilterBeforeCreateHardLinkEventArgs) FileContext() int64
func (args *CBFilterBeforeCreateHardLinkEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeCreateHardLinkEventArgs) HandleContext() int64
func (args *CBFilterBeforeCreateHardLinkEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeCreateHardLinkEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeCreateHardLinkEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeCreateHardLinkEventArgs) ResultCode() int32
func (args *CBFilterBeforeCreateHardLinkEventArgs) SetResultCode(value int32)
// CBFilterBeforeCreateHardLinkEvent defines the signature of the CBFilter BeforeCreateHardLink event's handler function.
type CBFilterBeforeCreateHardLinkEvent func(sender *CBFilter, args *CBFilterBeforeCreateHardLinkEventArgs)
func (obj *CBFilter) GetOnBeforeCreateHardLinkHandler() CBFilterBeforeCreateHardLinkEvent
func (obj *CBFilter) SetOnBeforeCreateHardLinkHandler(handlerFunc CBFilterBeforeCreateHardLinkEvent)
Remarks
This event fires before a hard link to the file specified by FileName is created. 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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeDeleteFile Event (CBFilter Component)
This event fires before a file or directory is deleted.
Syntax
// CBFilterBeforeDeleteFileEventArgs carries the CBFilter BeforeDeleteFile event's parameters.
type CBFilterBeforeDeleteFileEventArgs struct {...}
func (args *CBFilterBeforeDeleteFileEventArgs) FileName() string
func (args *CBFilterBeforeDeleteFileEventArgs) RequestType() int32
func (args *CBFilterBeforeDeleteFileEventArgs) FileContext() int64
func (args *CBFilterBeforeDeleteFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeDeleteFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeDeleteFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeDeleteFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeDeleteFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeDeleteFileEvent defines the signature of the CBFilter BeforeDeleteFile event's handler function.
type CBFilterBeforeDeleteFileEvent func(sender *CBFilter, args *CBFilterBeforeDeleteFileEventArgs)
func (obj *CBFilter) GetOnBeforeDeleteFileHandler() CBFilterBeforeDeleteFileEvent
func (obj *CBFilter) SetOnBeforeDeleteFileHandler(handlerFunc CBFilterBeforeDeleteFileEvent)
Remarks
This event fires before the file or directory specified by FileName is deleted. 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_FLAG | 0x1 | The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag |
| DEL_REQ_SET_DISPOSITION | 0x2 | The 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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeDeleteReparsePoint Event (CBFilter Component)
This event fires when the OS wants to delete a reparse point from a file or directory.
Syntax
// CBFilterBeforeDeleteReparsePointEventArgs carries the CBFilter BeforeDeleteReparsePoint event's parameters.
type CBFilterBeforeDeleteReparsePointEventArgs struct {...}
func (args *CBFilterBeforeDeleteReparsePointEventArgs) FileName() string
func (args *CBFilterBeforeDeleteReparsePointEventArgs) ReparseBuffer() []byte
func (args *CBFilterBeforeDeleteReparsePointEventArgs) BufferLength() int32
func (args *CBFilterBeforeDeleteReparsePointEventArgs) FileContext() int64
func (args *CBFilterBeforeDeleteReparsePointEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeDeleteReparsePointEventArgs) HandleContext() int64
func (args *CBFilterBeforeDeleteReparsePointEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeDeleteReparsePointEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeDeleteReparsePointEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeDeleteReparsePointEventArgs) ResultCode() int32
func (args *CBFilterBeforeDeleteReparsePointEventArgs) SetResultCode(value int32)
// CBFilterBeforeDeleteReparsePointEvent defines the signature of the CBFilter BeforeDeleteReparsePoint event's handler function.
type CBFilterBeforeDeleteReparsePointEvent func(sender *CBFilter, args *CBFilterBeforeDeleteReparsePointEventArgs)
func (obj *CBFilter) GetOnBeforeDeleteReparsePointHandler() CBFilterBeforeDeleteReparsePointEvent
func (obj *CBFilter) SetOnBeforeDeleteReparsePointHandler(handlerFunc CBFilterBeforeDeleteReparsePointEvent)
Remarks
This event fires before the OS deletes a reparse point from a file or directory specified by FileName.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeEnumerateDirectory Event (CBFilter Component)
This event fires when an enumeration request is sent by the OS.
Syntax
// CBFilterBeforeEnumerateDirectoryEventArgs carries the CBFilter BeforeEnumerateDirectory event's parameters.
type CBFilterBeforeEnumerateDirectoryEventArgs struct {...}
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) DirectoryName() string
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) Flags() int32
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) Mask() string
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) Index() int32
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) DirectoryContext() int64
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) SetDirectoryContext(value int64)
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) HandleContext() int64
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) EnumerationContext() int64
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) SetEnumerationContext(value int64)
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) ResultCode() int32
func (args *CBFilterBeforeEnumerateDirectoryEventArgs) SetResultCode(value int32)
// CBFilterBeforeEnumerateDirectoryEvent defines the signature of the CBFilter BeforeEnumerateDirectory event's handler function.
type CBFilterBeforeEnumerateDirectoryEvent func(sender *CBFilter, args *CBFilterBeforeEnumerateDirectoryEventArgs)
func (obj *CBFilter) GetOnBeforeEnumerateDirectoryHandler() CBFilterBeforeEnumerateDirectoryEvent
func (obj *CBFilter) SetOnBeforeEnumerateDirectoryHandler(handlerFunc CBFilterBeforeEnumerateDirectoryEvent)
Remarks
This event fires when the OS sends a request for reading one or more entries of the directory specified by DirectoryName.
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_SCAN | 1 | The requestor specified that directory enumeration must be restarted. |
| FS_ENUM_RETURN_SINGLE_ENTRY | 2 | One entry should be returned. |
| FS_ENUM_INDEX_SPECIFIED | 4 | The 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 filename characters and wildcards (the * and ? characters). Alternatively, it may be an exact filename (i.e., a value without any wildcards), as some applications query file information by specifying an exact filename 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeFilterAttachToVolume Event (CBFilter Component)
This event fires before the filter attaches to a newly mounted filesystem volume.
Syntax
// CBFilterBeforeFilterAttachToVolumeEventArgs carries the CBFilter BeforeFilterAttachToVolume event's parameters.
type CBFilterBeforeFilterAttachToVolumeEventArgs struct {...}
func (args *CBFilterBeforeFilterAttachToVolumeEventArgs) VolumeName() string
func (args *CBFilterBeforeFilterAttachToVolumeEventArgs) SkipVolume() bool
func (args *CBFilterBeforeFilterAttachToVolumeEventArgs) SetSkipVolume(value bool)
func (args *CBFilterBeforeFilterAttachToVolumeEventArgs) ResultCode() int32
func (args *CBFilterBeforeFilterAttachToVolumeEventArgs) SetResultCode(value int32)
// CBFilterBeforeFilterAttachToVolumeEvent defines the signature of the CBFilter BeforeFilterAttachToVolume event's handler function.
type CBFilterBeforeFilterAttachToVolumeEvent func(sender *CBFilter, args *CBFilterBeforeFilterAttachToVolumeEventArgs)
func (obj *CBFilter) GetOnBeforeFilterAttachToVolumeHandler() CBFilterBeforeFilterAttachToVolumeEvent
func (obj *CBFilter) SetOnBeforeFilterAttachToVolumeHandler(handlerFunc CBFilterBeforeFilterAttachToVolumeEvent)
Remarks
This event fires before the filter attaches to the newly mounted filesystem volume specified by 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.
The VolumeName parameter's value is always an NT native format in this event (unlike the other volume-related events, listed below, where its format depends on the ResolveNtDeviceToDriveLetter configuration setting). It is therefore recommended that applications add volume-specific rules, if desired, during the AfterFilterAttachToVolume event rather than this one. 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 component'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 component's system driver. It also will prevent any of the following events from firing for the volume:
- AfterFilterAttachToVolume
- NotifyFilterAttachToVolume
- AfterFilterDetachFromVolume
- NotifyFilterDetachFromVolume
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 Reporting and 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 Component)
This event fires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
Syntax
// CBFilterBeforeFsctlEventArgs carries the CBFilter BeforeFsctl event's parameters.
type CBFilterBeforeFsctlEventArgs struct {...}
func (args *CBFilterBeforeFsctlEventArgs) FileName() string
func (args *CBFilterBeforeFsctlEventArgs) FsControlCode() int32
func (args *CBFilterBeforeFsctlEventArgs) InBuffer() []byte
func (args *CBFilterBeforeFsctlEventArgs) InBufferLength() int32
func (args *CBFilterBeforeFsctlEventArgs) InBufferValidBytes() int32
func (args *CBFilterBeforeFsctlEventArgs) SetInBufferValidBytes(value int32)
func (args *CBFilterBeforeFsctlEventArgs) OutBuffer() []byte
func (args *CBFilterBeforeFsctlEventArgs) SetOutBuffer(value []byte)
func (args *CBFilterBeforeFsctlEventArgs) OutBufferLength() int32
func (args *CBFilterBeforeFsctlEventArgs) OutBufferValidBytes() int32
func (args *CBFilterBeforeFsctlEventArgs) SetOutBufferValidBytes(value int32)
func (args *CBFilterBeforeFsctlEventArgs) FileContext() int64
func (args *CBFilterBeforeFsctlEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeFsctlEventArgs) HandleContext() int64
func (args *CBFilterBeforeFsctlEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeFsctlEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeFsctlEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeFsctlEventArgs) ResultCode() int32
func (args *CBFilterBeforeFsctlEventArgs) SetResultCode(value int32)
// CBFilterBeforeFsctlEvent defines the signature of the CBFilter BeforeFsctl event's handler function.
type CBFilterBeforeFsctlEvent func(sender *CBFilter, args *CBFilterBeforeFsctlEventArgs)
func (obj *CBFilter) GetOnBeforeFsctlHandler() CBFilterBeforeFsctlEvent
func (obj *CBFilter) SetOnBeforeFsctlHandler(handlerFunc CBFilterBeforeFsctlEvent)
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:
- Copy no more than InBufferLength bytes into InBuffer.
- 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:
- Copy no more than OutBufferLength bytes into OutBuffer.
- Update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.
- 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_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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeGetFileSecurity Event (CBFilter Component)
This event fires before a file or directory's security attributes are retrieved.
Syntax
// CBFilterBeforeGetFileSecurityEventArgs carries the CBFilter BeforeGetFileSecurity event's parameters.
type CBFilterBeforeGetFileSecurityEventArgs struct {...}
func (args *CBFilterBeforeGetFileSecurityEventArgs) FileName() string
func (args *CBFilterBeforeGetFileSecurityEventArgs) SecurityInformation() int32
func (args *CBFilterBeforeGetFileSecurityEventArgs) SecurityDescriptor() []byte
func (args *CBFilterBeforeGetFileSecurityEventArgs) SetSecurityDescriptor(value []byte)
func (args *CBFilterBeforeGetFileSecurityEventArgs) Length() int32
func (args *CBFilterBeforeGetFileSecurityEventArgs) LengthNeeded() int32
func (args *CBFilterBeforeGetFileSecurityEventArgs) SetLengthNeeded(value int32)
func (args *CBFilterBeforeGetFileSecurityEventArgs) FileContext() int64
func (args *CBFilterBeforeGetFileSecurityEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeGetFileSecurityEventArgs) HandleContext() int64
func (args *CBFilterBeforeGetFileSecurityEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeGetFileSecurityEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeGetFileSecurityEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeGetFileSecurityEventArgs) ResultCode() int32
func (args *CBFilterBeforeGetFileSecurityEventArgs) SetResultCode(value int32)
// CBFilterBeforeGetFileSecurityEvent defines the signature of the CBFilter BeforeGetFileSecurity event's handler function.
type CBFilterBeforeGetFileSecurityEvent func(sender *CBFilter, args *CBFilterBeforeGetFileSecurityEventArgs)
func (obj *CBFilter) GetOnBeforeGetFileSecurityHandler() CBFilterBeforeGetFileSecurityEvent
func (obj *CBFilter) SetOnBeforeGetFileSecurityHandler(handlerFunc CBFilterBeforeGetFileSecurityEvent)
Remarks
This event fires before security attributes are retrieved for the file or directory specified by FileName.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeGetReparsePoint Event (CBFilter Component)
This event fires when the OS wants to read a reparse point for a file or directory.
Syntax
// CBFilterBeforeGetReparsePointEventArgs carries the CBFilter BeforeGetReparsePoint event's parameters.
type CBFilterBeforeGetReparsePointEventArgs struct {...}
func (args *CBFilterBeforeGetReparsePointEventArgs) FileName() string
func (args *CBFilterBeforeGetReparsePointEventArgs) ReparseBuffer() []byte
func (args *CBFilterBeforeGetReparsePointEventArgs) SetReparseBuffer(value []byte)
func (args *CBFilterBeforeGetReparsePointEventArgs) ReparseBufferLength() int32
func (args *CBFilterBeforeGetReparsePointEventArgs) SetReparseBufferLength(value int32)
func (args *CBFilterBeforeGetReparsePointEventArgs) FileContext() int64
func (args *CBFilterBeforeGetReparsePointEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeGetReparsePointEventArgs) HandleContext() int64
func (args *CBFilterBeforeGetReparsePointEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeGetReparsePointEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeGetReparsePointEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeGetReparsePointEventArgs) ResultCode() int32
func (args *CBFilterBeforeGetReparsePointEventArgs) SetResultCode(value int32)
// CBFilterBeforeGetReparsePointEvent defines the signature of the CBFilter BeforeGetReparsePoint event's handler function.
type CBFilterBeforeGetReparsePointEvent func(sender *CBFilter, args *CBFilterBeforeGetReparsePointEventArgs)
func (obj *CBFilter) GetOnBeforeGetReparsePointHandler() CBFilterBeforeGetReparsePointEvent
func (obj *CBFilter) SetOnBeforeGetReparsePointHandler(handlerFunc CBFilterBeforeGetReparsePointEvent)
Remarks
This event fires when the OS wants to read a reparse point for the file or directory specified by FileName.
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 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 nil.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeIoctl Event (CBFilter Component)
This event fires before an IRP_MJ_DEVICE_CONTROL request is processed.
Syntax
// CBFilterBeforeIoctlEventArgs carries the CBFilter BeforeIoctl event's parameters.
type CBFilterBeforeIoctlEventArgs struct {...}
func (args *CBFilterBeforeIoctlEventArgs) FileName() string
func (args *CBFilterBeforeIoctlEventArgs) IoControlCode() int32
func (args *CBFilterBeforeIoctlEventArgs) InBuffer() []byte
func (args *CBFilterBeforeIoctlEventArgs) InBufferLength() int32
func (args *CBFilterBeforeIoctlEventArgs) InBufferValidBytes() int32
func (args *CBFilterBeforeIoctlEventArgs) SetInBufferValidBytes(value int32)
func (args *CBFilterBeforeIoctlEventArgs) OutBuffer() []byte
func (args *CBFilterBeforeIoctlEventArgs) SetOutBuffer(value []byte)
func (args *CBFilterBeforeIoctlEventArgs) OutBufferLength() int32
func (args *CBFilterBeforeIoctlEventArgs) OutBufferValidBytes() int32
func (args *CBFilterBeforeIoctlEventArgs) SetOutBufferValidBytes(value int32)
func (args *CBFilterBeforeIoctlEventArgs) FileContext() int64
func (args *CBFilterBeforeIoctlEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeIoctlEventArgs) HandleContext() int64
func (args *CBFilterBeforeIoctlEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeIoctlEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeIoctlEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeIoctlEventArgs) ResultCode() int32
func (args *CBFilterBeforeIoctlEventArgs) SetResultCode(value int32)
// CBFilterBeforeIoctlEvent defines the signature of the CBFilter BeforeIoctl event's handler function.
type CBFilterBeforeIoctlEvent func(sender *CBFilter, args *CBFilterBeforeIoctlEventArgs)
func (obj *CBFilter) GetOnBeforeIoctlHandler() CBFilterBeforeIoctlEvent
func (obj *CBFilter) SetOnBeforeIoctlHandler(handlerFunc CBFilterBeforeIoctlEvent)
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:
- Copy no more than InBufferLength bytes into InBuffer.
- 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:
- Copy no more than OutBufferLength bytes into OutBuffer.
- Update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.
- 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_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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeLock Event (CBFilter Component)
This event fires before a range of bytes in a file is locked.
Syntax
// CBFilterBeforeLockEventArgs carries the CBFilter BeforeLock event's parameters.
type CBFilterBeforeLockEventArgs struct {...}
func (args *CBFilterBeforeLockEventArgs) FileName() string
func (args *CBFilterBeforeLockEventArgs) Offset() int64
func (args *CBFilterBeforeLockEventArgs) SetOffset(value int64)
func (args *CBFilterBeforeLockEventArgs) Length() int64
func (args *CBFilterBeforeLockEventArgs) SetLength(value int64)
func (args *CBFilterBeforeLockEventArgs) Key() int64
func (args *CBFilterBeforeLockEventArgs) FailImmediately() bool
func (args *CBFilterBeforeLockEventArgs) SetFailImmediately(value bool)
func (args *CBFilterBeforeLockEventArgs) ExclusiveLock() bool
func (args *CBFilterBeforeLockEventArgs) SetExclusiveLock(value bool)
func (args *CBFilterBeforeLockEventArgs) FileContext() int64
func (args *CBFilterBeforeLockEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeLockEventArgs) HandleContext() int64
func (args *CBFilterBeforeLockEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeLockEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeLockEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeLockEventArgs) ResultCode() int32
func (args *CBFilterBeforeLockEventArgs) SetResultCode(value int32)
// CBFilterBeforeLockEvent defines the signature of the CBFilter BeforeLock event's handler function.
type CBFilterBeforeLockEvent func(sender *CBFilter, args *CBFilterBeforeLockEventArgs)
func (obj *CBFilter) GetOnBeforeLockHandler() CBFilterBeforeLockEvent
func (obj *CBFilter) SetOnBeforeLockHandler(handlerFunc CBFilterBeforeLockEvent)
Remarks
This event fires before a range of bytes in the file specified by FileName is locked; 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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeOpenFile Event (CBFilter Component)
This event fires before a file or directory is opened.
Syntax
// CBFilterBeforeOpenFileEventArgs carries the CBFilter BeforeOpenFile event's parameters.
type CBFilterBeforeOpenFileEventArgs struct {...}
func (args *CBFilterBeforeOpenFileEventArgs) FileName() string
func (args *CBFilterBeforeOpenFileEventArgs) ExistingAttributes() int32
func (args *CBFilterBeforeOpenFileEventArgs) Isolate() bool
func (args *CBFilterBeforeOpenFileEventArgs) SetIsolate(value bool)
func (args *CBFilterBeforeOpenFileEventArgs) BackendFileName() string
func (args *CBFilterBeforeOpenFileEventArgs) SetBackendFileName(value string)
func (args *CBFilterBeforeOpenFileEventArgs) DesiredAccess() int32
func (args *CBFilterBeforeOpenFileEventArgs) SetDesiredAccess(value int32)
func (args *CBFilterBeforeOpenFileEventArgs) Attributes() int32
func (args *CBFilterBeforeOpenFileEventArgs) SetAttributes(value int32)
func (args *CBFilterBeforeOpenFileEventArgs) ShareMode() int32
func (args *CBFilterBeforeOpenFileEventArgs) SetShareMode(value int32)
func (args *CBFilterBeforeOpenFileEventArgs) Options() int32
func (args *CBFilterBeforeOpenFileEventArgs) SetOptions(value int32)
func (args *CBFilterBeforeOpenFileEventArgs) CreateDisposition() int32
func (args *CBFilterBeforeOpenFileEventArgs) SetCreateDisposition(value int32)
func (args *CBFilterBeforeOpenFileEventArgs) SecurityDescriptor() []byte
func (args *CBFilterBeforeOpenFileEventArgs) SetSecurityDescriptor(value []byte)
func (args *CBFilterBeforeOpenFileEventArgs) Length() int32
func (args *CBFilterBeforeOpenFileEventArgs) FileContext() int64
func (args *CBFilterBeforeOpenFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeOpenFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeOpenFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeOpenFileEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeOpenFileEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeOpenFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeOpenFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeOpenFileEvent defines the signature of the CBFilter BeforeOpenFile event's handler function.
type CBFilterBeforeOpenFileEvent func(sender *CBFilter, args *CBFilterBeforeOpenFileEventArgs)
func (obj *CBFilter) GetOnBeforeOpenFileHandler() CBFilterBeforeOpenFileEvent
func (obj *CBFilter) SetOnBeforeOpenFileHandler(handlerFunc CBFilterBeforeOpenFileEvent)
Remarks
This event fires before the file or directory specified by FileName is opened. Please refer to the File Create/Open Events topic for more information about how the component 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; this has the same effect as returning ACCESS_DENIED.
Requests may 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.
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.
Isolation-related functionality is under construction.
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_DIRECTORY | 0x00000001 | For a directory, the right to list the contents of the directory. |
| DESIRED_ACCESS_FILE_READ_DATA | 0x00000001 | For 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_FILE | 0x00000002 | For a directory, the right to create a file in the directory. |
| DESIRED_ACCESS_FILE_WRITE_DATA | 0x00000002 | For 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_SUBDIRECTORY | 0x00000004 | For a directory, the right to create a subdirectory. |
| DESIRED_ACCESS_FILE_APPEND_DATA | 0x00000004 | For 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_EA | 0x00000008 | The right to read extended file attributes. |
| DESIRED_ACCESS_FILE_WRITE_EA | 0x00000010 | The right to write extended file attributes. |
| DESIRED_ACCESS_FILE_EXECUTE | 0x00000020 | For 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_CHILD | 0x00000040 | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| DESIRED_ACCESS_FILE_READ_ATTRIBUTES | 0x00000080 | The right to read file attributes. |
| DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES | 0x00000100 | The right to write file attributes. |
| DESIRED_ACCESS_READ_CONTROL | 0x00020000 | 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_READ | 0x00020000 | Includes 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_WRITE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_SYNCHRONIZE | 0x00100000 | The 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_ACCESS | 0x001F01FF | All possible access rights for a file. |
| DESIRED_ACCESS_FILE_GENERIC_READ | 0x00120089 | A 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_WRITE | 0x00120116 | A 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_EXECUTE | 0x001200A0 | A 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_ONLY | 0x00000001 | The 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_HIDDEN | 0x00000002 | The file or directory is hidden.
The file is not included in an ordinary directory listing. |
| FILE_SYS_ATTR_SYSTEM | 0x00000004 | A file or directory that the operating system uses a part of, or uses exclusively. |
| FILE_SYS_ATTR_DIRECTORY | 0x00000010 | The entry is a directory. |
| FILE_SYS_ATTR_ARCHIVE | 0x00000020 | The entry is an archive file or directory.
Applications typically use this attribute to mark files for backup or removal. |
| FILE_SYS_ATTR_NORMAL | 0x00000080 | A file doesn't have other attributes set.
This attribute is valid only when used alone. |
| FILE_SYS_ATTR_TEMPORARY | 0x00000100 | A 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_FILE | 0x00000200 | A file that is a sparse file. |
| FILE_SYS_ATTR_REPARSE_POINT | 0x00000400 | A file that is a reparse point or a symbolic link. |
| FILE_SYS_ATTR_COMPRESSED | 0x00000800 | A 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_OFFLINE | 0x00001000 | The 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_INDEXED | 0x00002000 | The file or directory is not to be indexed by the content indexing service. |
| FILE_SYS_ATTR_ENCRYPTED | 0x00004000 | A 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_VIRTUAL | 0x00010000 | Reserved.
Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations. |
| FILE_SYS_ATTR_RECALL_ON_OPEN | 0x00040000 | The 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_NEW | 0x00000001 | Creates 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_ALWAYS | 0x00000002 | Creates 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_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens 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_EXISTING | 0x00000005 | Opens 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 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 component 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeQueryEa Event (CBFilter Component)
This event fires before information about extended attributes of a file is retrieved.
Syntax
// CBFilterBeforeQueryEaEventArgs carries the CBFilter BeforeQueryEa event's parameters.
type CBFilterBeforeQueryEaEventArgs struct {...}
func (args *CBFilterBeforeQueryEaEventArgs) FileName() string
func (args *CBFilterBeforeQueryEaEventArgs) Buffer() []byte
func (args *CBFilterBeforeQueryEaEventArgs) SetBuffer(value []byte)
func (args *CBFilterBeforeQueryEaEventArgs) BufferLength() int32
func (args *CBFilterBeforeQueryEaEventArgs) ReturnSingleEntry() bool
func (args *CBFilterBeforeQueryEaEventArgs) SetReturnSingleEntry(value bool)
func (args *CBFilterBeforeQueryEaEventArgs) EaList() []byte
func (args *CBFilterBeforeQueryEaEventArgs) SetEaList(value []byte)
func (args *CBFilterBeforeQueryEaEventArgs) EaListLength() int32
func (args *CBFilterBeforeQueryEaEventArgs) SetEaListLength(value int32)
func (args *CBFilterBeforeQueryEaEventArgs) EaIndex() int32
func (args *CBFilterBeforeQueryEaEventArgs) SetEaIndex(value int32)
func (args *CBFilterBeforeQueryEaEventArgs) RestartScan() bool
func (args *CBFilterBeforeQueryEaEventArgs) SetRestartScan(value bool)
func (args *CBFilterBeforeQueryEaEventArgs) LengthReturned() int32
func (args *CBFilterBeforeQueryEaEventArgs) SetLengthReturned(value int32)
func (args *CBFilterBeforeQueryEaEventArgs) FileContext() int64
func (args *CBFilterBeforeQueryEaEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeQueryEaEventArgs) HandleContext() int64
func (args *CBFilterBeforeQueryEaEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeQueryEaEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeQueryEaEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeQueryEaEventArgs) ResultCode() int32
func (args *CBFilterBeforeQueryEaEventArgs) SetResultCode(value int32)
// CBFilterBeforeQueryEaEvent defines the signature of the CBFilter BeforeQueryEa event's handler function.
type CBFilterBeforeQueryEaEvent func(sender *CBFilter, args *CBFilterBeforeQueryEaEventArgs)
func (obj *CBFilter) GetOnBeforeQueryEaHandler() CBFilterBeforeQueryEaEvent
func (obj *CBFilter) SetOnBeforeQueryEaHandler(handlerFunc CBFilterBeforeQueryEaEvent)
Remarks
This event fires before information about extended attributes of the file specified by FileName is retrieved using the FltQueryEaFile function of the system API.
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 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. 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 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.
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:
- Copy no more than BufferLength bytes into Buffer.
- Update the LengthReturned parameter's value afterward so that it correctly reflects the amount of data in Buffer.
- 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeQueryFileInfo Event (CBFilter Component)
This event fires before information about a file or directory is retrieved.
Syntax
// CBFilterBeforeQueryFileInfoEventArgs carries the CBFilter BeforeQueryFileInfo event's parameters.
type CBFilterBeforeQueryFileInfoEventArgs struct {...}
func (args *CBFilterBeforeQueryFileInfoEventArgs) FileName() string
func (args *CBFilterBeforeQueryFileInfoEventArgs) FileInformationClass() int32
func (args *CBFilterBeforeQueryFileInfoEventArgs) Buffer() []byte
func (args *CBFilterBeforeQueryFileInfoEventArgs) SetBuffer(value []byte)
func (args *CBFilterBeforeQueryFileInfoEventArgs) BufferLength() int32
func (args *CBFilterBeforeQueryFileInfoEventArgs) ValidBytes() int32
func (args *CBFilterBeforeQueryFileInfoEventArgs) SetValidBytes(value int32)
func (args *CBFilterBeforeQueryFileInfoEventArgs) FileContext() int64
func (args *CBFilterBeforeQueryFileInfoEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeQueryFileInfoEventArgs) HandleContext() int64
func (args *CBFilterBeforeQueryFileInfoEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeQueryFileInfoEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeQueryFileInfoEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeQueryFileInfoEventArgs) ResultCode() int32
func (args *CBFilterBeforeQueryFileInfoEventArgs) SetResultCode(value int32)
// CBFilterBeforeQueryFileInfoEvent defines the signature of the CBFilter BeforeQueryFileInfo event's handler function.
type CBFilterBeforeQueryFileInfoEvent func(sender *CBFilter, args *CBFilterBeforeQueryFileInfoEventArgs)
func (obj *CBFilter) GetOnBeforeQueryFileInfoHandler() CBFilterBeforeQueryFileInfoEvent
func (obj *CBFilter) SetOnBeforeQueryFileInfoHandler(handlerFunc CBFilterBeforeQueryFileInfoEvent)
Remarks
This event fires before information about the file or directory specified by FileName is retrieved; 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 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.
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:
- Copy no more than BufferLength bytes into Buffer.
- Update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.
- 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeReadFile Event (CBFilter Component)
This event fires before data are read from a file.
Syntax
// CBFilterBeforeReadFileEventArgs carries the CBFilter BeforeReadFile event's parameters.
type CBFilterBeforeReadFileEventArgs struct {...}
func (args *CBFilterBeforeReadFileEventArgs) FileName() string
func (args *CBFilterBeforeReadFileEventArgs) Position() int64
func (args *CBFilterBeforeReadFileEventArgs) SetPosition(value int64)
func (args *CBFilterBeforeReadFileEventArgs) Buffer() []byte
func (args *CBFilterBeforeReadFileEventArgs) SetBuffer(value []byte)
func (args *CBFilterBeforeReadFileEventArgs) BufferLength() int32
func (args *CBFilterBeforeReadFileEventArgs) BytesToRead() int32
func (args *CBFilterBeforeReadFileEventArgs) SetBytesToRead(value int32)
func (args *CBFilterBeforeReadFileEventArgs) Reserved() int32
func (args *CBFilterBeforeReadFileEventArgs) SetReserved(value int32)
func (args *CBFilterBeforeReadFileEventArgs) Direction() int32
func (args *CBFilterBeforeReadFileEventArgs) FileContext() int64
func (args *CBFilterBeforeReadFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeReadFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeReadFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeReadFileEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeReadFileEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeReadFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeReadFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeReadFileEvent defines the signature of the CBFilter BeforeReadFile event's handler function.
type CBFilterBeforeReadFileEvent func(sender *CBFilter, args *CBFilterBeforeReadFileEventArgs)
func (obj *CBFilter) GetOnBeforeReadFileHandler() CBFilterBeforeReadFileEvent
func (obj *CBFilter) SetOnBeforeReadFileHandler(handlerFunc CBFilterBeforeReadFileEvent)
Remarks
This event fires before data are read from the file specified by FileName.
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:
- Enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires).
- Copy no more than BufferLength bytes into Buffer.
- Update the BytesToRead parameter's value afterward so that it correctly reflects the amount of data in Buffer.
- 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_NONCACHED | 0 | Operations performed in the user mode application <--> filesystem direction. |
| FS_REQUEST_DIR_USER_CACHED | 1 | Operations performed in the user mode application <--> system cache direction. |
| FS_REQUEST_DIR_SYSTEM_NONCACHED | 2 | Operations performed in the system cache <--> filesystem direction. |
| FS_REQUEST_DIR_SYSTEM_CACHED | 3 | Operations performed in the system component <--> system cache direction. |
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 nil.)
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeRenameOrMoveFile Event (CBFilter Component)
This event fires before a file or directory is renamed or moved.
Syntax
// CBFilterBeforeRenameOrMoveFileEventArgs carries the CBFilter BeforeRenameOrMoveFile event's parameters.
type CBFilterBeforeRenameOrMoveFileEventArgs struct {...}
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) FileName() string
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) NewFileName() string
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) ReplaceIfExists() bool
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) SetReplaceIfExists(value bool)
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) FileContext() int64
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeRenameOrMoveFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeRenameOrMoveFileEvent defines the signature of the CBFilter BeforeRenameOrMoveFile event's handler function.
type CBFilterBeforeRenameOrMoveFileEvent func(sender *CBFilter, args *CBFilterBeforeRenameOrMoveFileEventArgs)
func (obj *CBFilter) GetOnBeforeRenameOrMoveFileHandler() CBFilterBeforeRenameOrMoveFileEvent
func (obj *CBFilter) SetOnBeforeRenameOrMoveFileHandler(handlerFunc CBFilterBeforeRenameOrMoveFileEvent)
Remarks
This event fires before the file or directory specified by FileName is renamed or moved to NewFileName.
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 filenames, 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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetAllocationSize Event (CBFilter Component)
This event fires before a file's allocation size is changed.
Syntax
// CBFilterBeforeSetAllocationSizeEventArgs carries the CBFilter BeforeSetAllocationSize event's parameters.
type CBFilterBeforeSetAllocationSizeEventArgs struct {...}
func (args *CBFilterBeforeSetAllocationSizeEventArgs) FileName() string
func (args *CBFilterBeforeSetAllocationSizeEventArgs) AllocationSize() int64
func (args *CBFilterBeforeSetAllocationSizeEventArgs) SetAllocationSize(value int64)
func (args *CBFilterBeforeSetAllocationSizeEventArgs) FileContext() int64
func (args *CBFilterBeforeSetAllocationSizeEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetAllocationSizeEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetAllocationSizeEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetAllocationSizeEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetAllocationSizeEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetAllocationSizeEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetAllocationSizeEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetAllocationSizeEvent defines the signature of the CBFilter BeforeSetAllocationSize event's handler function.
type CBFilterBeforeSetAllocationSizeEvent func(sender *CBFilter, args *CBFilterBeforeSetAllocationSizeEventArgs)
func (obj *CBFilter) GetOnBeforeSetAllocationSizeHandler() CBFilterBeforeSetAllocationSizeEvent
func (obj *CBFilter) SetOnBeforeSetAllocationSizeHandler(handlerFunc CBFilterBeforeSetAllocationSizeEvent)
Remarks
This event fires before the allocation size of the file specified by FileName is changed.
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 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 nil.)
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetEa Event (CBFilter Component)
This event fires before extended attributes of a file are changed.
Syntax
// CBFilterBeforeSetEaEventArgs carries the CBFilter BeforeSetEa event's parameters.
type CBFilterBeforeSetEaEventArgs struct {...}
func (args *CBFilterBeforeSetEaEventArgs) FileName() string
func (args *CBFilterBeforeSetEaEventArgs) Buffer() []byte
func (args *CBFilterBeforeSetEaEventArgs) SetBuffer(value []byte)
func (args *CBFilterBeforeSetEaEventArgs) BufferLength() int32
func (args *CBFilterBeforeSetEaEventArgs) FileContext() int64
func (args *CBFilterBeforeSetEaEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetEaEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetEaEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetEaEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetEaEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetEaEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetEaEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetEaEvent defines the signature of the CBFilter BeforeSetEa event's handler function.
type CBFilterBeforeSetEaEvent func(sender *CBFilter, args *CBFilterBeforeSetEaEventArgs)
func (obj *CBFilter) GetOnBeforeSetEaHandler() CBFilterBeforeSetEaEvent
func (obj *CBFilter) SetOnBeforeSetEaHandler(handlerFunc CBFilterBeforeSetEaEvent)
Remarks
This event fires before extended attributes are changed for the file specified by FileName.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetFileAttributes Event (CBFilter Component)
This event fires before a file or directory's attributes or times are changed.
Syntax
// CBFilterBeforeSetFileAttributesEventArgs carries the CBFilter BeforeSetFileAttributes event's parameters.
type CBFilterBeforeSetFileAttributesEventArgs struct {...}
func (args *CBFilterBeforeSetFileAttributesEventArgs) FileName() string
func (args *CBFilterBeforeSetFileAttributesEventArgs) CreationTime() time.Time
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetCreationTime(value time.Time)
func (args *CBFilterBeforeSetFileAttributesEventArgs) LastAccessTime() time.Time
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetLastAccessTime(value time.Time)
func (args *CBFilterBeforeSetFileAttributesEventArgs) LastWriteTime() time.Time
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetLastWriteTime(value time.Time)
func (args *CBFilterBeforeSetFileAttributesEventArgs) ChangeTime() time.Time
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetChangeTime(value time.Time)
func (args *CBFilterBeforeSetFileAttributesEventArgs) Attributes() int32
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetAttributes(value int32)
func (args *CBFilterBeforeSetFileAttributesEventArgs) FileContext() int64
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetFileAttributesEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetFileAttributesEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetFileAttributesEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetFileAttributesEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetFileAttributesEvent defines the signature of the CBFilter BeforeSetFileAttributes event's handler function.
type CBFilterBeforeSetFileAttributesEvent func(sender *CBFilter, args *CBFilterBeforeSetFileAttributesEventArgs)
func (obj *CBFilter) GetOnBeforeSetFileAttributesHandler() CBFilterBeforeSetFileAttributesEvent
func (obj *CBFilter) SetOnBeforeSetFileAttributesHandler(handlerFunc CBFilterBeforeSetFileAttributesEvent)
Remarks
This event fires before the attributes or times of a file or directory specified by FileName are changed.
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 in UTC. A value of January 1, 1601 00:00:00 UTC 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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetFileInfo Event (CBFilter Component)
This event fires before information about a file or directory is changed.
Syntax
// CBFilterBeforeSetFileInfoEventArgs carries the CBFilter BeforeSetFileInfo event's parameters.
type CBFilterBeforeSetFileInfoEventArgs struct {...}
func (args *CBFilterBeforeSetFileInfoEventArgs) FileName() string
func (args *CBFilterBeforeSetFileInfoEventArgs) FileInformationClass() int32
func (args *CBFilterBeforeSetFileInfoEventArgs) Buffer() []byte
func (args *CBFilterBeforeSetFileInfoEventArgs) SetBuffer(value []byte)
func (args *CBFilterBeforeSetFileInfoEventArgs) BufferLength() int32
func (args *CBFilterBeforeSetFileInfoEventArgs) ValidBytes() int32
func (args *CBFilterBeforeSetFileInfoEventArgs) SetValidBytes(value int32)
func (args *CBFilterBeforeSetFileInfoEventArgs) FileContext() int64
func (args *CBFilterBeforeSetFileInfoEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetFileInfoEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetFileInfoEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetFileInfoEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetFileInfoEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetFileInfoEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetFileInfoEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetFileInfoEvent defines the signature of the CBFilter BeforeSetFileInfo event's handler function.
type CBFilterBeforeSetFileInfoEvent func(sender *CBFilter, args *CBFilterBeforeSetFileInfoEventArgs)
func (obj *CBFilter) GetOnBeforeSetFileInfoHandler() CBFilterBeforeSetFileInfoEvent
func (obj *CBFilter) SetOnBeforeSetFileInfoHandler(handlerFunc CBFilterBeforeSetFileInfoEvent)
Remarks
This event fires before information about the file or directory specified by FileName is changed; 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:
- Copy no more than BufferLength bytes into Buffer.
- 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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetFileSecurity Event (CBFilter Component)
This event fires before a file or directory's security attributes are changed.
Syntax
// CBFilterBeforeSetFileSecurityEventArgs carries the CBFilter BeforeSetFileSecurity event's parameters.
type CBFilterBeforeSetFileSecurityEventArgs struct {...}
func (args *CBFilterBeforeSetFileSecurityEventArgs) FileName() string
func (args *CBFilterBeforeSetFileSecurityEventArgs) SecurityInformation() int32
func (args *CBFilterBeforeSetFileSecurityEventArgs) SecurityDescriptor() []byte
func (args *CBFilterBeforeSetFileSecurityEventArgs) SetSecurityDescriptor(value []byte)
func (args *CBFilterBeforeSetFileSecurityEventArgs) Length() int32
func (args *CBFilterBeforeSetFileSecurityEventArgs) FileContext() int64
func (args *CBFilterBeforeSetFileSecurityEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetFileSecurityEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetFileSecurityEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetFileSecurityEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetFileSecurityEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetFileSecurityEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetFileSecurityEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetFileSecurityEvent defines the signature of the CBFilter BeforeSetFileSecurity event's handler function.
type CBFilterBeforeSetFileSecurityEvent func(sender *CBFilter, args *CBFilterBeforeSetFileSecurityEventArgs)
func (obj *CBFilter) GetOnBeforeSetFileSecurityHandler() CBFilterBeforeSetFileSecurityEvent
func (obj *CBFilter) SetOnBeforeSetFileSecurityHandler(handlerFunc CBFilterBeforeSetFileSecurityEvent)
Remarks
This event fires before security attributes are changed for the file or directory specified by FileName.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetFileSize Event (CBFilter Component)
This event fires before a file is resized.
Syntax
// CBFilterBeforeSetFileSizeEventArgs carries the CBFilter BeforeSetFileSize event's parameters.
type CBFilterBeforeSetFileSizeEventArgs struct {...}
func (args *CBFilterBeforeSetFileSizeEventArgs) FileName() string
func (args *CBFilterBeforeSetFileSizeEventArgs) Size() int64
func (args *CBFilterBeforeSetFileSizeEventArgs) SetSize(value int64)
func (args *CBFilterBeforeSetFileSizeEventArgs) FileContext() int64
func (args *CBFilterBeforeSetFileSizeEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetFileSizeEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetFileSizeEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetFileSizeEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetFileSizeEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetFileSizeEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetFileSizeEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetFileSizeEvent defines the signature of the CBFilter BeforeSetFileSize event's handler function.
type CBFilterBeforeSetFileSizeEvent func(sender *CBFilter, args *CBFilterBeforeSetFileSizeEventArgs)
func (obj *CBFilter) GetOnBeforeSetFileSizeHandler() CBFilterBeforeSetFileSizeEvent
func (obj *CBFilter) SetOnBeforeSetFileSizeHandler(handlerFunc CBFilterBeforeSetFileSizeEvent)
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).
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 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 nil.)
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeSetReparsePoint Event (CBFilter Component)
This event fires when the OS wants to create or update a reparse point on a file or directory.
Syntax
// CBFilterBeforeSetReparsePointEventArgs carries the CBFilter BeforeSetReparsePoint event's parameters.
type CBFilterBeforeSetReparsePointEventArgs struct {...}
func (args *CBFilterBeforeSetReparsePointEventArgs) FileName() string
func (args *CBFilterBeforeSetReparsePointEventArgs) ReparseTag() int64
func (args *CBFilterBeforeSetReparsePointEventArgs) ReparseBuffer() []byte
func (args *CBFilterBeforeSetReparsePointEventArgs) SetReparseBuffer(value []byte)
func (args *CBFilterBeforeSetReparsePointEventArgs) BufferLength() int32
func (args *CBFilterBeforeSetReparsePointEventArgs) DataLength() int32
func (args *CBFilterBeforeSetReparsePointEventArgs) SetDataLength(value int32)
func (args *CBFilterBeforeSetReparsePointEventArgs) FileContext() int64
func (args *CBFilterBeforeSetReparsePointEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeSetReparsePointEventArgs) HandleContext() int64
func (args *CBFilterBeforeSetReparsePointEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeSetReparsePointEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeSetReparsePointEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeSetReparsePointEventArgs) ResultCode() int32
func (args *CBFilterBeforeSetReparsePointEventArgs) SetResultCode(value int32)
// CBFilterBeforeSetReparsePointEvent defines the signature of the CBFilter BeforeSetReparsePoint event's handler function.
type CBFilterBeforeSetReparsePointEvent func(sender *CBFilter, args *CBFilterBeforeSetReparsePointEventArgs)
func (obj *CBFilter) GetOnBeforeSetReparsePointHandler() CBFilterBeforeSetReparsePointEvent
func (obj *CBFilter) SetOnBeforeSetReparsePointHandler(handlerFunc CBFilterBeforeSetReparsePointEvent)
Remarks
This event fires before the OS creates or updates a reparse point on a file or directory specified by FileName.
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 component 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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeUnlockAll Event (CBFilter Component)
This event fires before all locked byte ranges in a file are unlocked.
Syntax
// CBFilterBeforeUnlockAllEventArgs carries the CBFilter BeforeUnlockAll event's parameters.
type CBFilterBeforeUnlockAllEventArgs struct {...}
func (args *CBFilterBeforeUnlockAllEventArgs) FileName() string
func (args *CBFilterBeforeUnlockAllEventArgs) FileContext() int64
func (args *CBFilterBeforeUnlockAllEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeUnlockAllEventArgs) HandleContext() int64
func (args *CBFilterBeforeUnlockAllEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeUnlockAllEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeUnlockAllEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeUnlockAllEventArgs) ResultCode() int32
func (args *CBFilterBeforeUnlockAllEventArgs) SetResultCode(value int32)
// CBFilterBeforeUnlockAllEvent defines the signature of the CBFilter BeforeUnlockAll event's handler function.
type CBFilterBeforeUnlockAllEvent func(sender *CBFilter, args *CBFilterBeforeUnlockAllEventArgs)
func (obj *CBFilter) GetOnBeforeUnlockAllHandler() CBFilterBeforeUnlockAllEvent
func (obj *CBFilter) SetOnBeforeUnlockAllHandler(handlerFunc CBFilterBeforeUnlockAllEvent)
Remarks
This event fires before all locked byte ranges in the file specified by FileName are unlocked.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeUnlockAllByKey Event (CBFilter Component)
This event fires before all locked byte ranges in a file, associated with a particular key, are unlocked.
Syntax
// CBFilterBeforeUnlockAllByKeyEventArgs carries the CBFilter BeforeUnlockAllByKey event's parameters.
type CBFilterBeforeUnlockAllByKeyEventArgs struct {...}
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) FileName() string
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) Key() int64
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) FileContext() int64
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) HandleContext() int64
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) ResultCode() int32
func (args *CBFilterBeforeUnlockAllByKeyEventArgs) SetResultCode(value int32)
// CBFilterBeforeUnlockAllByKeyEvent defines the signature of the CBFilter BeforeUnlockAllByKey event's handler function.
type CBFilterBeforeUnlockAllByKeyEvent func(sender *CBFilter, args *CBFilterBeforeUnlockAllByKeyEventArgs)
func (obj *CBFilter) GetOnBeforeUnlockAllByKeyHandler() CBFilterBeforeUnlockAllByKeyEvent
func (obj *CBFilter) SetOnBeforeUnlockAllByKeyHandler(handlerFunc CBFilterBeforeUnlockAllByKeyEvent)
Remarks
This event fires before all locked byte ranges in the file specified by FileName, and associated with the specified Key, are unlocked.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeUnlockSingle Event (CBFilter Component)
This event fires before a particular locked byte range in a file is unlocked.
Syntax
// CBFilterBeforeUnlockSingleEventArgs carries the CBFilter BeforeUnlockSingle event's parameters.
type CBFilterBeforeUnlockSingleEventArgs struct {...}
func (args *CBFilterBeforeUnlockSingleEventArgs) FileName() string
func (args *CBFilterBeforeUnlockSingleEventArgs) Offset() int64
func (args *CBFilterBeforeUnlockSingleEventArgs) SetOffset(value int64)
func (args *CBFilterBeforeUnlockSingleEventArgs) Length() int64
func (args *CBFilterBeforeUnlockSingleEventArgs) SetLength(value int64)
func (args *CBFilterBeforeUnlockSingleEventArgs) Key() int64
func (args *CBFilterBeforeUnlockSingleEventArgs) FileContext() int64
func (args *CBFilterBeforeUnlockSingleEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeUnlockSingleEventArgs) HandleContext() int64
func (args *CBFilterBeforeUnlockSingleEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeUnlockSingleEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeUnlockSingleEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeUnlockSingleEventArgs) ResultCode() int32
func (args *CBFilterBeforeUnlockSingleEventArgs) SetResultCode(value int32)
// CBFilterBeforeUnlockSingleEvent defines the signature of the CBFilter BeforeUnlockSingle event's handler function.
type CBFilterBeforeUnlockSingleEvent func(sender *CBFilter, args *CBFilterBeforeUnlockSingleEventArgs)
func (obj *CBFilter) GetOnBeforeUnlockSingleHandler() CBFilterBeforeUnlockSingleEvent
func (obj *CBFilter) SetOnBeforeUnlockSingleHandler(handlerFunc CBFilterBeforeUnlockSingleEvent)
Remarks
This event fires before a particular locked byte range in the file specified by FileName is unlocked.
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 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.
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
BeforeWriteFile Event (CBFilter Component)
This event fires before data are written to a file.
Syntax
// CBFilterBeforeWriteFileEventArgs carries the CBFilter BeforeWriteFile event's parameters.
type CBFilterBeforeWriteFileEventArgs struct {...}
func (args *CBFilterBeforeWriteFileEventArgs) FileName() string
func (args *CBFilterBeforeWriteFileEventArgs) Position() int64
func (args *CBFilterBeforeWriteFileEventArgs) SetPosition(value int64)
func (args *CBFilterBeforeWriteFileEventArgs) Buffer() []byte
func (args *CBFilterBeforeWriteFileEventArgs) SetBuffer(value []byte)
func (args *CBFilterBeforeWriteFileEventArgs) BufferLength() int32
func (args *CBFilterBeforeWriteFileEventArgs) BytesToWrite() int32
func (args *CBFilterBeforeWriteFileEventArgs) SetBytesToWrite(value int32)
func (args *CBFilterBeforeWriteFileEventArgs) Reserved() int32
func (args *CBFilterBeforeWriteFileEventArgs) SetReserved(value int32)
func (args *CBFilterBeforeWriteFileEventArgs) Direction() int32
func (args *CBFilterBeforeWriteFileEventArgs) FileContext() int64
func (args *CBFilterBeforeWriteFileEventArgs) SetFileContext(value int64)
func (args *CBFilterBeforeWriteFileEventArgs) HandleContext() int64
func (args *CBFilterBeforeWriteFileEventArgs) SetHandleContext(value int64)
func (args *CBFilterBeforeWriteFileEventArgs) ProcessRequest() bool
func (args *CBFilterBeforeWriteFileEventArgs) SetProcessRequest(value bool)
func (args *CBFilterBeforeWriteFileEventArgs) ResultCode() int32
func (args *CBFilterBeforeWriteFileEventArgs) SetResultCode(value int32)
// CBFilterBeforeWriteFileEvent defines the signature of the CBFilter BeforeWriteFile event's handler function.
type CBFilterBeforeWriteFileEvent func(sender *CBFilter, args *CBFilterBeforeWriteFileEventArgs)
func (obj *CBFilter) GetOnBeforeWriteFileHandler() CBFilterBeforeWriteFileEvent
func (obj *CBFilter) SetOnBeforeWriteFileHandler(handlerFunc CBFilterBeforeWriteFileEvent)
Remarks
This event fires before data are written to the file specified by FileName.
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:
- Enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires).
- Copy no more than BufferLength bytes into Buffer.
- 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:
- Write the data pointed to by Buffer to the desired location (after preprocessing it, if necessary).
- Update the BytesToWrite parameter's value afterward so that it correctly reflects the amount of data that were written.
- 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_NONCACHED | 0 | Operations performed in the user mode application <--> filesystem direction. |
| FS_REQUEST_DIR_USER_CACHED | 1 | Operations performed in the user mode application <--> system cache direction. |
| FS_REQUEST_DIR_SYSTEM_NONCACHED | 2 | Operations performed in the system cache <--> filesystem direction. |
| FS_REQUEST_DIR_SYSTEM_CACHED | 3 | Operations performed in the system component <--> system cache direction. |
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 nil.)
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
CleanupContext Event (CBFilter Component)
This event fires when the application-defined data stored in one or more contexts need to be cleaned up.
Syntax
// CBFilterCleanupContextEventArgs carries the CBFilter CleanupContext event's parameters.
type CBFilterCleanupContextEventArgs struct {...}
func (args *CBFilterCleanupContextEventArgs) FileContext() int64
func (args *CBFilterCleanupContextEventArgs) HandleContext() int64
func (args *CBFilterCleanupContextEventArgs) ResultCode() int32
func (args *CBFilterCleanupContextEventArgs) SetResultCode(value int32)
// CBFilterCleanupContextEvent defines the signature of the CBFilter CleanupContext event's handler function.
type CBFilterCleanupContextEvent func(sender *CBFilter, args *CBFilterCleanupContextEventArgs)
func (obj *CBFilter) GetOnCleanupContextHandler() CBFilterCleanupContextEvent
func (obj *CBFilter) SetOnCleanupContextHandler(handlerFunc CBFilterCleanupContextEvent)
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 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 nil. 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 nil. After this event fires, the applicable contexts are set back to nil 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 nil. Applications that clean up their contexts (and set them back to nil) 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
Error Event (CBFilter Component)
This event fires if an unhandled error occurs during an event.
Syntax
// CBFilterErrorEventArgs carries the CBFilter Error event's parameters.
type CBFilterErrorEventArgs struct {...}
func (args *CBFilterErrorEventArgs) ErrorCode() int32
func (args *CBFilterErrorEventArgs) Description() string
// CBFilterErrorEvent defines the signature of the CBFilter Error event's handler function.
type CBFilterErrorEvent func(sender *CBFilter, args *CBFilterErrorEventArgs)
func (obj *CBFilter) GetOnErrorHandler() CBFilterErrorEvent
func (obj *CBFilter) SetOnErrorHandler(handlerFunc CBFilterErrorEvent)
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 Component)
This event fires once the filter has attached and filtering has started.
Syntax
// CBFilterFilterStartEventArgs carries the CBFilter FilterStart event's parameters.
type CBFilterFilterStartEventArgs struct {...}
func (args *CBFilterFilterStartEventArgs) ResultCode() int32
func (args *CBFilterFilterStartEventArgs) SetResultCode(value int32)
// CBFilterFilterStartEvent defines the signature of the CBFilter FilterStart event's handler function.
type CBFilterFilterStartEvent func(sender *CBFilter, args *CBFilterFilterStartEventArgs)
func (obj *CBFilter) GetOnFilterStartHandler() CBFilterFilterStartEvent
func (obj *CBFilter) SetOnFilterStartHandler(handlerFunc CBFilterFilterStartEvent)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
FilterStop Event (CBFilter Component)
This event fires once filtering has stopped and the filter has detached.
Syntax
// CBFilterFilterStopEventArgs carries the CBFilter FilterStop event's parameters.
type CBFilterFilterStopEventArgs struct {...}
func (args *CBFilterFilterStopEventArgs) ResultCode() int32
func (args *CBFilterFilterStopEventArgs) SetResultCode(value int32)
// CBFilterFilterStopEvent defines the signature of the CBFilter FilterStop event's handler function.
type CBFilterFilterStopEvent func(sender *CBFilter, args *CBFilterFilterStopEventArgs)
func (obj *CBFilter) GetOnFilterStopHandler() CBFilterFilterStopEvent
func (obj *CBFilter) SetOnFilterStopHandler(handlerFunc CBFilterFilterStopEvent)
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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
NotifyCanFileBeDeleted Event (CBFilter Component)
This event fires when the OS marks a file or directory for deletion or removes such a mark.
Syntax
// CBFilterNotifyCanFileBeDeletedEventArgs carries the CBFilter NotifyCanFileBeDeleted event's parameters.
type CBFilterNotifyCanFileBeDeletedEventArgs struct {...}
func (args *CBFilterNotifyCanFileBeDeletedEventArgs) FileName() string
func (args *CBFilterNotifyCanFileBeDeletedEventArgs) RequestType() int32
func (args *CBFilterNotifyCanFileBeDeletedEventArgs) CanDelete() bool
func (args *CBFilterNotifyCanFileBeDeletedEventArgs) Status() int32
func (args *CBFilterNotifyCanFileBeDeletedEventArgs) ResultCode() int32
func (args *CBFilterNotifyCanFileBeDeletedEventArgs) SetResultCode(value int32)
// CBFilterNotifyCanFileBeDeletedEvent defines the signature of the CBFilter NotifyCanFileBeDeleted event's handler function.
type CBFilterNotifyCanFileBeDeletedEvent func(sender *CBFilter, args *CBFilterNotifyCanFileBeDeletedEventArgs)
func (obj *CBFilter) GetOnNotifyCanFileBeDeletedHandler() CBFilterNotifyCanFileBeDeletedEvent
func (obj *CBFilter) SetOnNotifyCanFileBeDeletedHandler(handlerFunc CBFilterNotifyCanFileBeDeletedEvent)
Remarks
This event fires when the OS marks the file or directory specified by FileName for deletion or removes such a mark.
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_FLAG | 0x1 | The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag |
| DEL_REQ_SET_DISPOSITION | 0x2 | The 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyCleanupFile Event (CBFilter Component)
This event fires when a file or directory handle has been closed.
Syntax
// CBFilterNotifyCleanupFileEventArgs carries the CBFilter NotifyCleanupFile event's parameters.
type CBFilterNotifyCleanupFileEventArgs struct {...}
func (args *CBFilterNotifyCleanupFileEventArgs) FileName() string
func (args *CBFilterNotifyCleanupFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyCleanupFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyCleanupFileEvent defines the signature of the CBFilter NotifyCleanupFile event's handler function.
type CBFilterNotifyCleanupFileEvent func(sender *CBFilter, args *CBFilterNotifyCleanupFileEventArgs)
func (obj *CBFilter) GetOnNotifyCleanupFileHandler() CBFilterNotifyCleanupFileEvent
func (obj *CBFilter) SetOnNotifyCleanupFileHandler(handlerFunc CBFilterNotifyCleanupFileEvent)
Remarks
This event fires when a handle to the file or directory specified by FileName has been closed. 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyCloseFile Event (CBFilter Component)
This event fires when a file or directory has been closed.
Syntax
// CBFilterNotifyCloseFileEventArgs carries the CBFilter NotifyCloseFile event's parameters.
type CBFilterNotifyCloseFileEventArgs struct {...}
func (args *CBFilterNotifyCloseFileEventArgs) FileName() string
func (args *CBFilterNotifyCloseFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyCloseFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyCloseFileEvent defines the signature of the CBFilter NotifyCloseFile event's handler function.
type CBFilterNotifyCloseFileEvent func(sender *CBFilter, args *CBFilterNotifyCloseFileEventArgs)
func (obj *CBFilter) GetOnNotifyCloseFileHandler() CBFilterNotifyCloseFileEvent
func (obj *CBFilter) SetOnNotifyCloseFileHandler(handlerFunc CBFilterNotifyCloseFileEvent)
Remarks
This event fires when the file or directory specified by FileName has been closed.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyCreateFile Event (CBFilter Component)
This event fires when a file or directory has been created.
Syntax
// CBFilterNotifyCreateFileEventArgs carries the CBFilter NotifyCreateFile event's parameters.
type CBFilterNotifyCreateFileEventArgs struct {...}
func (args *CBFilterNotifyCreateFileEventArgs) FileName() string
func (args *CBFilterNotifyCreateFileEventArgs) ExistingAttributes() int32
func (args *CBFilterNotifyCreateFileEventArgs) DesiredAccess() int32
func (args *CBFilterNotifyCreateFileEventArgs) Attributes() int32
func (args *CBFilterNotifyCreateFileEventArgs) ShareMode() int32
func (args *CBFilterNotifyCreateFileEventArgs) Options() int32
func (args *CBFilterNotifyCreateFileEventArgs) CreateDisposition() int32
func (args *CBFilterNotifyCreateFileEventArgs) SecurityDescriptor() []byte
func (args *CBFilterNotifyCreateFileEventArgs) Length() int32
func (args *CBFilterNotifyCreateFileEventArgs) Status() int32
func (args *CBFilterNotifyCreateFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyCreateFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyCreateFileEvent defines the signature of the CBFilter NotifyCreateFile event's handler function.
type CBFilterNotifyCreateFileEvent func(sender *CBFilter, args *CBFilterNotifyCreateFileEventArgs)
func (obj *CBFilter) GetOnNotifyCreateFileHandler() CBFilterNotifyCreateFileEvent
func (obj *CBFilter) SetOnNotifyCreateFileHandler(handlerFunc CBFilterNotifyCreateFileEvent)
Remarks
This event fires when the file or directory specified by FileName has been created. Please refer to the File Create/Open Events topic for more information about how the component 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_DIRECTORY | 0x00000001 | For a directory, the right to list the contents of the directory. |
| DESIRED_ACCESS_FILE_READ_DATA | 0x00000001 | For 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_FILE | 0x00000002 | For a directory, the right to create a file in the directory. |
| DESIRED_ACCESS_FILE_WRITE_DATA | 0x00000002 | For 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_SUBDIRECTORY | 0x00000004 | For a directory, the right to create a subdirectory. |
| DESIRED_ACCESS_FILE_APPEND_DATA | 0x00000004 | For 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_EA | 0x00000008 | The right to read extended file attributes. |
| DESIRED_ACCESS_FILE_WRITE_EA | 0x00000010 | The right to write extended file attributes. |
| DESIRED_ACCESS_FILE_EXECUTE | 0x00000020 | For 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_CHILD | 0x00000040 | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| DESIRED_ACCESS_FILE_READ_ATTRIBUTES | 0x00000080 | The right to read file attributes. |
| DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES | 0x00000100 | The right to write file attributes. |
| DESIRED_ACCESS_READ_CONTROL | 0x00020000 | 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_READ | 0x00020000 | Includes 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_WRITE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_SYNCHRONIZE | 0x00100000 | The 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_ACCESS | 0x001F01FF | All possible access rights for a file. |
| DESIRED_ACCESS_FILE_GENERIC_READ | 0x00120089 | A 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_WRITE | 0x00120116 | A 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_EXECUTE | 0x001200A0 | A 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_ONLY | 0x00000001 | The 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_HIDDEN | 0x00000002 | The file or directory is hidden.
The file is not included in an ordinary directory listing. |
| FILE_SYS_ATTR_SYSTEM | 0x00000004 | A file or directory that the operating system uses a part of, or uses exclusively. |
| FILE_SYS_ATTR_DIRECTORY | 0x00000010 | The entry is a directory. |
| FILE_SYS_ATTR_ARCHIVE | 0x00000020 | The entry is an archive file or directory.
Applications typically use this attribute to mark files for backup or removal. |
| FILE_SYS_ATTR_NORMAL | 0x00000080 | A file doesn't have other attributes set.
This attribute is valid only when used alone. |
| FILE_SYS_ATTR_TEMPORARY | 0x00000100 | A 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_FILE | 0x00000200 | A file that is a sparse file. |
| FILE_SYS_ATTR_REPARSE_POINT | 0x00000400 | A file that is a reparse point or a symbolic link. |
| FILE_SYS_ATTR_COMPRESSED | 0x00000800 | A 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_OFFLINE | 0x00001000 | The 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_INDEXED | 0x00002000 | The file or directory is not to be indexed by the content indexing service. |
| FILE_SYS_ATTR_ENCRYPTED | 0x00004000 | A 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_VIRTUAL | 0x00010000 | Reserved.
Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations. |
| FILE_SYS_ATTR_RECALL_ON_OPEN | 0x00040000 | The 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_NEW | 0x00000001 | Creates 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_ALWAYS | 0x00000002 | Creates 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_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens 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_EXISTING | 0x00000005 | Opens 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 component 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 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyCreateHardLink Event (CBFilter Component)
This event fires when a hard link has been created.
Syntax
// CBFilterNotifyCreateHardLinkEventArgs carries the CBFilter NotifyCreateHardLink event's parameters.
type CBFilterNotifyCreateHardLinkEventArgs struct {...}
func (args *CBFilterNotifyCreateHardLinkEventArgs) FileName() string
func (args *CBFilterNotifyCreateHardLinkEventArgs) LinkName() string
func (args *CBFilterNotifyCreateHardLinkEventArgs) Status() int32
func (args *CBFilterNotifyCreateHardLinkEventArgs) ResultCode() int32
func (args *CBFilterNotifyCreateHardLinkEventArgs) SetResultCode(value int32)
// CBFilterNotifyCreateHardLinkEvent defines the signature of the CBFilter NotifyCreateHardLink event's handler function.
type CBFilterNotifyCreateHardLinkEvent func(sender *CBFilter, args *CBFilterNotifyCreateHardLinkEventArgs)
func (obj *CBFilter) GetOnNotifyCreateHardLinkHandler() CBFilterNotifyCreateHardLinkEvent
func (obj *CBFilter) SetOnNotifyCreateHardLinkHandler(handlerFunc CBFilterNotifyCreateHardLinkEvent)
Remarks
This event fires when a hard link to the file specified by FileName has been created. 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyDeleteFile Event (CBFilter Component)
This event fires when a file or directory has been deleted.
Syntax
// CBFilterNotifyDeleteFileEventArgs carries the CBFilter NotifyDeleteFile event's parameters.
type CBFilterNotifyDeleteFileEventArgs struct {...}
func (args *CBFilterNotifyDeleteFileEventArgs) FileName() string
func (args *CBFilterNotifyDeleteFileEventArgs) RequestType() int32
func (args *CBFilterNotifyDeleteFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyDeleteFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyDeleteFileEvent defines the signature of the CBFilter NotifyDeleteFile event's handler function.
type CBFilterNotifyDeleteFileEvent func(sender *CBFilter, args *CBFilterNotifyDeleteFileEventArgs)
func (obj *CBFilter) GetOnNotifyDeleteFileHandler() CBFilterNotifyDeleteFileEvent
func (obj *CBFilter) SetOnNotifyDeleteFileHandler(handlerFunc CBFilterNotifyDeleteFileEvent)
Remarks
This event fires when the file or directory specified by FileName has been deleted. 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_FLAG | 0x1 | The file or directory is opened with the FILE_FLAG_DELETE_ON_CLOSE flag |
| DEL_REQ_SET_DISPOSITION | 0x2 | The 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyDeleteReparsePoint Event (CBFilter Component)
This event fires when a file or directory's reparse point has been deleted.
Syntax
// CBFilterNotifyDeleteReparsePointEventArgs carries the CBFilter NotifyDeleteReparsePoint event's parameters.
type CBFilterNotifyDeleteReparsePointEventArgs struct {...}
func (args *CBFilterNotifyDeleteReparsePointEventArgs) FileName() string
func (args *CBFilterNotifyDeleteReparsePointEventArgs) Status() int32
func (args *CBFilterNotifyDeleteReparsePointEventArgs) ResultCode() int32
func (args *CBFilterNotifyDeleteReparsePointEventArgs) SetResultCode(value int32)
// CBFilterNotifyDeleteReparsePointEvent defines the signature of the CBFilter NotifyDeleteReparsePoint event's handler function.
type CBFilterNotifyDeleteReparsePointEvent func(sender *CBFilter, args *CBFilterNotifyDeleteReparsePointEventArgs)
func (obj *CBFilter) GetOnNotifyDeleteReparsePointHandler() CBFilterNotifyDeleteReparsePointEvent
func (obj *CBFilter) SetOnNotifyDeleteReparsePointHandler(handlerFunc CBFilterNotifyDeleteReparsePointEvent)
Remarks
This event fires when a reparse point has been deleted from the file or directory specified by FileName.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyEnumerateDirectory Event (CBFilter Component)
This event fires when a directory entry has been returned during directory enumeration.
Syntax
// CBFilterNotifyEnumerateDirectoryEventArgs carries the CBFilter NotifyEnumerateDirectory event's parameters.
type CBFilterNotifyEnumerateDirectoryEventArgs struct {...}
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) DirectoryName() string
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) Flags() int32
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) Index() int32
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) FileName() string
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) CreationTime() time.Time
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) LastAccessTime() time.Time
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) LastWriteTime() time.Time
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) ChangeTime() time.Time
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) Size() int64
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) AllocationSize() int64
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) FileId() int64
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) Attributes() int32
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) Status() int32
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) ResultCode() int32
func (args *CBFilterNotifyEnumerateDirectoryEventArgs) SetResultCode(value int32)
// CBFilterNotifyEnumerateDirectoryEvent defines the signature of the CBFilter NotifyEnumerateDirectory event's handler function.
type CBFilterNotifyEnumerateDirectoryEvent func(sender *CBFilter, args *CBFilterNotifyEnumerateDirectoryEventArgs)
func (obj *CBFilter) GetOnNotifyEnumerateDirectoryHandler() CBFilterNotifyEnumerateDirectoryEvent
func (obj *CBFilter) SetOnNotifyEnumerateDirectoryHandler(handlerFunc CBFilterNotifyEnumerateDirectoryEvent)
Remarks
This event fires when a directory entry (i.e., file or subdirectory) has been returned during enumeration of the directory specified by DirectoryName.
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_SCAN | 1 | The requestor specified that directory enumeration must be restarted. |
| FS_ENUM_RETURN_SINGLE_ENTRY | 2 | One entry should be returned. |
| FS_ENUM_INDEX_SPECIFIED | 4 | The 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 in UTC.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyFilterAttachToVolume Event (CBFilter Component)
This event fires when the filter has been attached to a newly mounted filesystem volume.
Syntax
// CBFilterNotifyFilterAttachToVolumeEventArgs carries the CBFilter NotifyFilterAttachToVolume event's parameters.
type CBFilterNotifyFilterAttachToVolumeEventArgs struct {...}
func (args *CBFilterNotifyFilterAttachToVolumeEventArgs) VolumeName() string
func (args *CBFilterNotifyFilterAttachToVolumeEventArgs) ResultCode() int32
func (args *CBFilterNotifyFilterAttachToVolumeEventArgs) SetResultCode(value int32)
// CBFilterNotifyFilterAttachToVolumeEvent defines the signature of the CBFilter NotifyFilterAttachToVolume event's handler function.
type CBFilterNotifyFilterAttachToVolumeEvent func(sender *CBFilter, args *CBFilterNotifyFilterAttachToVolumeEventArgs)
func (obj *CBFilter) GetOnNotifyFilterAttachToVolumeHandler() CBFilterNotifyFilterAttachToVolumeEvent
func (obj *CBFilter) SetOnNotifyFilterAttachToVolumeHandler(handlerFunc CBFilterNotifyFilterAttachToVolumeEvent)
Remarks
This event fires when the filter has been attached to the newly mounted filesystem volume specified by 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.
Applications that use volume-specific rules should typically add such rules during the AfterFilterAttachToVolume event, which is fired synchronously, rather than this one.
The format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 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 Reporting and 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 Component)
This event fires when the filter has been detached from a filesystem volume.
Syntax
// CBFilterNotifyFilterDetachFromVolumeEventArgs carries the CBFilter NotifyFilterDetachFromVolume event's parameters.
type CBFilterNotifyFilterDetachFromVolumeEventArgs struct {...}
func (args *CBFilterNotifyFilterDetachFromVolumeEventArgs) VolumeName() string
func (args *CBFilterNotifyFilterDetachFromVolumeEventArgs) ResultCode() int32
func (args *CBFilterNotifyFilterDetachFromVolumeEventArgs) SetResultCode(value int32)
// CBFilterNotifyFilterDetachFromVolumeEvent defines the signature of the CBFilter NotifyFilterDetachFromVolume event's handler function.
type CBFilterNotifyFilterDetachFromVolumeEvent func(sender *CBFilter, args *CBFilterNotifyFilterDetachFromVolumeEventArgs)
func (obj *CBFilter) GetOnNotifyFilterDetachFromVolumeHandler() CBFilterNotifyFilterDetachFromVolumeEvent
func (obj *CBFilter) SetOnNotifyFilterDetachFromVolumeHandler(handlerFunc CBFilterNotifyFilterDetachFromVolumeEvent)
Remarks
This event fires when the filter has been detached from the filesystem volume specified by 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.
Applications that use volume-specific rules typically should remove such rules during the AfterFilterDetachFromVolume event, which is fired synchronously, rather than this one.
The format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 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 Reporting and 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 Component)
This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.
Syntax
// CBFilterNotifyFsctlEventArgs carries the CBFilter NotifyFsctl event's parameters.
type CBFilterNotifyFsctlEventArgs struct {...}
func (args *CBFilterNotifyFsctlEventArgs) FileName() string
func (args *CBFilterNotifyFsctlEventArgs) FsControlCode() int32
func (args *CBFilterNotifyFsctlEventArgs) InBuffer() []byte
func (args *CBFilterNotifyFsctlEventArgs) InBufferLength() int32
func (args *CBFilterNotifyFsctlEventArgs) InBufferValidBytes() int32
func (args *CBFilterNotifyFsctlEventArgs) OutBuffer() []byte
func (args *CBFilterNotifyFsctlEventArgs) OutBufferLength() int32
func (args *CBFilterNotifyFsctlEventArgs) OutBufferValidBytes() int32
func (args *CBFilterNotifyFsctlEventArgs) Status() int32
func (args *CBFilterNotifyFsctlEventArgs) ResultCode() int32
func (args *CBFilterNotifyFsctlEventArgs) SetResultCode(value int32)
// CBFilterNotifyFsctlEvent defines the signature of the CBFilter NotifyFsctl event's handler function.
type CBFilterNotifyFsctlEvent func(sender *CBFilter, args *CBFilterNotifyFsctlEventArgs)
func (obj *CBFilter) GetOnNotifyFsctlHandler() CBFilterNotifyFsctlEvent
func (obj *CBFilter) SetOnNotifyFsctlHandler(handlerFunc CBFilterNotifyFsctlEvent)
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyGetFileSecurity Event (CBFilter Component)
This event fires when a file or directory's security attributes have been retrieved.
Syntax
// CBFilterNotifyGetFileSecurityEventArgs carries the CBFilter NotifyGetFileSecurity event's parameters.
type CBFilterNotifyGetFileSecurityEventArgs struct {...}
func (args *CBFilterNotifyGetFileSecurityEventArgs) FileName() string
func (args *CBFilterNotifyGetFileSecurityEventArgs) SecurityInformation() int32
func (args *CBFilterNotifyGetFileSecurityEventArgs) SecurityDescriptor() []byte
func (args *CBFilterNotifyGetFileSecurityEventArgs) Length() int32
func (args *CBFilterNotifyGetFileSecurityEventArgs) Status() int32
func (args *CBFilterNotifyGetFileSecurityEventArgs) ResultCode() int32
func (args *CBFilterNotifyGetFileSecurityEventArgs) SetResultCode(value int32)
// CBFilterNotifyGetFileSecurityEvent defines the signature of the CBFilter NotifyGetFileSecurity event's handler function.
type CBFilterNotifyGetFileSecurityEvent func(sender *CBFilter, args *CBFilterNotifyGetFileSecurityEventArgs)
func (obj *CBFilter) GetOnNotifyGetFileSecurityHandler() CBFilterNotifyGetFileSecurityEvent
func (obj *CBFilter) SetOnNotifyGetFileSecurityHandler(handlerFunc CBFilterNotifyGetFileSecurityEvent)
Remarks
This event fires when security attributes have been retrieved for the file or directory specified by FileName.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyGetFileSizes Event (CBFilter Component)
This event fires when a file's size information has been retrieved.
Syntax
// CBFilterNotifyGetFileSizesEventArgs carries the CBFilter NotifyGetFileSizes event's parameters.
type CBFilterNotifyGetFileSizesEventArgs struct {...}
func (args *CBFilterNotifyGetFileSizesEventArgs) FileName() string
func (args *CBFilterNotifyGetFileSizesEventArgs) Size() int64
func (args *CBFilterNotifyGetFileSizesEventArgs) AllocationSize() int64
func (args *CBFilterNotifyGetFileSizesEventArgs) Status() int32
func (args *CBFilterNotifyGetFileSizesEventArgs) ResultCode() int32
func (args *CBFilterNotifyGetFileSizesEventArgs) SetResultCode(value int32)
// CBFilterNotifyGetFileSizesEvent defines the signature of the CBFilter NotifyGetFileSizes event's handler function.
type CBFilterNotifyGetFileSizesEvent func(sender *CBFilter, args *CBFilterNotifyGetFileSizesEventArgs)
func (obj *CBFilter) GetOnNotifyGetFileSizesHandler() CBFilterNotifyGetFileSizesEvent
func (obj *CBFilter) SetOnNotifyGetFileSizesHandler(handlerFunc CBFilterNotifyGetFileSizesEvent)
Remarks
This event fires when size information has been retrieved for the file specified by FileName.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyGetReparsePoint Event (CBFilter Component)
This event fires when a file or directory's reparse point information has been retrieved.
Syntax
// CBFilterNotifyGetReparsePointEventArgs carries the CBFilter NotifyGetReparsePoint event's parameters.
type CBFilterNotifyGetReparsePointEventArgs struct {...}
func (args *CBFilterNotifyGetReparsePointEventArgs) FileName() string
func (args *CBFilterNotifyGetReparsePointEventArgs) Status() int32
func (args *CBFilterNotifyGetReparsePointEventArgs) ResultCode() int32
func (args *CBFilterNotifyGetReparsePointEventArgs) SetResultCode(value int32)
// CBFilterNotifyGetReparsePointEvent defines the signature of the CBFilter NotifyGetReparsePoint event's handler function.
type CBFilterNotifyGetReparsePointEvent func(sender *CBFilter, args *CBFilterNotifyGetReparsePointEventArgs)
func (obj *CBFilter) GetOnNotifyGetReparsePointHandler() CBFilterNotifyGetReparsePointEvent
func (obj *CBFilter) SetOnNotifyGetReparsePointHandler(handlerFunc CBFilterNotifyGetReparsePointEvent)
Remarks
This event fires when reparse point information has been retrieved for the file or directory specified by FileName.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyIoctl Event (CBFilter Component)
This event fires when an IRP_MJ_DEVICE_CONTROL operation has occurred.
Syntax
// CBFilterNotifyIoctlEventArgs carries the CBFilter NotifyIoctl event's parameters.
type CBFilterNotifyIoctlEventArgs struct {...}
func (args *CBFilterNotifyIoctlEventArgs) FileName() string
func (args *CBFilterNotifyIoctlEventArgs) IoControlCode() int32
func (args *CBFilterNotifyIoctlEventArgs) InBuffer() []byte
func (args *CBFilterNotifyIoctlEventArgs) InBufferLength() int32
func (args *CBFilterNotifyIoctlEventArgs) InBufferValidBytes() int32
func (args *CBFilterNotifyIoctlEventArgs) OutBuffer() []byte
func (args *CBFilterNotifyIoctlEventArgs) OutBufferLength() int32
func (args *CBFilterNotifyIoctlEventArgs) OutBufferValidBytes() int32
func (args *CBFilterNotifyIoctlEventArgs) Status() int32
func (args *CBFilterNotifyIoctlEventArgs) ResultCode() int32
func (args *CBFilterNotifyIoctlEventArgs) SetResultCode(value int32)
// CBFilterNotifyIoctlEvent defines the signature of the CBFilter NotifyIoctl event's handler function.
type CBFilterNotifyIoctlEvent func(sender *CBFilter, args *CBFilterNotifyIoctlEventArgs)
func (obj *CBFilter) GetOnNotifyIoctlHandler() CBFilterNotifyIoctlEvent
func (obj *CBFilter) SetOnNotifyIoctlHandler(handlerFunc CBFilterNotifyIoctlEvent)
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyLock Event (CBFilter Component)
This event fires when a range of bytes in a file has been locked.
Syntax
// CBFilterNotifyLockEventArgs carries the CBFilter NotifyLock event's parameters.
type CBFilterNotifyLockEventArgs struct {...}
func (args *CBFilterNotifyLockEventArgs) FileName() string
func (args *CBFilterNotifyLockEventArgs) Offset() int64
func (args *CBFilterNotifyLockEventArgs) Length() int64
func (args *CBFilterNotifyLockEventArgs) Key() int64
func (args *CBFilterNotifyLockEventArgs) FailImmediately() bool
func (args *CBFilterNotifyLockEventArgs) ExclusiveLock() bool
func (args *CBFilterNotifyLockEventArgs) Status() int32
func (args *CBFilterNotifyLockEventArgs) ResultCode() int32
func (args *CBFilterNotifyLockEventArgs) SetResultCode(value int32)
// CBFilterNotifyLockEvent defines the signature of the CBFilter NotifyLock event's handler function.
type CBFilterNotifyLockEvent func(sender *CBFilter, args *CBFilterNotifyLockEventArgs)
func (obj *CBFilter) GetOnNotifyLockHandler() CBFilterNotifyLockEvent
func (obj *CBFilter) SetOnNotifyLockHandler(handlerFunc CBFilterNotifyLockEvent)
Remarks
This event fires when a range of bytes in the file specified by FileName has been locked; 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyOpenFile Event (CBFilter Component)
This event fires when a file or directory has been opened.
Syntax
// CBFilterNotifyOpenFileEventArgs carries the CBFilter NotifyOpenFile event's parameters.
type CBFilterNotifyOpenFileEventArgs struct {...}
func (args *CBFilterNotifyOpenFileEventArgs) FileName() string
func (args *CBFilterNotifyOpenFileEventArgs) ExistingAttributes() int32
func (args *CBFilterNotifyOpenFileEventArgs) DesiredAccess() int32
func (args *CBFilterNotifyOpenFileEventArgs) Attributes() int32
func (args *CBFilterNotifyOpenFileEventArgs) ShareMode() int32
func (args *CBFilterNotifyOpenFileEventArgs) Options() int32
func (args *CBFilterNotifyOpenFileEventArgs) CreateDisposition() int32
func (args *CBFilterNotifyOpenFileEventArgs) SecurityDescriptor() []byte
func (args *CBFilterNotifyOpenFileEventArgs) Length() int32
func (args *CBFilterNotifyOpenFileEventArgs) Status() int32
func (args *CBFilterNotifyOpenFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyOpenFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyOpenFileEvent defines the signature of the CBFilter NotifyOpenFile event's handler function.
type CBFilterNotifyOpenFileEvent func(sender *CBFilter, args *CBFilterNotifyOpenFileEventArgs)
func (obj *CBFilter) GetOnNotifyOpenFileHandler() CBFilterNotifyOpenFileEvent
func (obj *CBFilter) SetOnNotifyOpenFileHandler(handlerFunc CBFilterNotifyOpenFileEvent)
Remarks
This event fires when the file or directory specified by FileName has been opened. Please refer to the File Create/Open Events topic for more information about how the component 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_DIRECTORY | 0x00000001 | For a directory, the right to list the contents of the directory. |
| DESIRED_ACCESS_FILE_READ_DATA | 0x00000001 | For 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_FILE | 0x00000002 | For a directory, the right to create a file in the directory. |
| DESIRED_ACCESS_FILE_WRITE_DATA | 0x00000002 | For 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_SUBDIRECTORY | 0x00000004 | For a directory, the right to create a subdirectory. |
| DESIRED_ACCESS_FILE_APPEND_DATA | 0x00000004 | For 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_EA | 0x00000008 | The right to read extended file attributes. |
| DESIRED_ACCESS_FILE_WRITE_EA | 0x00000010 | The right to write extended file attributes. |
| DESIRED_ACCESS_FILE_EXECUTE | 0x00000020 | For 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_CHILD | 0x00000040 | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| DESIRED_ACCESS_FILE_READ_ATTRIBUTES | 0x00000080 | The right to read file attributes. |
| DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES | 0x00000100 | The right to write file attributes. |
| DESIRED_ACCESS_READ_CONTROL | 0x00020000 | 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_READ | 0x00020000 | Includes 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_WRITE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE | 0x00020000 | Same as STANDARD_RIGHTS_READ |
| DESIRED_ACCESS_SYNCHRONIZE | 0x00100000 | The 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_ACCESS | 0x001F01FF | All possible access rights for a file. |
| DESIRED_ACCESS_FILE_GENERIC_READ | 0x00120089 | A 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_WRITE | 0x00120116 | A 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_EXECUTE | 0x001200A0 | A 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_ONLY | 0x00000001 | The 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_HIDDEN | 0x00000002 | The file or directory is hidden.
The file is not included in an ordinary directory listing. |
| FILE_SYS_ATTR_SYSTEM | 0x00000004 | A file or directory that the operating system uses a part of, or uses exclusively. |
| FILE_SYS_ATTR_DIRECTORY | 0x00000010 | The entry is a directory. |
| FILE_SYS_ATTR_ARCHIVE | 0x00000020 | The entry is an archive file or directory.
Applications typically use this attribute to mark files for backup or removal. |
| FILE_SYS_ATTR_NORMAL | 0x00000080 | A file doesn't have other attributes set.
This attribute is valid only when used alone. |
| FILE_SYS_ATTR_TEMPORARY | 0x00000100 | A 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_FILE | 0x00000200 | A file that is a sparse file. |
| FILE_SYS_ATTR_REPARSE_POINT | 0x00000400 | A file that is a reparse point or a symbolic link. |
| FILE_SYS_ATTR_COMPRESSED | 0x00000800 | A 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_OFFLINE | 0x00001000 | The 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_INDEXED | 0x00002000 | The file or directory is not to be indexed by the content indexing service. |
| FILE_SYS_ATTR_ENCRYPTED | 0x00004000 | A 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_VIRTUAL | 0x00010000 | Reserved.
Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations. |
| FILE_SYS_ATTR_RECALL_ON_OPEN | 0x00040000 | The 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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_NEW | 0x00000001 | Creates 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_ALWAYS | 0x00000002 | Creates 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_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens 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_EXISTING | 0x00000005 | Opens 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 component 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 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyQueryEa Event (CBFilter Component)
This event fires when information about the extended attributes of a file has been retrieved.
Syntax
// CBFilterNotifyQueryEaEventArgs carries the CBFilter NotifyQueryEa event's parameters.
type CBFilterNotifyQueryEaEventArgs struct {...}
func (args *CBFilterNotifyQueryEaEventArgs) FileName() string
func (args *CBFilterNotifyQueryEaEventArgs) Buffer() []byte
func (args *CBFilterNotifyQueryEaEventArgs) BufferLength() int32
func (args *CBFilterNotifyQueryEaEventArgs) ReturnSingleEntry() bool
func (args *CBFilterNotifyQueryEaEventArgs) EaList() []byte
func (args *CBFilterNotifyQueryEaEventArgs) EaListLength() int32
func (args *CBFilterNotifyQueryEaEventArgs) EaIndex() int32
func (args *CBFilterNotifyQueryEaEventArgs) RestartScan() bool
func (args *CBFilterNotifyQueryEaEventArgs) LengthReturned() int32
func (args *CBFilterNotifyQueryEaEventArgs) Status() int32
func (args *CBFilterNotifyQueryEaEventArgs) ResultCode() int32
func (args *CBFilterNotifyQueryEaEventArgs) SetResultCode(value int32)
// CBFilterNotifyQueryEaEvent defines the signature of the CBFilter NotifyQueryEa event's handler function.
type CBFilterNotifyQueryEaEvent func(sender *CBFilter, args *CBFilterNotifyQueryEaEventArgs)
func (obj *CBFilter) GetOnNotifyQueryEaHandler() CBFilterNotifyQueryEaEvent
func (obj *CBFilter) SetOnNotifyQueryEaHandler(handlerFunc CBFilterNotifyQueryEaEvent)
Remarks
This event fires when information about the extended attributes of a file specified by FileName has been retrieved.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyQueryFileInfo Event (CBFilter Component)
This event fires when information about a file or directory has been retrieved.
Syntax
// CBFilterNotifyQueryFileInfoEventArgs carries the CBFilter NotifyQueryFileInfo event's parameters.
type CBFilterNotifyQueryFileInfoEventArgs struct {...}
func (args *CBFilterNotifyQueryFileInfoEventArgs) FileName() string
func (args *CBFilterNotifyQueryFileInfoEventArgs) FileInformationClass() int32
func (args *CBFilterNotifyQueryFileInfoEventArgs) Buffer() []byte
func (args *CBFilterNotifyQueryFileInfoEventArgs) BufferLength() int32
func (args *CBFilterNotifyQueryFileInfoEventArgs) ValidBytes() int32
func (args *CBFilterNotifyQueryFileInfoEventArgs) Status() int32
func (args *CBFilterNotifyQueryFileInfoEventArgs) ResultCode() int32
func (args *CBFilterNotifyQueryFileInfoEventArgs) SetResultCode(value int32)
// CBFilterNotifyQueryFileInfoEvent defines the signature of the CBFilter NotifyQueryFileInfo event's handler function.
type CBFilterNotifyQueryFileInfoEvent func(sender *CBFilter, args *CBFilterNotifyQueryFileInfoEventArgs)
func (obj *CBFilter) GetOnNotifyQueryFileInfoHandler() CBFilterNotifyQueryFileInfoEvent
func (obj *CBFilter) SetOnNotifyQueryFileInfoHandler(handlerFunc CBFilterNotifyQueryFileInfoEvent)
Remarks
This event fires when information about a file or directory specified by FileName has been retrieved; 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyReadFile Event (CBFilter Component)
This event fires when data have been read from a file.
Syntax
// CBFilterNotifyReadFileEventArgs carries the CBFilter NotifyReadFile event's parameters.
type CBFilterNotifyReadFileEventArgs struct {...}
func (args *CBFilterNotifyReadFileEventArgs) FileName() string
func (args *CBFilterNotifyReadFileEventArgs) Position() int64
func (args *CBFilterNotifyReadFileEventArgs) BytesToRead() int32
func (args *CBFilterNotifyReadFileEventArgs) Direction() int32
func (args *CBFilterNotifyReadFileEventArgs) BytesRead() int32
func (args *CBFilterNotifyReadFileEventArgs) Status() int32
func (args *CBFilterNotifyReadFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyReadFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyReadFileEvent defines the signature of the CBFilter NotifyReadFile event's handler function.
type CBFilterNotifyReadFileEvent func(sender *CBFilter, args *CBFilterNotifyReadFileEventArgs)
func (obj *CBFilter) GetOnNotifyReadFileHandler() CBFilterNotifyReadFileEvent
func (obj *CBFilter) SetOnNotifyReadFileHandler(handlerFunc CBFilterNotifyReadFileEvent)
Remarks
This event fires when data have been read from a file specified by FileName.
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_NONCACHED | 0 | Operations performed in the user mode application <--> filesystem direction. |
| FS_REQUEST_DIR_USER_CACHED | 1 | Operations performed in the user mode application <--> system cache direction. |
| FS_REQUEST_DIR_SYSTEM_NONCACHED | 2 | Operations performed in the system cache <--> filesystem direction. |
| FS_REQUEST_DIR_SYSTEM_CACHED | 3 | Operations 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyRenameOrMoveFile Event (CBFilter Component)
This event fires when a file or directory has been renamed or moved.
Syntax
// CBFilterNotifyRenameOrMoveFileEventArgs carries the CBFilter NotifyRenameOrMoveFile event's parameters.
type CBFilterNotifyRenameOrMoveFileEventArgs struct {...}
func (args *CBFilterNotifyRenameOrMoveFileEventArgs) FileName() string
func (args *CBFilterNotifyRenameOrMoveFileEventArgs) NewFileName() string
func (args *CBFilterNotifyRenameOrMoveFileEventArgs) Status() int32
func (args *CBFilterNotifyRenameOrMoveFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyRenameOrMoveFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyRenameOrMoveFileEvent defines the signature of the CBFilter NotifyRenameOrMoveFile event's handler function.
type CBFilterNotifyRenameOrMoveFileEvent func(sender *CBFilter, args *CBFilterNotifyRenameOrMoveFileEventArgs)
func (obj *CBFilter) GetOnNotifyRenameOrMoveFileHandler() CBFilterNotifyRenameOrMoveFileEvent
func (obj *CBFilter) SetOnNotifyRenameOrMoveFileHandler(handlerFunc CBFilterNotifyRenameOrMoveFileEvent)
Remarks
This event fires when a file or directory specified by FileName has been renamed or moved to NewFileName.
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 filenames, 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetAllocationSize Event (CBFilter Component)
This event fires when a file's allocation size has been changed.
Syntax
// CBFilterNotifySetAllocationSizeEventArgs carries the CBFilter NotifySetAllocationSize event's parameters.
type CBFilterNotifySetAllocationSizeEventArgs struct {...}
func (args *CBFilterNotifySetAllocationSizeEventArgs) FileName() string
func (args *CBFilterNotifySetAllocationSizeEventArgs) AllocationSize() int64
func (args *CBFilterNotifySetAllocationSizeEventArgs) Status() int32
func (args *CBFilterNotifySetAllocationSizeEventArgs) ResultCode() int32
func (args *CBFilterNotifySetAllocationSizeEventArgs) SetResultCode(value int32)
// CBFilterNotifySetAllocationSizeEvent defines the signature of the CBFilter NotifySetAllocationSize event's handler function.
type CBFilterNotifySetAllocationSizeEvent func(sender *CBFilter, args *CBFilterNotifySetAllocationSizeEventArgs)
func (obj *CBFilter) GetOnNotifySetAllocationSizeHandler() CBFilterNotifySetAllocationSizeEvent
func (obj *CBFilter) SetOnNotifySetAllocationSizeHandler(handlerFunc CBFilterNotifySetAllocationSizeEvent)
Remarks
This event fires when the allocation size of the file specified by FileName has been changed.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetEa Event (CBFilter Component)
This event fires when information about the extended attributes of a file has been changed.
Syntax
// CBFilterNotifySetEaEventArgs carries the CBFilter NotifySetEa event's parameters.
type CBFilterNotifySetEaEventArgs struct {...}
func (args *CBFilterNotifySetEaEventArgs) FileName() string
func (args *CBFilterNotifySetEaEventArgs) Buffer() []byte
func (args *CBFilterNotifySetEaEventArgs) BufferLength() int32
func (args *CBFilterNotifySetEaEventArgs) Status() int32
func (args *CBFilterNotifySetEaEventArgs) ResultCode() int32
func (args *CBFilterNotifySetEaEventArgs) SetResultCode(value int32)
// CBFilterNotifySetEaEvent defines the signature of the CBFilter NotifySetEa event's handler function.
type CBFilterNotifySetEaEvent func(sender *CBFilter, args *CBFilterNotifySetEaEventArgs)
func (obj *CBFilter) GetOnNotifySetEaHandler() CBFilterNotifySetEaEvent
func (obj *CBFilter) SetOnNotifySetEaHandler(handlerFunc CBFilterNotifySetEaEvent)
Remarks
This event fires when information about the extended attributes of a file specified by FileName has been changed.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetFileAttributes Event (CBFilter Component)
This event fires when a file or directory's attributes or times have been changed.
Syntax
// CBFilterNotifySetFileAttributesEventArgs carries the CBFilter NotifySetFileAttributes event's parameters.
type CBFilterNotifySetFileAttributesEventArgs struct {...}
func (args *CBFilterNotifySetFileAttributesEventArgs) FileName() string
func (args *CBFilterNotifySetFileAttributesEventArgs) CreationTime() time.Time
func (args *CBFilterNotifySetFileAttributesEventArgs) LastAccessTime() time.Time
func (args *CBFilterNotifySetFileAttributesEventArgs) LastWriteTime() time.Time
func (args *CBFilterNotifySetFileAttributesEventArgs) ChangeTime() time.Time
func (args *CBFilterNotifySetFileAttributesEventArgs) Attributes() int32
func (args *CBFilterNotifySetFileAttributesEventArgs) Status() int32
func (args *CBFilterNotifySetFileAttributesEventArgs) ResultCode() int32
func (args *CBFilterNotifySetFileAttributesEventArgs) SetResultCode(value int32)
// CBFilterNotifySetFileAttributesEvent defines the signature of the CBFilter NotifySetFileAttributes event's handler function.
type CBFilterNotifySetFileAttributesEvent func(sender *CBFilter, args *CBFilterNotifySetFileAttributesEventArgs)
func (obj *CBFilter) GetOnNotifySetFileAttributesHandler() CBFilterNotifySetFileAttributesEvent
func (obj *CBFilter) SetOnNotifySetFileAttributesHandler(handlerFunc CBFilterNotifySetFileAttributesEvent)
Remarks
This event fires when the attributes or times of the file or directory specified by FileName have been changed.
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 in UTC. A value of January 1, 1601 00:00:00 UTC 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetFileInfo Event (CBFilter Component)
This event fires when information about a file or directory has been changed.
Syntax
// CBFilterNotifySetFileInfoEventArgs carries the CBFilter NotifySetFileInfo event's parameters.
type CBFilterNotifySetFileInfoEventArgs struct {...}
func (args *CBFilterNotifySetFileInfoEventArgs) FileName() string
func (args *CBFilterNotifySetFileInfoEventArgs) FileInformationClass() int32
func (args *CBFilterNotifySetFileInfoEventArgs) Buffer() []byte
func (args *CBFilterNotifySetFileInfoEventArgs) BufferLength() int32
func (args *CBFilterNotifySetFileInfoEventArgs) ValidBytes() int32
func (args *CBFilterNotifySetFileInfoEventArgs) Status() int32
func (args *CBFilterNotifySetFileInfoEventArgs) ResultCode() int32
func (args *CBFilterNotifySetFileInfoEventArgs) SetResultCode(value int32)
// CBFilterNotifySetFileInfoEvent defines the signature of the CBFilter NotifySetFileInfo event's handler function.
type CBFilterNotifySetFileInfoEvent func(sender *CBFilter, args *CBFilterNotifySetFileInfoEventArgs)
func (obj *CBFilter) GetOnNotifySetFileInfoHandler() CBFilterNotifySetFileInfoEvent
func (obj *CBFilter) SetOnNotifySetFileInfoHandler(handlerFunc CBFilterNotifySetFileInfoEvent)
Remarks
This event fires when information about a file or directory specified by FileName has been changed; 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetFileSecurity Event (CBFilter Component)
This event fires when a file or directory's security attributes have been changed.
Syntax
// CBFilterNotifySetFileSecurityEventArgs carries the CBFilter NotifySetFileSecurity event's parameters.
type CBFilterNotifySetFileSecurityEventArgs struct {...}
func (args *CBFilterNotifySetFileSecurityEventArgs) FileName() string
func (args *CBFilterNotifySetFileSecurityEventArgs) SecurityInformation() int32
func (args *CBFilterNotifySetFileSecurityEventArgs) SecurityDescriptor() []byte
func (args *CBFilterNotifySetFileSecurityEventArgs) Length() int32
func (args *CBFilterNotifySetFileSecurityEventArgs) Status() int32
func (args *CBFilterNotifySetFileSecurityEventArgs) ResultCode() int32
func (args *CBFilterNotifySetFileSecurityEventArgs) SetResultCode(value int32)
// CBFilterNotifySetFileSecurityEvent defines the signature of the CBFilter NotifySetFileSecurity event's handler function.
type CBFilterNotifySetFileSecurityEvent func(sender *CBFilter, args *CBFilterNotifySetFileSecurityEventArgs)
func (obj *CBFilter) GetOnNotifySetFileSecurityHandler() CBFilterNotifySetFileSecurityEvent
func (obj *CBFilter) SetOnNotifySetFileSecurityHandler(handlerFunc CBFilterNotifySetFileSecurityEvent)
Remarks
This event fires when security attributes have been changed for a file or directory specified by FileName.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetFileSize Event (CBFilter Component)
This event fires when a file has been resized.
Syntax
// CBFilterNotifySetFileSizeEventArgs carries the CBFilter NotifySetFileSize event's parameters.
type CBFilterNotifySetFileSizeEventArgs struct {...}
func (args *CBFilterNotifySetFileSizeEventArgs) FileName() string
func (args *CBFilterNotifySetFileSizeEventArgs) Size() int64
func (args *CBFilterNotifySetFileSizeEventArgs) Status() int32
func (args *CBFilterNotifySetFileSizeEventArgs) ResultCode() int32
func (args *CBFilterNotifySetFileSizeEventArgs) SetResultCode(value int32)
// CBFilterNotifySetFileSizeEvent defines the signature of the CBFilter NotifySetFileSize event's handler function.
type CBFilterNotifySetFileSizeEvent func(sender *CBFilter, args *CBFilterNotifySetFileSizeEventArgs)
func (obj *CBFilter) GetOnNotifySetFileSizeHandler() CBFilterNotifySetFileSizeEvent
func (obj *CBFilter) SetOnNotifySetFileSizeHandler(handlerFunc CBFilterNotifySetFileSizeEvent)
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).
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifySetReparsePoint Event (CBFilter Component)
This event fires when a file or directory's reparse point has been created or updated.
Syntax
// CBFilterNotifySetReparsePointEventArgs carries the CBFilter NotifySetReparsePoint event's parameters.
type CBFilterNotifySetReparsePointEventArgs struct {...}
func (args *CBFilterNotifySetReparsePointEventArgs) FileName() string
func (args *CBFilterNotifySetReparsePointEventArgs) ReparseTag() int64
func (args *CBFilterNotifySetReparsePointEventArgs) Status() int32
func (args *CBFilterNotifySetReparsePointEventArgs) ResultCode() int32
func (args *CBFilterNotifySetReparsePointEventArgs) SetResultCode(value int32)
// CBFilterNotifySetReparsePointEvent defines the signature of the CBFilter NotifySetReparsePoint event's handler function.
type CBFilterNotifySetReparsePointEvent func(sender *CBFilter, args *CBFilterNotifySetReparsePointEventArgs)
func (obj *CBFilter) GetOnNotifySetReparsePointHandler() CBFilterNotifySetReparsePointEvent
func (obj *CBFilter) SetOnNotifySetReparsePointHandler(handlerFunc CBFilterNotifySetReparsePointEvent)
Remarks
This event fires when a reparse point has been created or updated for a file or directory specified by FileName.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyUnlockAll Event (CBFilter Component)
This event fires when all locked byte ranges in a file have been unlocked.
Syntax
// CBFilterNotifyUnlockAllEventArgs carries the CBFilter NotifyUnlockAll event's parameters.
type CBFilterNotifyUnlockAllEventArgs struct {...}
func (args *CBFilterNotifyUnlockAllEventArgs) FileName() string
func (args *CBFilterNotifyUnlockAllEventArgs) Status() int32
func (args *CBFilterNotifyUnlockAllEventArgs) ResultCode() int32
func (args *CBFilterNotifyUnlockAllEventArgs) SetResultCode(value int32)
// CBFilterNotifyUnlockAllEvent defines the signature of the CBFilter NotifyUnlockAll event's handler function.
type CBFilterNotifyUnlockAllEvent func(sender *CBFilter, args *CBFilterNotifyUnlockAllEventArgs)
func (obj *CBFilter) GetOnNotifyUnlockAllHandler() CBFilterNotifyUnlockAllEvent
func (obj *CBFilter) SetOnNotifyUnlockAllHandler(handlerFunc CBFilterNotifyUnlockAllEvent)
Remarks
This event fires when all locked byte ranges in the file specified by FileName have been unlocked.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyUnlockAllByKey Event (CBFilter Component)
This event fires when all locked byte ranges in a file, associated with a particular key, have been unlocked.
Syntax
// CBFilterNotifyUnlockAllByKeyEventArgs carries the CBFilter NotifyUnlockAllByKey event's parameters.
type CBFilterNotifyUnlockAllByKeyEventArgs struct {...}
func (args *CBFilterNotifyUnlockAllByKeyEventArgs) FileName() string
func (args *CBFilterNotifyUnlockAllByKeyEventArgs) Key() int64
func (args *CBFilterNotifyUnlockAllByKeyEventArgs) Status() int32
func (args *CBFilterNotifyUnlockAllByKeyEventArgs) ResultCode() int32
func (args *CBFilterNotifyUnlockAllByKeyEventArgs) SetResultCode(value int32)
// CBFilterNotifyUnlockAllByKeyEvent defines the signature of the CBFilter NotifyUnlockAllByKey event's handler function.
type CBFilterNotifyUnlockAllByKeyEvent func(sender *CBFilter, args *CBFilterNotifyUnlockAllByKeyEventArgs)
func (obj *CBFilter) GetOnNotifyUnlockAllByKeyHandler() CBFilterNotifyUnlockAllByKeyEvent
func (obj *CBFilter) SetOnNotifyUnlockAllByKeyHandler(handlerFunc CBFilterNotifyUnlockAllByKeyEvent)
Remarks
This event fires when all locked byte ranges in the file specified by FileName, and associated with the specified Key, have been unlocked.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyUnlockSingle Event (CBFilter Component)
This event fires when a particular locked byte range in a file has been unlocked.
Syntax
// CBFilterNotifyUnlockSingleEventArgs carries the CBFilter NotifyUnlockSingle event's parameters.
type CBFilterNotifyUnlockSingleEventArgs struct {...}
func (args *CBFilterNotifyUnlockSingleEventArgs) FileName() string
func (args *CBFilterNotifyUnlockSingleEventArgs) Offset() int64
func (args *CBFilterNotifyUnlockSingleEventArgs) Length() int64
func (args *CBFilterNotifyUnlockSingleEventArgs) Key() int64
func (args *CBFilterNotifyUnlockSingleEventArgs) Status() int32
func (args *CBFilterNotifyUnlockSingleEventArgs) ResultCode() int32
func (args *CBFilterNotifyUnlockSingleEventArgs) SetResultCode(value int32)
// CBFilterNotifyUnlockSingleEvent defines the signature of the CBFilter NotifyUnlockSingle event's handler function.
type CBFilterNotifyUnlockSingleEvent func(sender *CBFilter, args *CBFilterNotifyUnlockSingleEventArgs)
func (obj *CBFilter) GetOnNotifyUnlockSingleHandler() CBFilterNotifyUnlockSingleEvent
func (obj *CBFilter) SetOnNotifyUnlockSingleHandler(handlerFunc CBFilterNotifyUnlockSingleEvent)
Remarks
This event fires when a particular locked byte range in a file specified by FileName has been unlocked.
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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
NotifyWriteFile Event (CBFilter Component)
This event fires when data have been written to a file.
Syntax
// CBFilterNotifyWriteFileEventArgs carries the CBFilter NotifyWriteFile event's parameters.
type CBFilterNotifyWriteFileEventArgs struct {...}
func (args *CBFilterNotifyWriteFileEventArgs) FileName() string
func (args *CBFilterNotifyWriteFileEventArgs) Position() int64
func (args *CBFilterNotifyWriteFileEventArgs) BytesToWrite() int32
func (args *CBFilterNotifyWriteFileEventArgs) Direction() int32
func (args *CBFilterNotifyWriteFileEventArgs) BytesWritten() int32
func (args *CBFilterNotifyWriteFileEventArgs) Status() int32
func (args *CBFilterNotifyWriteFileEventArgs) ResultCode() int32
func (args *CBFilterNotifyWriteFileEventArgs) SetResultCode(value int32)
// CBFilterNotifyWriteFileEvent defines the signature of the CBFilter NotifyWriteFile event's handler function.
type CBFilterNotifyWriteFileEvent func(sender *CBFilter, args *CBFilterNotifyWriteFileEventArgs)
func (obj *CBFilter) GetOnNotifyWriteFileHandler() CBFilterNotifyWriteFileEvent
func (obj *CBFilter) SetOnNotifyWriteFileHandler(handlerFunc CBFilterNotifyWriteFileEvent)
Remarks
This event fires when data have been written to the file specified by FileName.
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_NONCACHED | 0 | Operations performed in the user mode application <--> filesystem direction. |
| FS_REQUEST_DIR_USER_CACHED | 1 | Operations performed in the user mode application <--> system cache direction. |
| FS_REQUEST_DIR_SYSTEM_NONCACHED | 2 | Operations performed in the system cache <--> filesystem direction. |
| FS_REQUEST_DIR_SYSTEM_CACHED | 3 | Operations 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 Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.
ReparseFileName Event (CBFilter Component)
This event fires to allow file access to be dynamically redirected to another location.
Syntax
// CBFilterReparseFileNameEventArgs carries the CBFilter ReparseFileName event's parameters.
type CBFilterReparseFileNameEventArgs struct {...}
func (args *CBFilterReparseFileNameEventArgs) FileName() string
func (args *CBFilterReparseFileNameEventArgs) DesiredAccess() int32
func (args *CBFilterReparseFileNameEventArgs) ReparsedFileName() string
func (args *CBFilterReparseFileNameEventArgs) NewFileName() string
func (args *CBFilterReparseFileNameEventArgs) SetNewFileName(value string)
func (args *CBFilterReparseFileNameEventArgs) ResultCode() int32
func (args *CBFilterReparseFileNameEventArgs) SetResultCode(value int32)
// CBFilterReparseFileNameEvent defines the signature of the CBFilter ReparseFileName event's handler function.
type CBFilterReparseFileNameEvent func(sender *CBFilter, args *CBFilterReparseFileNameEventArgs)
func (obj *CBFilter) GetOnReparseFileNameHandler() CBFilterReparseFileNameEvent
func (obj *CBFilter) SetOnReparseFileNameHandler(handlerFunc CBFilterReparseFileNameEvent)
Remarks
Applications can use this event to dynamically redirect access to the file or directory specified by FileName to another location.
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.
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 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
ReparseWithTag Event (CBFilter Component)
This event fires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point.
Syntax
// CBFilterReparseWithTagEventArgs carries the CBFilter ReparseWithTag event's parameters.
type CBFilterReparseWithTagEventArgs struct {...}
func (args *CBFilterReparseWithTagEventArgs) FileName() string
func (args *CBFilterReparseWithTagEventArgs) NewFileName() string
func (args *CBFilterReparseWithTagEventArgs) ReparseTag() int32
func (args *CBFilterReparseWithTagEventArgs) ReparseBuffer() []byte
func (args *CBFilterReparseWithTagEventArgs) ReparseBufferLength() int32
func (args *CBFilterReparseWithTagEventArgs) ReissueIO() bool
func (args *CBFilterReparseWithTagEventArgs) SetReissueIO(value bool)
func (args *CBFilterReparseWithTagEventArgs) ResultCode() int32
func (args *CBFilterReparseWithTagEventArgs) SetResultCode(value int32)
// CBFilterReparseWithTagEvent defines the signature of the CBFilter ReparseWithTag event's handler function.
type CBFilterReparseWithTagEvent func(sender *CBFilter, args *CBFilterReparseWithTagEventArgs)
func (obj *CBFilter) GetOnReparseWithTagHandler() CBFilterReparseWithTagEvent
func (obj *CBFilter) SetOnReparseWithTagHandler(handlerFunc CBFilterReparseWithTagEvent)
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.
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 component 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 filename 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
WorkerThreadCreation Event (CBFilter Component)
Fires just after a new worker thread is created.
Syntax
// CBFilterWorkerThreadCreationEventArgs carries the CBFilter WorkerThreadCreation event's parameters.
type CBFilterWorkerThreadCreationEventArgs struct {...}
func (args *CBFilterWorkerThreadCreationEventArgs) ResultCode() int32
func (args *CBFilterWorkerThreadCreationEventArgs) SetResultCode(value int32)
// CBFilterWorkerThreadCreationEvent defines the signature of the CBFilter WorkerThreadCreation event's handler function.
type CBFilterWorkerThreadCreationEvent func(sender *CBFilter, args *CBFilterWorkerThreadCreationEventArgs)
func (obj *CBFilter) GetOnWorkerThreadCreationHandler() CBFilterWorkerThreadCreationEvent
func (obj *CBFilter) SetOnWorkerThreadCreationHandler(handlerFunc CBFilterWorkerThreadCreationEvent)
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 component 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 Reporting and Handling topic for more information.
This event is fired synchronously; please refer to the Event Types topic for more information.
WorkerThreadTermination Event (CBFilter Component)
Fires just before a worker thread is terminated.
Syntax
// CBFilterWorkerThreadTerminationEventArgs carries the CBFilter WorkerThreadTermination event's parameters.
type CBFilterWorkerThreadTerminationEventArgs struct {...}
// CBFilterWorkerThreadTerminationEvent defines the signature of the CBFilter WorkerThreadTermination event's handler function.
type CBFilterWorkerThreadTerminationEvent func(sender *CBFilter, args *CBFilterWorkerThreadTerminationEventArgs)
func (obj *CBFilter) GetOnWorkerThreadTerminationHandler() CBFilterWorkerThreadTerminationEvent
func (obj *CBFilter) SetOnWorkerThreadTerminationHandler(handlerFunc CBFilterWorkerThreadTerminationEvent)
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 component 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.
CBFSFilterStream Type
Syntax
cbfsfilter.CBFSFilterStream
Remarks
The CBFSFilterStream type is returned by some of the CBFilter component's methods. All stream types in CBFS Filter share a common API, which implements multiple interfaces from Go's io package, documented below.
Properties | |
| Length |
Gets or sets the length of the stream, in bytes.
func (obj *CBFSFilterStream) GetLength() (int64, error) |
| Position |
Gets or sets the current position within the stream.
func (obj *CBFSFilterStream) GetPosition() (int64, error) |
Methods | |
| Close |
Closes the stream. Has no effect if the stream is already closed.
func (obj *CBFSFilterStream) Close() error |
| Flush |
Forces all data held by the stream's buffers to be written out to storage.
func (obj *CBFSFilterStream) Flush() error |
| Read |
Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read.
func (obj *CBFSFilterStream) Read(p []byte) (n int, err error) Up to len(p) bytes will be read from the stream into p. Fewer than len(p) bytes may be read if fewer than len(p) bytes are available. Returns the number of bytes read in n, and any error encountered (including, but not limited to, EOF) in err. |
| ReadByte |
Reads and returns the next byte from the stream or any error encountered.
func (obj *CBFSFilterStream) ReadByte() (byte, error) |
| Seek |
Sets the current position within the stream based on a particular point of origin.
func (obj *CBFSFilterStream) Seek(offset int64, whence int) (int64, error) Returns the new offset relative to the start of the stream, and any error encountered. |
| Write |
Writes a sequence of bytes to the stream and advances the current position within the stream by the number of bytes written.
func (obj *CBFSFilterStream) Write(p []byte) (n int, err error) Writes len(p) bytes to the stream. Returns the number of bytes written in n, and any error encountered in err. |
| WriteByte |
Writes a single byte to the stream and returns any error encountered.
func (obj *CBFSFilterStream) WriteByte(c byte) error |
Config Settings (CBFilter Component)
The component 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 component, access to these internal properties is provided through the Config method.CBFilter Config Settings
By default, this configuration setting is disabled, because it requires the component's system driver to perform extra system calls when a file is being created or opened (which may negatively affect performance in some cases).
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.
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.
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.
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).
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.
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.
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.
This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.
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.
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.
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.
By default this setting is disabled.
Note: This setting cannot be changed when Active is true, and it cannot be changed within events.
Note: This setting cannot be changed within events.
When a file or directory is first opened, the component'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.
- 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.
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.
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.
- 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 component 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."
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
- 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 Component)
The component uses Windows error codes during operations as necessary. Please refer to the Error Reporting and Handling topic for more information.Special Use Errors
| 21 ERROR_NOT_READY: Reported by the methods of the component if Initialize has not been called or did not succeed. | |
| 575 ERROR_APP_INIT_FAILURE: Reported by the methods of the component 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. |