CBFS Disk 2022 .NET Edition
Version 22.0 [Build 8462]

CBDisk Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

callback.CBFSDisk.Cbdisk

Remarks

The CBDisk component 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 component. 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 component can be used in applications for Windows operating system.

Getting Started

Each CBDisk component instance controls a single virtual disk. Applications can use multiple instances of the CBDisk component if their use-case requires the creation of multiple virtual disks. The component'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 topic for more information.
  2. Call the Initialize method to initialize the CBDisk component. This must be done each time the application starts (if the application is using multiple CBDisk component instances, only the first instance created should be used to call Initialize).
  3. Ensure that the component'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 topic for more information.

Property List


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

ActiveWhether the component is active and handling OS requests.
MountingPointsCollection of mounting points for the virtual disk.
ReadOnlyWhether the virtual disk should be mounted in read-only mode.
StorageCharacteristicsThe characteristic flags to create the virtual disk with.
StorageGUIDThe GUID to create the virtual disk with.
StoragePresentWhether a virtual disk has been created.
StorageTypeThe type of virtual disk to create.
TagStores application-defined data specific to this instance of the component.

Method List


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

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

Event List


The following is the full list of the events fired by the component 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 disk have been ejected.
ErrorFires if an unhandled error occurs during an event.
FlushTBD.
GetDiskSizeFires when the OS needs to retrieve the size of the virtual disk.

Config Settings


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

AsyncDeleteStorageNotificationsWhether system broadcasts for virtual disk deletion are sent asynchronously.
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.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

Active Property (CBDisk Component)

Whether the component is active and handling OS requests.

Syntax

public bool Active { get; }
Public ReadOnly Property Active As Boolean

Default Value

False

Remarks

This property reflects whether the component is currently active and handling OS requests. Active will be true once both CreateStorage and MountMedia have been called.

This property is read-only and not available at design time.

MountingPoints Property (CBDisk Component)

Collection of mounting points for the virtual disk.

Syntax

public MountingPointList MountingPoints { get; }
Public ReadOnly Property MountingPoints As MountingPointList

Remarks

This property holds a collection of MountingPoint objects, each of which represents an available mounting point for the virtual disk.

Please refer to the AddMountingPoint and RemoveMountingPoint methods for more information.

Note: The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

This property is read-only and not available at design time.

ReadOnly Property (CBDisk Component)

Whether the virtual disk should be mounted in read-only mode.

Syntax

public bool ReadOnly { get; set; }
Public Property ReadOnly As Boolean

Default Value

False

Remarks

This property specifies whether the component should mount the virtual disk in read-only mode when MountMedia is called.

Note: This property cannot be changed when Active is true.

This property is not available at design time.

StorageCharacteristics Property (CBDisk Component)

The characteristic flags to create the virtual disk with.

Syntax

public int StorageCharacteristics { get; set; }
Public Property StorageCharacteristics As Integer

Default Value

16

Remarks

The system, as well as other applications, use these flags to optimize their use of the virtual disk. This property should be set by OR'ing together zero or more of the following flags:

STGC_FLOPPY_DISKETTE0x00000001The storage is a floppy disk device.

This flag is not supported when StorageType is set to STGT_DISK_PNP.

STGC_READONLY_DEVICE0x00000002The storage is a read-only device.

STGC_WRITE_ONCE_MEDIA0x00000008The storage device's media can only be written to once.

This flag is not supported when StorageType is set to STGT_DISK_PNP.

STGC_REMOVABLE_MEDIA0x00000010The storage device's media is removable.

Users may remove the storage media from the virtual drive at any time. (Note that this flag does not indicate that the virtual drive itself is removable.)

STGC_AUTOCREATE_DRIVE_LETTER0x00002000The system should automatically create a drive letter for the storage device.

Deprecated: Include the STGMP_AUTOCREATE_DRIVE_LETTER flag in the value passed for the AddMountingPoint method's Flags parameter instead.

When this flag is present, the StorageGUID property must be set. This flag only works when StorageType is set to STGT_DISK_PNP.

STGC_SHOW_IN_EJECTION_TRAY0x00004000The storage device should be shown in the 'Safely Remove Hardware and Eject Media' menu in the system notification area (system tray).

This flag only works when StorageType is set to STGT_DISK_PNP.

STGC_ALLOW_EJECTION0x00008000The storage device can be ejected.

Users may eject the virtual drive at any time. When the virtual drive is ejected, it is destroyed.

This flag only works when StorageType is set to STGT_DISK_PNP.

STGC_RESERVED_10x00010000Reserved, do not use.

STGC_RESERVED_20x00020000Reserved, do not use.

Note: This property cannot be changed after a virtual disk is created, and cannot be changed within events.

StorageGUID Property (CBDisk Component)

The GUID to create the virtual disk with.

Syntax

public string StorageGUID { get; set; }
Public Property StorageGUID As String

Default Value

""

Remarks

When the StorageType property is set to STGT_DISK_PNP, this property is used to specify a GUID for the virtual disk, and must be set to GUID-formatted string (e.g., {676D0357-A23A-49c3-B433-65AAD72DD282}). Otherwise, this property can be left empty.

Some software uses a disk's GUID for the purpose of setting and maintaining certain configuration parameters. Therefore, applications are expected to use the same GUID when repeatedly creating a virtual disk that represents the same data.

Note: This property cannot be changed after a virtual disk is created, and cannot be changed within events.

StoragePresent Property (CBDisk Component)

Whether a virtual disk has been created.

Syntax

public bool StoragePresent { get; }
Public ReadOnly Property StoragePresent As Boolean

Default Value

False

Remarks

This property reflects whether a virtual disk has been created; it is automatically updated by the component whenever the virtual disk's presence changes (e.g., due to calls to CreateStorage, DeleteStorage, etc.).

This property is read-only and not available at design time.

StorageType Property (CBDisk Component)

The type of virtual disk to create.

Syntax

public int StorageType { get; set; }
Public Property StorageType As Integer

Default Value

0

Remarks

This property specifies what type of virtual disk should be created. Windows Explorer uses this information to display the appropriate icon and apply the appropriate security settings for the virtual disk. Other applications may also make use of this information in various ways.

Possible values are:

STGT_DISK0x00000000Create a regular disk device.

STGT_CDROM0x00000001Create a CD-ROM or DVD device.

STGT_DISK_PNP0x00000003Create a plug-and-play storage device.

Important: The CBFS Disk system driver must be installed in PnP mode for this option to function properly.

Note: This property cannot be changed after a virtual disk is created, and cannot be changed within events.

Plug-and-play Virtual Drives

Virtual disks created as plug-and-play (STGT_DISK_PNP) require that a "physical device" be visible in the Disk Manager snap-in of the Microsoft Management Console (mmc.exe). This can be accomplished by calling the AddMountingPoint method and including the STGMP_MOUNT_MANAGER flag in the value passed for its Flags parameter.

In addition to supporting the STGC_REMOVABLE_MEDIA StorageCharacteristics flag, which specifies whether a virtual disk's media is removable or non-removable, plug-and-play virtual disks also support the STGC_ALLOW_EJECTION flag, which specifies whether a virtual disk itself is removable or non-removable.

Tag Property (CBDisk Component)

Stores application-defined data specific to this instance of the component.

Syntax

public long Tag { get; set; }
Public Property Tag As Long

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the component.

AddMountingPoint Method (CBDisk Component)

Adds a mounting point for the virtual disk.

Syntax

public void AddMountingPoint(string mountingPoint, int flags, long authenticationId);
Public Sub AddMountingPoint(ByVal MountingPoint As String, ByVal Flags As Integer, ByVal AuthenticationId As Long)

Remarks

This method adds a new mounting point for the virtual disk (which must have already been created using CreateStorage). Virtual disks may have as many mounting points as desired.

Typically, mounting points may be added before or after MountMedia is called. However, for plug-and-play virtual drives with non-removable media (see StorageType), AddMountingPoint must not be called until after the MountMedia method has been called successfully, otherwise an error will occur.

MountingPoint should be set to the name/path of the mounting point. The format of this value varies based what type of mounting point the application wishes to create; please refer to the Mounting Points topic for more information.

The Flags parameter is used to specify properties for the mounting point, and should be set by OR'ing together zero or more of the following flags:

STGMP_SIMPLE0x00010000Create a simple mounting point.

Simple mounting points may be local or global; and when local, can be made visible in either the current user session or another one.

This flag cannot be combined with STGMP_MOUNT_MANAGER or STGMP_NETWORK, and is implied if neither of those flags are present.

STGMP_MOUNT_MANAGER0x00020000Create a mounting point that appears to the system as a physical device.

When the StorageType property is set to STGT_DISK_PNP, mounting points created using the system mount manager appear as physical devices in the Disk Management snap-in of the Microsoft Management Console (mmc.exe).

This flag is a necessary prerequisite for creating a folder mounting point, which makes a drive accessible via an otherwise empty directory on another NTFS volume.

This flag cannot be combined with STGMP_SIMPLE, STGMP_NETWORK, or STGMP_LOCAL.

Only one mounting point of this type can be added to a virtual drive.

STGMP_NETWORK0x00040000Create a network mounting point.

Network mounting points can be further configured using the various STGMP_NETWORK_* flags described below. Applications that plan to make use of network mounting points must be sure to install the Helper DLL before doing so, otherwise Windows Explorer will not correctly recognize the "network" drive.

This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER.

STGMP_LOCAL0x10000000Specifies that a local mounting point should be created.

This flag specifies that a local mounting point should be created rather than a global one. When this flag is set, applications must also pass an appropriate value for the AddMountingPoint method's AuthenticationId parameter.

Passing 0 for AuthenticationId will make the mounting point visible in the current user session. To make the mounting point visible in a different user session instead, pass the target session's Authentication ID.

This flag is valid when combined with STGMP_SIMPLE or STGMP_NETWORK; it cannot be combined with STGMP_MOUNT_MANAGER. Please note that a mounting point can be made available to other computers as a network share, and network shares are always globally visible on the local machine, even if this flag is set.

STGMP_NETWORK_ALLOW_MAP_AS_DRIVE0x00000001Indicates that users may assign a drive letter to the share (e.g., using the 'Map network drive...' context menu item in Windows Explorer).

STGMP_NETWORK_HIDDEN_SHARE0x00000002Indicates that the share should be skipped during enumeration.

Such shares are only accessible when their name is already known to the accessor.

STGMP_NETWORK_READ_ACCESS0x00000004Makes a read-only share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the component use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_WRITE_ACCESS0x00000008Makes a read/write share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the component use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_CLAIM_SERVER_NAME0x00000010Specifies that the server name is unique.

When this flag is specified, the driver handles IOCTL_REDIR_QUERY_PATH[_EX] requests by instructing the OS to direct all requests going to the <Server Name> part of the MountingPoint parameter's value to the driver instead.

This flag should be used when the <Server Name> is unique within the local system (e.g., when the application's name is used). Using this flag allows the system to avoid delays caused by certain network requests made by various processes.

This flag is also required for "net view" command to be able to show the share in the list.
STGMP_DRIVE_LETTER_NOTIFY_ASYNC0x20000000Causes the method to return immediately without waiting for mounting notifications to be sent to the system.

STGMP_AUTOCREATE_DRIVE_LETTER0x40000000Tells the component that it should assign the drive letter automatically.

When this flag is specified, the component will automatically assign a drive letter from the list of available letters. The assigned letter is added to the end of the list of mounting points, and can be retrieved from there.

Do not include a drive letter in the MountingPoint parameter's value when specifying this flag.

If no flags are specified, the STGMP_SIMPLE flag is assumed.

If the STGMP_LOCAL flag is set, the AuthenticationId parameter should be set to the Authentication ID of the user session the mounting point should visible in; or to 0 to make the mounting point visible in the current user session. If the aforementioned flag is not set and AuthenticationId is 0, the mounting point will be global (i.e., visible in all user sessions). When AuthenticationId is set to a non-zero value, STGMP_LOCAL is implied. Please refer to the Mounting Points topic for more information.

Note: This method cannot be called within events.

The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

Virtual Drives, Media, and Mounting Points

When applications call the CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual disk, applications should call MountMedia to "insert" virtual storage media into the virtual disk. This call will cause the component's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual disk, applications should use the AddMountingPoint method to add one or more mounting points for the virtual disk. These mounting points make the virtual disk, visible to the system and other applications, allowing them to start accessing the contents of the CBDisk-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual disks with non-removable media; see StorageType), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

When applications call the CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual disk, applications should call MountMedia to "insert" virtual storage media into the virtual disk. This call will cause the component's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual disk, applications should use the AddMountingPoint method to add one or more mounting points for the virtual disk. These mounting points make the virtual disk, visible to the system and other applications, allowing them to start accessing the contents of the CBDisk-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual disks with non-removable media; see StorageType), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

Config Method (CBDisk Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);
Public Function Config(ByVal ConfigurationString As String) As String

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These 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.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateStorage Method (CBDisk Component)

Creates the virtual disk.

Syntax

public void CreateStorage();
Public Sub CreateStorage()

Remarks

This method creates the virtual disk (without mounting points) based on the following properties and configuration settings, which cannot be changed once the virtual storage has been created:

(Note that there are many other properties which, while not directly used by this method, nonetheless cannot be changed once a virtual disk is created. Such restrictions are noted where applicable.)

After the virtual disk is created, use the MountMedia method to "insert storage media" into the virtual drive, and use the AddMountingPoint method to create one or more mounting points for it.

The Initialize method must have been called by some component instance in the application prior to calling this method.

Note: This method cannot be called within events.

Virtual Drives, Media, and Mounting Points

When applications call the CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual disk, applications should call MountMedia to "insert" virtual storage media into the virtual disk. This call will cause the component's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual disk, applications should use the AddMountingPoint method to add one or more mounting points for the virtual disk. These mounting points make the virtual disk, visible to the system and other applications, allowing them to start accessing the contents of the CBDisk-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual disks with non-removable media; see StorageType), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

When applications call the CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual disk, applications should call MountMedia to "insert" virtual storage media into the virtual disk. This call will cause the component's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual disk, applications should use the AddMountingPoint method to add one or more mounting points for the virtual disk. These mounting points make the virtual disk, visible to the system and other applications, allowing them to start accessing the contents of the CBDisk-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual disks with non-removable media; see StorageType), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

DeleteStorage Method (CBDisk Component)

Deletes the virtual disk.

Syntax

public void DeleteStorage(bool forceUnmount);
Public Sub DeleteStorage(ByVal ForceUnmount As Boolean)

Remarks

This method attempts to delete the virtual disk. The ForceUnmount parameter controls how this method behaves if any mounting points currently exist for the virtual disk.

If ForceUnmount is true, any existing mounting points are forcibly removed (and any open handles are closed along the way). If ForceUnmount is false and any mounting points exist for it, this method throws an exception.

Note: This method cannot be called within events.

GetDriverStatus Method (CBDisk Component)

Retrieves the status of the system driver.

Syntax

public int GetDriverStatus(string productGUID, int module);
Public Function GetDriverStatus(ByVal ProductGUID As String, ByVal Module As Integer) As Integer

Remarks

This method retrieves the status of the system driver module specified by Module. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:

MODULE_STATUS_NOT_PRESENT0x00000000The specified module is not present on the system.

MODULE_STATUS_STOPPED0x00000001The specified module is in the Stopped state.

MODULE_STATUS_RUNNING0x00000004The specified module is loaded and running.

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.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

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:

The Module parameter specifies which driver module to query the status of. Possible values are:

MODULE_PNP_BUS0x00000001PnP Bus Driver (.sys file).

This module must be installed if the application wishes to make use of Plug-and-Play (PnP) storage features. PnP storage devices are those visible as disks in the Device Manager, and the system treats such storage devices differently from other purely virtual devices.

The filesystem driver must be reinstalled any time this module is added or removed.

MODULE_DRIVER0x00000002Core Product Driver (.sys file).

The product's filesystem driver module provides the core of its functionality; it must be installed for the product to function correctly.

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBDiskShellHelper22.dll)

This module provides supplementary functionality; please refer to the Helper DLL topic for more information.

Note: This module is not applicable when calling the GetDriverStatus method.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

GetModuleVersion Method (CBDisk Component)

Retrieves the version of a given product module.

Syntax

public long GetModuleVersion(string productGUID, int module);
Public Function GetModuleVersion(ByVal ProductGUID As String, ByVal Module As Integer) As Long

Remarks

This method retrieves the version of the product module specified by Module. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the specified module is not installed, this method returns 0.

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.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

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:

The Module parameter specifies which driver module to query the status of. Possible values are:

MODULE_PNP_BUS0x00000001PnP Bus Driver (.sys file).

This module must be installed if the application wishes to make use of Plug-and-Play (PnP) storage features. PnP storage devices are those visible as disks in the Device Manager, and the system treats such storage devices differently from other purely virtual devices.

The filesystem driver must be reinstalled any time this module is added or removed.

MODULE_DRIVER0x00000002Core Product Driver (.sys file).

The product's filesystem driver module provides the core of its functionality; it must be installed for the product to function correctly.

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBDiskShellHelper22.dll)

This module provides supplementary functionality; please refer to the Helper DLL topic for more information.

Note: This module is not applicable when calling the GetDriverStatus method.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Initialize Method (CBDisk Component)

Initializes the component.

Syntax

public void Initialize(string productGUID);
Public Sub Initialize(ByVal ProductGUID As String)

Remarks

This method initializes the component and must be called each time the application starts before attempting to call any of the component's other methods with the exception of installation-related methods.

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.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

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:

If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

Install Method (CBDisk Component)

Installs (or upgrades) the product's system drivers and/or the helper DLL.

Syntax

public int Install(string cabFileName, string productGUID, string pathToInstall, int modulesToInstall, int flags);
Public Function Install(ByVal CabFileName As String, ByVal ProductGUID As String, ByVal PathToInstall As String, ByVal ModulesToInstall As Integer, ByVal Flags As Integer) As Integer

Remarks

This method is used to install or upgrade the product's various modules (i.e., the system drivers and the Helper DLL). The ModulesToInstall parameter selects which modules should be installed. If the system must be rebooted to complete the installation process, this method will return a non-zero value indicating which module(s) requested the reboot (out of those initially selected).

Important: To upgrade the product's modules, use only the Install method. Previously installed versions of the modules should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the .cab file containing the product modules. 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 modules 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.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

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 modules are installed. Pass empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

ModulesToInstall should contain one or more of the following flags, OR'd together:

MODULE_PNP_BUS0x00000001PnP Bus Driver (.sys file).

This module must be installed if the application wishes to make use of Plug-and-Play (PnP) storage features. PnP storage devices are those visible as disks in the Device Manager, and the system treats such storage devices differently from other purely virtual devices.

The filesystem driver must be reinstalled any time this module is added or removed.

MODULE_DRIVER0x00000002Core Product Driver (.sys file).

The product's filesystem driver module provides the core of its functionality; it must be installed for the product to function correctly.

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBDiskShellHelper22.dll)

This module provides supplementary functionality; please refer to the Helper DLL topic for more information.

Note: This module is not applicable when calling the GetDriverStatus method.

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

INSTALL_REMOVE_OLD_VERSIONS0x00000001Uninstall drivers and helper DLLs from previous component 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_OVERWRITE_SAME_VERSION0x00000004Install files when their version is the same as the version of already installed files.

If this flag is not set (default), the installation logic will overwrite the existing file only if the version number of the file being installed is larger than the version of the file being overwritten. Setting this flag causes the installation logic to overwrite the file even when it has the same version.

This method is available in both the component 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.

IsIconRegistered Method (CBDisk Component)

Checks whether the specified icon is registered.

Syntax

public bool IsIconRegistered(string iconId);
Public Function IsIconRegistered(ByVal IconId As String) As Boolean

Remarks

This method checks whether an icon with the specified IconId has been registered. If such an icon has been registered, this method returns true; otherwise it returns false.

Icons can be registered using the RegisterIcon method. Please refer to that method's documentation, as well as the Custom Drive Icons topic, for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

MountMedia Method (CBDisk Component)

Mounts media in the virtual disk, making it accessible for reading and writing.

Syntax

public void MountMedia(int timeout);
Public Sub MountMedia(ByVal Timeout As Integer)

Remarks

After using CreateStorage to create a virtual disk, applications should call this method to "insert storage media" into it. For plug-and-play virtual disks with non-removable media (see StorageType), this method must be called before AddMountingPoint is called. For all other virtual disks, AddMountingPoint can be called before or after calling this method.

Timeout specifies how many milliseconds the driver will wait for events to execute before cancelling the underlying OS requests ; please refer to the Timeouts topic for more information . Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. (Passing a non-zero value less than 3000 will cause this method to fail with an ERROR_IMPLEMENTATION_LIMIT (1292, 0x50C) error code.)

When event timeouts are in effect, event handlers can call ResetTimeout to reset the timer if they require additional time to complete an operation.

Note that there are a number of properties that cannot be changed once media is mounted. Such restrictions are noted in properties' documentation as applicable.

If this method encounters any issues during its execution, it throws an exception, and additional information is logged to the Windows system log as described in the Error Reporting and Handling topic.

Note: This method can only be called after creating a virtual disk, and cannot be called within events.

Virtual Drives, Media, and Mounting Points

When applications call the CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual disk, applications should call MountMedia to "insert" virtual storage media into the virtual disk. This call will cause the component's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual disk, applications should use the AddMountingPoint method to add one or more mounting points for the virtual disk. These mounting points make the virtual disk, visible to the system and other applications, allowing them to start accessing the contents of the CBDisk-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual disks with non-removable media; see StorageType), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

When applications call the CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual disk, applications should call MountMedia to "insert" virtual storage media into the virtual disk. This call will cause the component's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual disk, applications should use the AddMountingPoint method to add one or more mounting points for the virtual disk. These mounting points make the virtual disk, visible to the system and other applications, allowing them to start accessing the contents of the CBDisk-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual disks with non-removable media; see StorageType), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

RegisterIcon Method (CBDisk Component)

Registers an icon that can be displayed as an overlay on the virtual disk in Windows Explorer.

Syntax

public bool RegisterIcon(string iconPath, string productGUID, string iconId);
Public Function RegisterIcon(ByVal IconPath As String, ByVal ProductGUID As String, ByVal IconId As String) As Boolean

Remarks

This method registers an icon in the file specified by IconPath so that it can later be used to display an overlay on the virtual disk in Windows Explorer. If the system must be rebooted before the icon can be used, this method returns true, otherwise it returns false.

Please note that this method only registers overlay icons; Applications should call the SetIcon and ResetIcon methods to select an icon for display. Please refer to the Custom Drive Icons topic for more information.

IconPath must be the full path and file name of the .ico file whose icon should be registered. The file must exist and remain available in order for the icon to be used until the icon is unregistered using UnregisterIcon.

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.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

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:

IconId specifies an identifier that can later be passed to the SetIcon and UnregisterIcon methods. Each registered icon should have a unique IconId value; if a value is passed that is already in use, the existing icon will be removed (by calling UnregisterIcon internally) before the new one is registered.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter. The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

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.

RemoveMountingPoint Method (CBDisk Component)

Removes a mounting point for the virtual disk.

Syntax

public void RemoveMountingPoint(int index, string mountingPoint, int flags, long authenticationId);
Public Sub RemoveMountingPoint(ByVal Index As Integer, ByVal MountingPoint As String, ByVal Flags As Integer, ByVal AuthenticationId As Long)

Remarks

This method removes a previously-created mounting point for the virtual disk.

Index must be set to the index of an item in the MountingPoints collection property, or to -1 to remove an item based on the other method parameters.

If Index is -1, then the same values must be passed for MountingPoint, Flags, AuthenticationId as were used to add the mounting point when AddMountingPoint was called previously. Please refer to that method's documentation for more information. (If Index is not -1, these parameters are ignored.)

The sgSTGMPDRIVELETTERNOTIFYASYNC; flag may be passed in Flags to send notifications about removal of the mounting point asynchronously. Do not use this flag if the process quits right after a call to this method because asynchronous delivery involves a secondary thread, which will be terminated when the process quits.

Note: This method cannot be called within events.

The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

ResetIcon Method (CBDisk Component)

Resets the virtual disk's icon back to default by deselecting the active overlay icon.

Syntax

public void ResetIcon();
Public Sub ResetIcon()

Remarks

This method deselects the overlay icon currently in use, thus resetting the virtual disk's icon back to its default state (i.e., displayed without any overlay icons).

Please refer to the SetIcon method, as well as the Custom Drive Icons topic, for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

Note: This method can only be called after creating a virtual disk, and cannot be called within events.

SetIcon Method (CBDisk Component)

Selects a registered overlay icon for display on the virtual disk in Windows Explorer.

Syntax

public void SetIcon(string iconId);
Public Sub SetIcon(ByVal IconId As String)

Remarks

This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual disk in Windows Explorer. The desired icon must have already been registered using the RegisterIcon method, and the value passed for IconId must match the one passed RegisterIcon at that time.

To switch to a different overlay icon later, call this method again with a different IconId. To reset the virtual disk's icon back to its default state (i.e., displayed without any overlay icons), call the ResetIcon method. Please refer to the Custom Drive Icons topic for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

Note: This method can only be called after creating a virtual disk, and cannot be called within events. Also, note that the effects of this method only last until the virtual disk is destroyed; applications that always want to have some overlay icon displayed must call this method each time the virtual disk is created.

ShutdownSystem Method (CBDisk Component)

Shuts down or reboots the operating system.

Syntax

public bool ShutdownSystem(string shutdownPrompt, int timeout, bool forceCloseApps, bool reboot);
Public Function ShutdownSystem(ByVal ShutdownPrompt As String, ByVal Timeout As Integer, ByVal ForceCloseApps As Boolean, ByVal Reboot As Boolean) As Boolean

Remarks

This method shuts down or (if Reboot is true) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns false, then this method will return false; otherwise, it returns true. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (true) or just shut down (false).

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Uninstall Method (CBDisk Component)

Uninstalls the product's system drivers and/or helper DLL.

Syntax

public int Uninstall(string cabFileName, string productGUID, string installedPath, int flags);
Public Function Uninstall(ByVal CabFileName As String, ByVal ProductGUID As String, ByVal InstalledPath As String, ByVal Flags As Integer) As Integer

Remarks

This method is used to uninstall the product's various modules (i.e., the system drivers and Helper DLL). If the system must be rebooted to complete the uninstallation process, this method will return a non-zero value indicating which module(s) requested the reboot (see Install for possible values).

Important: To upgrade the product's modules, use only the Install method. Previously installed versions of the modules should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when Install was called; please refer to its documentation for more information.

Flags specifies which versions of the product's modules should be uninstalled, and should be set by OR'ing together one or more of the following values:

UNINSTALL_VERSION_PREVIOUS0x00000001Uninstall modules from previous product versions.

UNINSTALL_VERSION_CURRENT0x00000002Uninstall modules from the current product version.

UNINSTALL_VERSION_ALL0x00000003Uninstall modules from all product versions.

This method is available in both the component 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.

UnmountMedia Method (CBDisk Component)

Unmounts media from the virtual disk.

Syntax

public void UnmountMedia(bool forceUnmount);
Public Sub UnmountMedia(ByVal ForceUnmount As Boolean)

Remarks

This method unmounts the virtual storage media from the virtual disk. The virtual disk itself, as well as any existing mounting points, remain present.

If ForceUnmount is true, all open files are forcefully closed. If ForceUnmount is false and open files or directories are detected, this method throws an exception.

This method must not be called for plug-and-play virtual disks with non-removable media (see StorageType); attempting to do so will cause the call will fail with an "access denied" error.

Note: This method can only be called after creating a virtual disk, and cannot be called within events.

UnregisterIcon Method (CBDisk Component)

Unregisters an existing overlay icon.

Syntax

public bool UnregisterIcon(string productGUID, string iconId);
Public Function UnregisterIcon(ByVal ProductGUID As String, ByVal IconId As String) As Boolean

Remarks

This method unregisters the overlay icon identified by IconId. If the system must be rebooted to completely remove the icon, this method returns true, otherwise it returns false.

The same values must be passed for the ProductGUID and IconId parameters as were passed when RegisterIcon was called; please refer to its documentation, as well as the Custom Drive Icons topic, for more information.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter. The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

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.

DiskRead Event (CBDisk Component)

Fires when the OS needs to read data from the virtual disk.

Syntax

public event OnDiskReadHandler OnDiskRead;

public delegate void OnDiskReadHandler(object sender, CbdiskDiskReadEventArgs e);

public class CbdiskDiskReadEventArgs : EventArgs {
  public long Offset { get; }
  public IntPtr Buffer { get; }
  public long BytesToRead { get; }
  public long BytesRead { get; set; }
  public int ResultCode { get; set; }
}
Public Event OnDiskRead As OnDiskReadHandler

Public Delegate Sub OnDiskReadHandler(sender As Object, e As CbdiskDiskReadEventArgs)

Public Class CbdiskDiskReadEventArgs Inherits EventArgs
  Public ReadOnly Property Offset As Long
  Public ReadOnly Property Buffer As IntPtr
  Public ReadOnly Property BytesToRead As Long
  Public Property BytesRead As Long
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the OS needs to read data from the virtual disk.

To handle this event properly, applications must read BytesToRead bytes from the block of data associated with the virtual disk, copying it to the memory region pointed to by Buffer. Reading must begin at the specified Offset in the data block, and when reading is complete, applications must set BytesRead to reflect the actual number of bytes read into Buffer. Applications must not attempt to copy more than BytesToRead bytes of data into Buffer.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

DiskWrite Event (CBDisk Component)

Fires when the OS needs to write data to the virtual disk.

Syntax

public event OnDiskWriteHandler OnDiskWrite;

public delegate void OnDiskWriteHandler(object sender, CbdiskDiskWriteEventArgs e);

public class CbdiskDiskWriteEventArgs : EventArgs {
  public long Offset { get; }
  public IntPtr Buffer { get; }
  public long BytesToWrite { get; }
  public int ResultCode { get; set; }
}
Public Event OnDiskWrite As OnDiskWriteHandler

Public Delegate Sub OnDiskWriteHandler(sender As Object, e As CbdiskDiskWriteEventArgs)

Public Class CbdiskDiskWriteEventArgs Inherits EventArgs
  Public ReadOnly Property Offset As Long
  Public ReadOnly Property Buffer As IntPtr
  Public ReadOnly Property BytesToWrite As Long
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the OS needs to write data to the virtual disk.

To handle this event properly, applications must write BytesToWrite bytes to the block of data associated with the virtual disk, copying it from the memory region pointed to by Buffer. Writing must begin at the specified Offset in the data block; and applications must either write exactly BytesToWrite bytes, or return an error via ResultCode (i.e., partial writes are not a successful outcome). Applications must not attempt to copy more than BytesToWrite bytes of data from Buffer.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Ejected Event (CBDisk Component)

Fires when the media and virtual disk have been ejected.

Syntax

public event OnEjectedHandler OnEjected;

public delegate void OnEjectedHandler(object sender, CbdiskEjectedEventArgs e);

public class CbdiskEjectedEventArgs : EventArgs {
  public int ResultCode { get; set; }
}
Public Event OnEjected As OnEjectedHandler

Public Delegate Sub OnEjectedHandler(sender As Object, e As CbdiskEjectedEventArgs)

Public Class CbdiskEjectedEventArgs Inherits EventArgs
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when a user has ejected the media and virtual disk using the Eject command in Windows Explorer.

For ejection via the system notification area (tray) to work correctly, the StorageType property must be set to STGT_DISK_PNP, and the StorageCharacteristics property must include ejection-related flags.

This event is optional; it is provided to give applications a chance to, e.g., free up resources associated with the virtual disk. Since the virtual disk has already been destroyed by the time this event fires, applications must not call UnmountMedia or DeleteStorage (the latter is called automatically with its ForceUnmount parameter set to true) .

The ResultCode parameter will always be initially set to the result of a storage deletion operation. The expected value is 0. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Note that as ejection has already occured, this non-zero value will not have effect on the media's state. Please refer to the Error Reporting and Handling topic for more information.

Error Event (CBDisk Component)

Fires if an unhandled error occurs during an event.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, CbdiskErrorEventArgs e);

public class CbdiskErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}
Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As CbdiskErrorEventArgs)

Public Class CbdiskErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to help track down unhandled errors in an application's event handlers.

Flush Event (CBDisk Component)

TBD.

Syntax

public event OnFlushHandler OnFlush;

public delegate void OnFlushHandler(object sender, CbdiskFlushEventArgs e);

public class CbdiskFlushEventArgs : EventArgs {
  public int ResultCode { get; set; }
}
Public Event OnFlush As OnFlushHandler

Public Delegate Sub OnFlushHandler(sender As Object, e As CbdiskFlushEventArgs)

Public Class CbdiskFlushEventArgs Inherits EventArgs
  Public Property ResultCode As Integer
End Class

Remarks

TBD.

TBD.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

GetDiskSize Event (CBDisk Component)

Fires when the OS needs to retrieve the size of the virtual disk.

Syntax

public event OnGetDiskSizeHandler OnGetDiskSize;

public delegate void OnGetDiskSizeHandler(object sender, CbdiskGetDiskSizeEventArgs e);

public class CbdiskGetDiskSizeEventArgs : EventArgs {
  public long Size { get; set; }
  public int ResultCode { get; set; }
}
Public Event OnGetDiskSize As OnGetDiskSizeHandler

Public Delegate Sub OnGetDiskSizeHandler(sender As Object, e As CbdiskGetDiskSizeEventArgs)

Public Class CbdiskGetDiskSizeEventArgs Inherits EventArgs
  Public Property Size As Long
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the OS needs to retrieve the size of the virtual disk.

To handle this event properly, applications must set Size to reflect the size in bytes of the block of data associated with the virtual disk.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

MountingPoint Type

Represents a mounting point for the virtual disk.

Remarks

This type represents a mounting point for the virtual disk.

Fields

AuthenticationId
Long

The Authentication ID used when creating the mounting point, if applicable.

If the STGMP_LOCAL flag is included in the Flags value, this field reflects the Authentication ID of the user session in which the mounting point was added. Will be 0 if the mounting point was added in the current user session or globally.

Flags
Integer

The flags used to create the mounting point.

This field reflects the flags used to create the mounting point. It is a combination of zero or more of the following:

STGMP_SIMPLE0x00010000Create a simple mounting point.

Simple mounting points may be local or global; and when local, can be made visible in either the current user session or another one.

This flag cannot be combined with STGMP_MOUNT_MANAGER or STGMP_NETWORK, and is implied if neither of those flags are present.

STGMP_MOUNT_MANAGER0x00020000Create a mounting point that appears to the system as a physical device.

When the StorageType property is set to STGT_DISK_PNP, mounting points created using the system mount manager appear as physical devices in the Disk Management snap-in of the Microsoft Management Console (mmc.exe).

This flag is a necessary prerequisite for creating a folder mounting point, which makes a drive accessible via an otherwise empty directory on another NTFS volume.

This flag cannot be combined with STGMP_SIMPLE, STGMP_NETWORK, or STGMP_LOCAL.

Only one mounting point of this type can be added to a virtual drive.

STGMP_NETWORK0x00040000Create a network mounting point.

Network mounting points can be further configured using the various STGMP_NETWORK_* flags described below. Applications that plan to make use of network mounting points must be sure to install the Helper DLL before doing so, otherwise Windows Explorer will not correctly recognize the "network" drive.

This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER.

STGMP_LOCAL0x10000000Specifies that a local mounting point should be created.

This flag specifies that a local mounting point should be created rather than a global one. When this flag is set, applications must also pass an appropriate value for the AddMountingPoint method's AuthenticationId parameter.

Passing 0 for AuthenticationId will make the mounting point visible in the current user session. To make the mounting point visible in a different user session instead, pass the target session's Authentication ID.

This flag is valid when combined with STGMP_SIMPLE or STGMP_NETWORK; it cannot be combined with STGMP_MOUNT_MANAGER. Please note that a mounting point can be made available to other computers as a network share, and network shares are always globally visible on the local machine, even if this flag is set.

STGMP_NETWORK_ALLOW_MAP_AS_DRIVE0x00000001Indicates that users may assign a drive letter to the share (e.g., using the 'Map network drive...' context menu item in Windows Explorer).

STGMP_NETWORK_HIDDEN_SHARE0x00000002Indicates that the share should be skipped during enumeration.

Such shares are only accessible when their name is already known to the accessor.

STGMP_NETWORK_READ_ACCESS0x00000004Makes a read-only share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the component use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_WRITE_ACCESS0x00000008Makes a read/write share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the component use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_CLAIM_SERVER_NAME0x00000010Specifies that the server name is unique.

When this flag is specified, the driver handles IOCTL_REDIR_QUERY_PATH[_EX] requests by instructing the OS to direct all requests going to the <Server Name> part of the MountingPoint parameter's value to the driver instead.

This flag should be used when the <Server Name> is unique within the local system (e.g., when the application's name is used). Using this flag allows the system to avoid delays caused by certain network requests made by various processes.

This flag is also required for "net view" command to be able to show the share in the list.
STGMP_DRIVE_LETTER_NOTIFY_ASYNC0x20000000Causes the method to return immediately without waiting for mounting notifications to be sent to the system.

STGMP_AUTOCREATE_DRIVE_LETTER0x40000000Tells the component that it should assign the drive letter automatically.

When this flag is specified, the component will automatically assign a drive letter from the list of available letters. The assigned letter is added to the end of the list of mounting points, and can be retrieved from there.

Do not include a drive letter in the MountingPoint parameter's value when specifying this flag.

Name
String

The mounting point name.

This field reflects the name of the mounting point (i.e., the value passed to the AddMountingPoint method's MountingPoint parameter).

Config Settings (CBDisk Component)

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.

CBDisk Config Settings

AsyncDeleteStorageNotifications:   Whether system broadcasts for virtual disk deletion are sent asynchronously.

This setting specifies whether the WM_DEVICECHANGE broadcast is sent asynchronously (true) or synchronously (false) when the virtual disk is deleted using DeleteStorage.

By default, this setting is enabled, and the broadcast is sent asynchronously. This is typically sufficient, but applications may disable this setting if they find that Windows Explorer is still presenting virtual disks as available after they've been deleted (which may occur if the application exits immediately after deleting a virtual disk).

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.

SectorSize:   The sector size to create the virtual drive with.

This setting specifies the number of bytes each "sector" on the virtual drive contains. This setting must be set to a value that is a multiple of 512, a power of 2, and not larger than 4096 (e.g., 512, 1024, 2048, 4096).

By default, this setting is set to 512; using a different value is not recommended.

SupportSearchIndexer:   Specifies whether the driver must take additional measures to support indexing by Windows Search.

The Search Indexer of Windows 10 has been recently modified in the way that Search Indexer stopped indexing virtual disks. This happens because of the missing mounting point when the disk is created.

This setting, when enabled, tells the driver to create a fake mounting point and use it to work around the Search Indexer bug. By default, this setting is disabled.

Note: This property cannot be changed within events.

VolumeGuidName:   The GUID of the mounted volume.

Use this setting to obtain the guild of the created disk device. The value is returned as a string in the "Volume{GUID}" format, where GUID is the actual GUID.

Base Config 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).

Trappable Errors (CBDisk Component)

The component uses Windows error codes during operation as necessary. Please refer to the Error Reporting and Handling topic for more information.

Special Use Errors

21   ERROR_NOT_READY: Reported by the methods of the component if Initialize has not been called or did not succeed.
575   ERROR_APP_INIT_FAILURE: Reported by the methods of the component if Initialize has not been called or did not succeed. Differs from ERROR_NOT_READY (21) in that it indicates a specific situation in the internal code.
588   ERROR_FS_DRIVER_REQUIRED: Reported if the required system module was not correctly installed for the given ProductGUID.
614   ERROR_NO_CALLBACK_ACTIVE: Reported by any method that can only be called within event handlers if it is called outside an event handler.
1292   ERROR_IMPLEMENTATION_LIMIT: Reported when the timeout value provided is less than 3 seconds.
1314   ERROR_PRIVILEGE_NOT_HELD: Reported by any method that requires elevated permissions if it is called without such permissions.

Copyright (c) 2023 Callback Technologies, Inc. - All rights reserved.
CBFS Disk 2022 .NET Edition - Version 22.0 [Build 8462]