CBFS Filter 2020 C++ Builder Edition

Questions / Feedback?

CBFilter Configuration

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 Configuration Settings

AllowFileAccessInBeforeOpen:   Whether file access, via the CreateFileDirect method, is allowed in during the BeforeCreateFile and BeforeOpenFile events.

This setting specifies whether the component should allow the CreateFileDirect method to be used to access a file during the BeforeCreateFile and/or BeforeOpenFile event fired for it. When this setting is enabled, the CreateFileDirect method may be called in synchronized mode during the aforementioned methods; please refer to its documentation for more information.

By default, this setting is disabled, since it requires the component's system driver to perform extra system calls when a file is being created or opened (which may negatively impact performance in some cases).

AlwaysPrepareFiles:   Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the component is initialized.

This setting corresponds to the INSTALL_ALWAYS_PREPARE_FILES flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

CacheRemoteFilesLocally:   Whether remote files involved in filtered operations should be cached locally rather than remotely.

Applications that need to perform on-the-fly data modifications (e.g., encryption) on remote files should enable this setting; it is disabled by default.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

FilterOwnRequests:   Whether the component's system driver should filter requests made by the application itself.

This setting specifies whether requests made by the application itself should be filtered through the component's system driver (assuming that they match one of the rules present at the time). When this setting is disabled (default), and the application performs some operation that would match an existing rule, the driver will explicitly ignore it.

This setting should normally remain disabled (especially in production) in order to reduce the possibility of system deadlocks occurring. That said, there are certain situations that require it to be enabled, such as for testing purposes (so that event handlers can be tested with single-process tests).

ForceAppPermissionCheck:   Whether the driver should require the controller process to have elevated or system privileges.

This setting corresponds to the INSTALL_FORCE_APP_PERMISSION_CHECK flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

ForceSecurityChecks:   Whether the driver should prevent the controller process from filtering files that it would not normally have access to.

This setting corresponds to the INSTALL_FORCE_SECURITY_CHECKS flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

LoggingEnabled:   Whether extended logging is enabled.

This setting specifies whether extended logging is enabled for this component; it is disabled by default. Please refer to the Error Reporting and Handling topic for more information.

This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.

MaxWorkerThreadCount:   The maximum number of worker threads to use to fire events.

This setting specifies the maximum number of worker threads the component may create to fire events on when the SerializeEvents property is disabled. (If SerializeEvents is enabled, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: 4 * number_of_processors.

MinWorkerThreadCount:   The minimum number of worker threads to use to fire events.

This setting specifies the minimum number of worker threads the component should create to fire events on when the SerializeEvents property is disabled. (If SerializeEvents is enabled, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: max(number_of_processors, 4). If this setting's value exceeds the MaxWorkerThreadCount value, the latter is used instead.

ModifiableReadWriteBuffers:   Whether the driver should duplicate read/write buffers sent to the user.

This setting specifies whether the driver should duplicate the buffers exposed via the AfterReadFile, BeforeReadFile, and BeforeWriteFile events, allowing them to be modified by the application.

Applications that intend to modify these buffers' contents (e.g., for encryption, compression, or similar purposes) should enable this setting. All other applications should leave this setting disabled (the default) for better performance.

NotificationFetchBatchSize:   How many notification entries to transfer from the kernel to the user mode at once.

To speed up operations when Notification Events are used, the component will fetch notification information from the driver in batches; this setting controls how many entries are transferred in each batch.

By default, this setting is set to 64 entries; valid values are 1 to 1024 (inclusive). Keep in mind that larger values can lead to notification loss if the application crashes before it can process all of the notifications fetched in the most recent batch.

PreprocessedRulesCacheSize:   Maximum number of preprocessed rules to keep cached.

This setting specifies the maximum number of preprocessed rules that the component's system driver should keep cached; it is set to 1024 by default.

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, since they prevent the driver from having to re-check each rule every time an operation occurs.

ResolveNtDeviceToDriveLetter:   Whether native device names are translated to drive letters.

This setting specifies whether NT native device names, like \Device\HarddiskVolume1\..., should be translated to DOS-style drive letters, like C:\... when possible. However, please note that:

  • Such translation will only be performed if a device actually has a corresponding DOS-style drive letter; not all devices do.
  • The BeforeFilterAttachToVolume event always uses NT native device names, since 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 cannot be changed within events.

SendRequestsViaDriverStack:   Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers.

This setting corresponds to the INSTALL_REQUESTS_VIA_DRIVER_STACK flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

WorkerInitialStackSize:   The initial stack size to create worker threads with.

This property specifies the initial size of the stack each worker thread is created with. The system rounds this value to the nearest page.

By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).

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

Base Configuration Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g. RuntimeLicense, License File).
  • License Type: The type of license installed (e.g. Royalty Free, Single Server).

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