Install Method

Installs (or upgrades) the class's system driver.

Syntax

int Install(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iFilterMode, int iAltitude, int iFlags);
INT Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszPathToInstall, INT iFilterMode, INT iAltitude, INT iFlags);

Remarks

This method is used to install or upgrade the class's system driver. If the system must be rebooted to complete the installation process, this method returns true; otherwise, it returns false.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the cbfilter.cab file containing the class's system driver. Important: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required for uninstalling the driver from the system.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., 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.

FilterMode specifies whether the driver should operate in legacy mode or minifilter mode. After installation, the filter mode can be changed at any time using the FilterMode property. Possible values for this parameter are:

FS_FILTER_MODE_LEGACY0Use legacy filesystem filter mode.

Note: Legacy mode is obsolete; support for it is deprecated, and will be removed in a future product update. Please refer to the Minifilter and Legacy Modes topic for more information.

FS_FILTER_MODE_MINIFILTER1Use filesystem minifilter mode.

Altitude specifies the driver altitude to use when operating in minifilter mode. An altitude value must be assigned by Microsoft before deploying a filesystem minifilter in production; please refer to the Driver Altitudes topic for more information. After installation, the altitude can be changed at any time using the Altitude property.

Flags specifies various installation options, and should contain zero or more of the following flags, OR'd together:

INSTALL_REMOVE_OLD_VERSIONS0x00000001Uninstall drivers from previous class versions (e.g., 2017).

INSTALL_KEEP_START_TYPE0x00000002Keep the driver's current start type setting in the registry.

If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application itself) set it previously.

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

This flag is only applicable for CBFilter and CBMonitor.

After installation, the effects of this flag can be changed using the SendRequestsViaDriverStack configuration setting.

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

This flag is only applicable for CBFilter and CBMonitor.

If this flag is set, the driver will prepare information about each file as it is opened, regardless of whether a CBFilter/CBMonitor-based application is actually running at the time. This information then allows applications to receive events for any files that are already open when the CBFilter/CBMonitor class is initialized. Please note that these preparations will slow down all file open operations; don't enable this feature unless it's actually necessary.

After installation, the effects of this flag can be changed using the AlwaysPrepareFiles configuration setting.

INSTALL_FORCE_APP_PERMISSION_CHECK0x00020000Whether the driver should require the controller process to have elevated or system privileges.

This flag is only applicable for CBFilter and CBMonitor.

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). Please note that this additional verification will slow down all file open operations.

After installation, the effects of this flag can be changed using the ForceAppPermissionCheck configuration setting.

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

This flag is only applicable for CBFilter and CBMonitor.

If this flag is set, the driver will check the security permissions of the controller process anytime a file is opened in order to verify that the process itself 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. Please note that 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 that 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 class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

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

Note: This method cannot be called within events.

Error Handling (C++)

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

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