Deployment (Operating System Edition, Windows platform)

Installation of the drivers and Helper DLLs

All versions of the kernel-mode driver and all Helper DLLs are packed to a single CAB file named cbfsstorage.cab, which should be installed to the target system. The cbfsstorage.cab file is located in the Drivers subdirectory of the directory, to which you have installed CBFS Storage on your development system.

The driver and the Helper DLLs can be installed using the functions exported by Installer DLL that is included within CBFS Storage. This DLL can be freely distributed with your projects as long as it is used with the licensed version of CBFS Storage.

To install or uninstall the drivers from your main application, use the calls in CBFS Storage API: Install and Uninstall or UninstallEx.

Windows requires system restart after installation or deinstallation of plug-n-play drivers, so restart is needed if you install drivers in PnP mode.

If you install one or both helper DLLs, they must be loaded by Explorer during its startup. So to ensure proper user experience Install function returns RebootNeeded set accordingly to have the system restarted and the DLLs loaded.

Note, that Uninstall or UninstallEx function should be used only to completely uninstall the driver and helper DLLs. Don't use these functions if you are updating the version of CBFS Storage on a target system. If you use Uninstall or UninstallEx and then attempt to install the updated version without restarting the system, you can either get an error or restart will cause the OS to delete the newly installed files (the OS treats these files as the ones that must be uninstalled). This remark is not applicable, when you upgrade CBFS Storage from the lower major version (2015 or 2016) to the higher version (2017 or 2018 accordingly): higher major versions are treated as different products and they don't update lower versions.

After you install the CAB file, you need to keep a copy of this file on the destination system, because deinstallation of the files also requires the CAB archive to be present.

Required Permissions

By default, installation and deinstallation of CBFS Storage files (kernel-mode drivers and Helper DLLs) can be performed from the user account, which belongs to Administrators group. This is a security measure of Windows operating system. You can change this behaviour on the target system by adjusting the list of users and groups that have the right to install and uninstall the drivers. This can be done in Control Panel -> Administrative tools -> Local Security Settings -> Local Policies \ User Rights Assignment (tree branch), there you need to change "Load and Unload device drivers" item. No need to say that by default, you can change the security settings, if you are system administrator.

Notes for Vista and later versions of Windows

If you have UAC (User Account Control) enabled, Vista and later versions of Windows will run applications started by you with limited rights even when you are logged in as the administrator or a member of Administrators group.

If you install or uninstall the drivers by calling the above mentioned functions in your code, you need to elevate privileges of your application so that it's started with truly administrative rights.

To elevate privileges for your application, you must start it with Run As Administrator option. In Windows Explorer, this is done using Run As Administrator command in the context menu for the application. Alternatively, you can set the corresponding option in the Properties window, shown for your executable module.

One more option is to use the manifest. The manifest file can be placed next to the executable of your application or embedded into the executable. If you decide to keep the manifest in a separate file, it must be named <EXEName_with_extension>.manifest, eg. for MyApp.exe the manifest should be called MyApp.exe.manifest.

You can use the following manifest:

<?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>

User-mode API

CBFS Storage user-mode API is shipped as .NET assemblies, static and dynamic library for Visual C++, and VCL units.

  • .NET API:
    When deploying the project, copy CBFSStorageOS2017.dll to your application folder. Questions about when and how to install the assemblies to Global Assembly Cache are discussed in Working with Assemblies and the Global Assembly Cache and How to: Install an Assembly into the Global Assembly Cache articles.

    The .NET assemblies are offered in one form that does not depend on MS VC Runtime, but requires an unmanaged CBFSStorageOS.dll instead. The unmanaged DLL, CBFSStorageOS.dll, is located next to the assembly.

    .NET assemblies must be deployed by copying CBFSStorageOS.dll and CBFSStorageOS2017.dll from "<CBFS Storage>\.NET" folder together with your application files. CBFSStorageOS.dll must be placed next to the main EXE of your application.
  • C++ API:
    To deploy CBFS Storage in the case of dynamic linkage, just copy CBFSStorageOS.dll together with your application files. The DLL is located in "<CBFS Storage>\Win32\DynamicLib" or "<CBFS Storage>\Win_x64\DynamicLib" folders (for Win32 and Win64 platforms).
    No deployment is needed in the case of static linkage of the C++ library.

  • VCL API:
    32-bit VCL unit for Delphi and C++Builder links CBFS Storage API statically so no deployment is required. 64-bit VCL units require CBFSStorageOS.dll to be deployed together with your application files.