Driver Installation

At a high level, CBFS Connect consists of a kernel mode driver, a helper DLL, and a user mode API library; all of which work together in tandem to provide the product's functionality. Therefore, it is necessary to install the CBFS Connect kernel mode driver and helper DLL when deploying an application built with the CBFS Connect user mode API library.

The functionality needed to install the driver and helper DLL is included in the user mode API itself, as well as in a separate installer DLL. The drivers directory, located within the product's installation directory, contains the following files:

{ClassName}.cab Contains the filesystem driver, PnP bus driver, helper DLL, and the supplementary installation/uninstallation files.
installer/{ClassName}Inst.h A header file for the installer DLL. The installer DLL may be used on the target system to install (or uninstall) the items within {ClassName}.cab.
installer/x64/{ClassName}Inst.dll The 64-bit C/C++ installer DLL.
installer/x86/{ClassName}Inst.dll The 32-bit C/C++ installer DLL.

Installation and Uninstallation via User Mode (Class) API Methods

The user mode class APIs include the following methods to install and uninstall the required files; please refer to their documentation for more information:

Important: Uninstall must only be used when completely removing the driver. When updating the driver, this method must not be used as it may cause the OS to incorrectly remove the driver on reboot. Please refer to the "Updating the Driver" section, below, for more information.

Installation and Uninstallation via Installer DLL Functions

The installer DLL is a lightweight, stand-alone library that contains only the functionality required for installing and uninstalling the required files. It is available in both 32-bit and 64-bit versions (each of which is capable of installing both 32-bit and 64-bit drivers and helper DLLs); and may be used as desired in installation scripts, setup applications, or any other executable capable of loading dynamically-linked libraries (DLLs).

The functions exposed by the installer DLL mirror the class methods listed above. Each function is available in two forms: those with an *A suffix, which can be used with ANSI/UTF8 strings; and those with a *W suffix, which can be used with Unicode (UTF16) strings.

Updating the Driver

Only the Install method/function is required to update the driver; the new version of the driver will replace the older version. Do not call Uninstall when updating the driver.

Uninstalling the Driver

The driver should only be uninstalled when the intent is to completely remove it from the system; never uninstall the driver to upgrade it.

To uninstall the driver completely, call the Uninstall method/function; if the driver cannot be immediately uninstalled, it will be marked for removal and uninstalled on the next reboot. Use caution when calling Uninstall; if it gets called and the driver cannot be uninstalled immediately, and then Install is subsequently called to install a new version, then upon reboot, the OS will end up uninstalling the newly-installed driver.

Reboot Requirements

Depending on the current state of the system, as well as the options chosen when installing or uninstalling the driver, the OS may need to reboot to complete the operation.

For example, the helper DLL must be loaded by Windows Explorer when it starts, and a reboot is required for this to occur. Additionally, when installing or uninstalling the Plug-and-Play (PnP) drivers, a reboot is always required.

Always check the return value of the Install and Uninstall methods/functions; it will indicate whether a reboot is required (and if so, which module(s) required it).

Additional Notes

The OS treats major versions of the driver as separate products; they can operate in parallel and do not share any resources. Old major versions may optionally be removed from the system when calling Install by passing the appropriate value for its Flags parameter.

For each major version of the product, only one copy of the driver can be installed at any time. When the driver is being installed, its version is checked, and one of the following three things occurs:

  • If no driver with the same major version is currently installed, then the install procedure installs the driver as a new product.
  • If a driver with the same major version and an older minor version is currently installed, then the install procedure updates the existing driver with the new one.
  • If a driver with the same major version and a newer minor version is currently installed, then the install procedure leaves the existing driver unchanged.

When deploying files to a target system, the CAB file must remain present on the system. This file is required for uninstallation of the driver at a later time.

The product's installation code maintains a ProductGUID-based record of driver installations in the Windows Registry, creating a separate registry entry for each different ProductGUID. When the driver is "uninstalled", the corresponding registry entry is removed. The driver is only removed from the system if there are no entries left in the registry that reference the driver.

Required Permissions

By default, Windows only allows installation and uninstallation of the CBFS Connect files (kernel mode drivers and helper DLLs) to be performed from a user account which is a member of the Administrators group.

On systems where UAC is enabled, the process responsible for installing or uninstalling the drivers must run with elevated permissions. Detection of current privileges and elevation of permissions is not within the scope of the class itself.

Some examples of obtaining the required permissions for driver installation and uninstallation are below.

  • Starting the application which uses the class with the "Run as administrator" option.
  • Modifying the Load and unload device drivers setting in the Local Security Policy under the User Rights Assignment section.
  • Including a manifest alongside the application indicating the requirement for elevated permissions. For instance, if a file MyApp.exe.manifest with the content below exists next to the application MyApp.exe, it will prompt for elevated permissions when started (if required).


    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
      <assemblyIdentity version="1.0.0.0" processorArchitecture="X86" name="ExeName" type="win32"/>
      <description>elevate execution level</description>
      <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
        <security>
          <requestedPrivileges>
            <requestedExecutionLevel level="requireAdministrator" uiAccess="false"/>
          </requestedPrivileges>
        </security>
      </trustInfo>
    </assembly>

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