CBFS Storage 2020 Node.js Edition

Questions / Feedback?

CBDisk Class

Properties   Methods   Events   Configuration Settings   Errors  

The CBDisk class lets applications create a virtual disk backed by a contiguous block of data.

Syntax

cbfsstorage.cbdisk()

Remarks

The CBDisk class is used to create a virtual disk whose contents are stored in one contiguous block of data. CBDisk doesn't implement any filesystem functionality, nor does it attempt to process virtual disks' contents in any way; its minimal API is focused wholly on the efficient transfer of raw disk data.

Therefore, a CBDisk-based application's only responsibility is to maintain a finite block of data for each virtual disk, reading from and writing to it as instructed by the class. This block of data functions as a virtual disk's storage space, and it can be located anywhere the application desires.

Newly-created virtual disks begin in a raw state, and must be formatted with a known filesystem (e.g., NTFS, FAT32, exFAT, etc.) using standard Windows formatting utilities. Once a virtual disk has been formatted, it can be used just like any other storage device. When the application is finished with a virtual disk, the block of data associated with it can be saved so that the virtual disk can be "re-created" at a later time.

The CBDisk class can be used in applications for Windows operating system.

Getting Started

Each CBDisk class instance controls a single virtual disk. Applications can use multiple instances of the CBDisk class if their use-case requires the creation of multiple virtual disks. The class's Tag property can be used to distinguish between instances during event handlers by storing some disk-specific information ("disk context") or UID.

Here's how to get up and running:

  1. If the system driver hasn't been installed yet, call the Install method to do so. This only needs to be done once.
    • In production, the system driver can be installed (or updated) ahead-of-time by the application's installation script using the Installer DLL. Please refer to the Driver Installation in Windows topic for more information.
  2. Call the Initialize method to initialize the CBDisk class. This must be done each time the application starts (if the application is using multiple CBDisk class instances, only the first instance created should be used to call Initialize).
  3. Ensure that the class's event handlers have been implemented so that the driver can read and write raw disk data. Please refer to the events' documentation for more information.
  4. Create a virtual disk by calling the CreateStorage method.
  5. Create one or more Mounting Points for the virtual disk using the AddMountingPoint method. A mounting point can be a drive letter, a UNC path, or a directory on an existing NTFS-formatted drive.
  6. Call the MountMedia method to "insert storage media" into the virtual disk drive. (This "media" can be changed at any time later using the UnmountMedia and MountMedia methods.)
  7. Later, the application can unmount the "media" from the virtual disk using the UnmountMedia method. At this point, the application could call the MountMedia method again to "insert different storage media".
  8. To delete the virtual disk entirely, call the DeleteStorage method.
  9. To uninstall the system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
    • In production, the system driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation in Windows topic for more information.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

ActiveWhether the class is active and handling OS requests.
MountingPointCountThe number of records in the MountingPoint arrays.
MountingPointAuthenticationIdThe Authentication ID used when creating the mounting point, if applicable.
MountingPointFlagsThe flags used to create the mounting point.
MountingPointNameThe mounting point name.
ReadOnlyWhether the virtual drive should be mounted in read-only mode.
StorageCharacteristicsThe characteristic flags to create the virtual drive with. (Windows only).
StorageGUIDThe GUID to create the virtual drive with.
StoragePresentWhether a virtual drive has been created.
StorageTypeThe type of virtual drive to create. (Windows only).
TagStores application-defined data specific to this instance of the class.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

AddMountingPointAdds a mounting point for the virtual drive.
ConfigSets or retrieves a configuration setting.
CreateStorageCreates the virtual drive.
DeleteStorageDeletes the virtual drive.
GetDriverStatusRetrieves the status of the system driver.
GetModuleVersionRetrieves the version of a given product module.
InitializeInitializes the class.
InstallInstalls (or upgrades) the product's system drivers and/or helper DLL. (Windows only).
IsIconRegisteredChecks whether the specified icon is registered.
MountMediaMounts media in the virtual drive, making it accessible for reading and writing.
RegisterIconRegisters an icon that can be displayed as an overlay on the virtual drive in Windows Explorer.
RemoveMountingPointRemoves a mounting point for the virtual drive.
ResetIconResets the virtual drive's icon back to default by deselecting the active overlay icon.
SetIconSelects a registered overlay icon for display on the virtual drive in Windows Explorer.
ShutdownSystemShuts down or reboots the operating system.
UninstallUninstalls the product's system drivers and/or helper DLL. (Windows only).
UnmountMediaUnmounts media from the virtual drive.
UnregisterIconUnregisters an existing overlay icon.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

DiskReadFires when the OS needs to read data from the virtual disk.
DiskWriteFires when the OS needs to write data to the virtual disk.
EjectedFires when the media and virtual drive have been ejected.
ErrorFires if an unhandled error occurs during an event.
GetDiskSizeFires when the OS needs to retrieve the size of the virtual disk.

Configuration Settings


The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.

AsyncDeleteStorageNotificationsWhether system broadcasts for virtual drive deletion are sent asynchronously.
DeviceChangeBroadcastsEnabledWhether the user-mode API broadcasts WM_DEVICECHANGE messages.
LoggingEnabledWhether extended logging is enabled.
SectorSizeThe sector size to create the virtual drive with.
SupportSearchIndexerSpecifies whether the driver must take additional measures to support indexing by Windows Search.
VolumeGuidNameThe GUID of the mounted volume.

Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 Node.js Edition - Version 20.0 [Build 7922]