Struct cbfsdisk::CBDisk

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

cbfsdisk::CBDisk

Remarks

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

Getting Started

Each CBDisk struct instance controls a single virtual disk. Applications can use multiple instances of the CBDisk struct if their use-case requires the creation of multiple virtual disks. The struct'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 struct. This must be done each time the application starts (if the application is using multiple CBDisk struct instances, only the first instance created should be used to call initialize).
  3. Ensure that the struct'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 create_storage method.
  5. Create one or more Mounting Points for the virtual disk using the add_mounting_point method. A mounting point can be a drive letter, a UNC path, or a directory on an existing NTFS-formatted drive.
  6. Call the mount_media method to "insert storage media" into the virtual disk drive. (This "media" can be changed at any time later using the unmount_media and mount_media methods.)
  7. Later, the application can unmount the "media" from the virtual disk using the unmount_media method. At this point, the application could call the mount_media method again to "insert different storage media".
  8. To delete the virtual disk entirely, call the delete_storage 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.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintainted by CBFSDisk. Due to this, the CBDisk struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBDisk when you have finished using the instance.

Property List


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

activeWhether the struct is active and handling OS requests.
mounting_point_countThe number of records in the MountingPoint arrays.
mounting_point_authentication_idThe Authentication ID used when creating the mounting point, if applicable.
mounting_point_flagsThe flags used to create the mounting point.
mounting_point_nameThe mounting point name.
read_onlyWhether the virtual disk should be mounted in read-only mode.
storage_characteristicsThe characteristic flags to create the virtual disk with.
storage_guidThe GUID to create the virtual disk with.
storage_presentWhether a virtual disk has been created.
storage_typeThe type of virtual disk to create.
tagThis property stores application-defined data specific to a particular instance of the struct.

Method List


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

add_mounting_pointAdds a mounting point for the virtual disk.
configSets or retrieves a configuration setting.
create_storageCreates the virtual disk.
delete_storageDeletes the virtual disk.
get_driver_statusRetrieves the status of the system driver.
get_module_versionRetrieves the version of a given product module.
initializeThis method initializes the struct.
installInstalls (or upgrades) the product's system drivers and/or the helper DLL.
is_icon_registeredChecks whether the specified icon is registered.
mount_mediaMounts media in the virtual disk, making it accessible for reading and writing.
register_iconRegisters an icon that can be displayed as an overlay on the virtual disk in Windows File Explorer.
remove_mounting_pointRemoves a mounting point for the virtual disk.
reset_iconResets the virtual disk's icon back to default by deselecting the active overlay icon.
set_iconSelects a registered overlay icon for display on the virtual disk in Windows File Explorer.
shutdown_systemShuts down or reboots the operating system.
uninstallUninstalls the product's system drivers and/or helper DLL.
unmount_mediaUnmounts media from the virtual disk.
unregister_iconUnregisters an existing overlay icon.

Event List


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

on_disk_readFires when the OS needs to read data from the virtual disk.
on_disk_writeFires when the OS needs to write data to the virtual disk.
on_ejectedFires when the media and virtual disk have been ejected.
on_errorThis event fires if an unhandled error occurs during an event.
on_flushTBD.
on_get_disk_sizeFires when the OS needs to retrieve the size of the virtual disk.

Config Settings


The following is a list of config settings for the struct 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 Struct)

Whether the struct is active and handling OS requests.

Syntax

fn active(&self ) -> Result<bool, CBFSDiskError> 

Default Value

false

Remarks

This property reflects whether the struct is currently active and handling OS requests. Active will be true once both create_storage and mount_media have been called.

This property is read-only.

Data Type

bool

mounting_point_count Property (CBDisk Struct)

The number of records in the MountingPoint arrays.

Syntax

fn mounting_point_count(&self ) -> Result<i32, CBFSDiskError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at mounting_point_count - 1.

This property is read-only.

Data Type

i32

mounting_point_authentication_id Property (CBDisk Struct)

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

Syntax

fn mounting_point_authentication_id(&self , MountingPointIndex : i32) -> Result<i64, CBFSDiskError> 

Default Value

0

Remarks

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

If the STGMP_LOCAL flag is included in the mounting_point_flags value, this property 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.

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only.

Data Type

i64

mounting_point_flags Property (CBDisk Struct)

The flags used to create the mounting point.

Syntax

fn mounting_point_flags(&self , MountingPointIndex : i32) -> Result<i32, CBFSDiskError> 

Default Value

0

Remarks

The flags used to create the mounting point.

This property 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 storage_type 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 File 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 add_mounting_point 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 File 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 struct 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 struct 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 struct that it should assign the drive letter automatically.

When this flag is specified, the struct 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.

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only.

Data Type

i32

mounting_point_name Property (CBDisk Struct)

The mounting point name.

Syntax

fn mounting_point_name(&self , MountingPointIndex : i32) -> Result<String, CBFSDiskError> 

Default Value

String::default()

Remarks

The mounting point name.

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

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only.

Data Type

String

read_only Property (CBDisk Struct)

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

Syntax

fn read_only(&self ) -> Result<bool, CBFSDiskError> 
fn set_read_only(&self, value : bool) -> Option<CBFSDiskError>

Default Value

false

Remarks

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

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

Data Type

bool

storage_characteristics Property (CBDisk Struct)

The characteristic flags to create the virtual disk with.

Syntax

fn storage_characteristics(&self ) -> Result<i32, CBFSDiskError> 
fn set_storage_characteristics(&self, value : i32) -> Option<CBFSDiskError>

Default Value

0

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 storage_type 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 storage_type 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 add_mounting_point method's Flags parameter instead.

When this flag is present, the storage_guid property must be set. This flag only works when storage_type 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 storage_type 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 storage_type 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 it cannot be changed within events.

Data Type

i32

storage_guid Property (CBDisk Struct)

The GUID to create the virtual disk with.

Syntax

fn storage_guid(&self ) -> Result<String, CBFSDiskError> 
fn set_storage_guid(&self, value : String) -> Option<CBFSDiskError> fn set_storage_guid_ref(&self, value : &String) -> Option<CBFSDiskError>

Default Value

String::default()

Remarks

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 may be left empty; in the latter case, the driver will generate a unique value when a disk is mounted.

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.

In multiuser environments (Terminal Server, Citrix and similar software) where the application may be run concurrently by different users, using the same GUID for all users will cause a name conflict. To avoid it, mix the constant GUID value with the user-unique information such as the hash of the username or SID. This way, each user will use a constant but distinct GUID for their virtual drive.

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

Data Type

String

storage_present Property (CBDisk Struct)

Whether a virtual disk has been created.

Syntax

fn storage_present(&self ) -> Result<bool, CBFSDiskError> 

Default Value

false

Remarks

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

This property is read-only.

Data Type

bool

storage_type Property (CBDisk Struct)

The type of virtual disk to create.

Syntax

fn storage_type(&self ) -> Result<i32, CBFSDiskError> 
fn set_storage_type(&self, value : i32) -> Option<CBFSDiskError>

Default Value

0

Remarks

This property specifies what type of virtual disk should be created. Windows File 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 it 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 add_mounting_point method and including the STGMP_MOUNT_MANAGER flag in the value passed for its Flags parameter.

In addition to supporting the STGC_REMOVABLE_MEDIA storage_characteristics 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.

Data Type

i32

tag Property (CBDisk Struct)

This property stores application-defined data specific to a particular instance of the struct.

Syntax

fn tag(&self ) -> Result<i64, CBFSDiskError> 
fn set_tag(&self, value : i64) -> Option<CBFSDiskError>

Default Value

0

Remarks

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

Data Type

i64

add_mounting_point Method (CBDisk Struct)

Adds a mounting point for the virtual disk.

Syntax

fn add_mounting_point(&self, mounting_point : &String, flags : i32, authentication_id : i64) -> Option<CBFSDiskError>

Remarks

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

Typically, mounting points may be added before or after mount_media is called. However, for plug-and-play virtual drives with non-removable media (see storage_type), add_mounting_point must not be called until after the mount_media 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 storage_type 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 File 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 add_mounting_point 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 File 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 struct 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 struct 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 struct that it should assign the drive letter automatically.

When this flag is specified, the struct 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 create_storage 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 mount_media to "insert" virtual storage media into the virtual disk. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual disk, applications should use the add_mounting_point 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 add_mounting_point before mount_media (except for plug-and-play virtual disks with non-removable media; see storage_type), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

When applications call the create_storage 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 mount_media to "insert" virtual storage media into the virtual disk. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual disk, applications should use the add_mounting_point 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 add_mounting_point before mount_media (except for plug-and-play virtual disks with non-removable media; see storage_type), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

config Method (CBDisk Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &String) ->  Result<String, CBFSDiskError>

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, 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.

create_storage Method (CBDisk Struct)

Creates the virtual disk.

Syntax

fn create_storage(&self) -> Option<CBFSDiskError>

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 mount_media method to "insert storage media" into the virtual drive, and use the add_mounting_point method to create one or more mounting points for it.

The initialize method must have been called by some struct 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 create_storage 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 mount_media to "insert" virtual storage media into the virtual disk. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual disk, applications should use the add_mounting_point 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 add_mounting_point before mount_media (except for plug-and-play virtual disks with non-removable media; see storage_type), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

When applications call the create_storage 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 mount_media to "insert" virtual storage media into the virtual disk. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual disk, applications should use the add_mounting_point 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 add_mounting_point before mount_media (except for plug-and-play virtual disks with non-removable media; see storage_type), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

delete_storage Method (CBDisk Struct)

Deletes the virtual disk.

Syntax

fn delete_storage(&self, force_unmount : bool) -> Option<CBFSDiskError>

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 .

Note: This method cannot be called within events.

get_driver_status Method (CBDisk Struct)

Retrieves the status of the system driver.

Syntax

fn get_driver_status(&self, product_guid : &String, module : i32) ->  Result<i32, CBFSDiskError>

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.

Note: This functionality is only available in Windows.

MODULE_STATUS_STOPPED0x00000001The specified module is in the Stopped state.

Note: This functionality is only available in Windows.

MODULE_STATUS_RUNNING0x00000004The specified module is loaded and running.

Note: This functionality is only available in Windows.

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 (CBDiskShellHelper24.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 get_driver_status method.

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

get_module_version Method (CBDisk Struct)

Retrieves the version of a given product module.

Syntax

fn get_module_version(&self, product_guid : &String, module : i32) ->  Result<i64, CBFSDiskError>

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 (CBDiskShellHelper24.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 get_driver_status method.

This method is available in both the struct 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 Struct)

This method initializes the struct.

Syntax

fn initialize(&self, product_guid : &String) -> Option<CBFSDiskError>

Remarks

This method initializes the struct and must be called each time the application starts before attempting to call any of the struct'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).

If the loaded kernel-mode driver is older than the user-mode API, initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the install method is required before the struct can be used.

install Method (CBDisk Struct)

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

Syntax

fn install(&self, cab_file_name : &String, product_guid : &String, path_to_install : &String, modules_to_install : i32, flags : i32) ->  Result<i32, CBFSDiskError>

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 (CBDiskShellHelper24.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 get_driver_status 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 struct versions (e.g., 2017).

Note: This functionality is only available in Windows. This flag does not remove the old PnP driver (VPnpBus) from the system because that driver is not versioned. Use the installer DLL of the old version and its Uninstall() function if you need to uninstall the PnP driver.

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.

Note: This functionality is only available in Windows.

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.

Note: This functionality is only available in Windows.

This method is available in both the struct 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 () error.

Note: This method cannot be called within events.

is_icon_registered Method (CBDisk Struct)

Checks whether the specified icon is registered.

Syntax

fn is_icon_registered(&self, icon_id : &String) ->  Result<bool, CBFSDiskError>

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 register_icon 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 get_module_version method, and install it using the install method if necessary.

mount_media Method (CBDisk Struct)

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

Syntax

fn mount_media(&self, timeout : i32) -> Option<CBFSDiskError>

Remarks

After using create_storage 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 storage_type), this method must be called before add_mounting_point is called. For all other virtual disks, add_mounting_point 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 reset_timeout 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 , and additional information is logged to the Windows system log as described in the Error Handling topic.

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

Virtual Drives, Media, and Mounting Points

When applications call the create_storage 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 mount_media to "insert" virtual storage media into the virtual disk. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual disk, applications should use the add_mounting_point 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 add_mounting_point before mount_media (except for plug-and-play virtual disks with non-removable media; see storage_type), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

When applications call the create_storage 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 mount_media to "insert" virtual storage media into the virtual disk. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual disk, applications should use the add_mounting_point 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 add_mounting_point before mount_media (except for plug-and-play virtual disks with non-removable media; see storage_type), but any attempts to access a virtual disk with no media mounted will result in a "no media" error.

register_icon Method (CBDisk Struct)

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

Syntax

fn register_icon(&self, icon_path : &String, product_guid : &String, icon_id : &String) ->  Result<bool, CBFSDiskError>

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 File 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 set_icon and reset_icon 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 unregister_icon.

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 set_icon and unregister_icon 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 unregister_icon internally) before the new one is registered.

This method is available in both the struct 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 get_module_version 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 () error.

Note: This method cannot be called within events.

remove_mounting_point Method (CBDisk Struct)

Removes a mounting point for the virtual disk.

Syntax

fn remove_mounting_point(&self, index : i32, mounting_point : &String, flags : i32, authentication_id : i64) -> Option<CBFSDiskError>

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 MountingPoint* properties, 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 add_mounting_point 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.

reset_icon Method (CBDisk Struct)

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

Syntax

fn reset_icon(&self) -> Option<CBFSDiskError>

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 set_icon 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 get_module_version method, and install it using the install method if necessary.

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

set_icon Method (CBDisk Struct)

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

Syntax

fn set_icon(&self, icon_id : &String) -> Option<CBFSDiskError>

Remarks

This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual disk in Windows File Explorer. The desired icon must have already been registered using the register_icon method, and the value passed for IconId must match the one passed register_icon 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 reset_icon 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 get_module_version method, and install it using the install method if necessary.

Note: This method can be called only after creating a virtual disk, and it 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.

shutdown_system Method (CBDisk Struct)

Shuts down or reboots the operating system.

Syntax

fn shutdown_system(&self, shutdown_prompt : &String, timeout : i32, force_close_apps : bool, reboot : bool) ->  Result<bool, CBFSDiskError>

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 struct 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 Struct)

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

Syntax

fn uninstall(&self, cab_file_name : &String, product_guid : &String, installed_path : &String, flags : i32) ->  Result<i32, CBFSDiskError>

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.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_CURRENT0x00000002Uninstall modules from the current product version.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_ALL0x00000003Uninstall modules from all product versions.

Note: This functionality is only available in Windows.

This method is available in both the struct 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 () error.

Note: This method cannot be called within events.

unmount_media Method (CBDisk Struct)

Unmounts media from the virtual disk.

Syntax

fn unmount_media(&self, force_unmount : bool) -> Option<CBFSDiskError>

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 .

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

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

unregister_icon Method (CBDisk Struct)

Unregisters an existing overlay icon.

Syntax

fn unregister_icon(&self, product_guid : &String, icon_id : &String) ->  Result<bool, CBFSDiskError>

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 register_icon 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 struct 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 get_module_version 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 () error.

Note: This method cannot be called within events.

on_disk_read Event (CBDisk Struct)

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

Syntax

// CBDiskDiskReadEventArgs carries the CBDisk DiskRead event's parameters.
pub struct CBDiskDiskReadEventArgs {
  fn offset(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn bytes_to_read(&self) -> i64
  fn bytes_read(&self) -> i64
  fn set_bytes_read(&self, value : i64)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBDiskDiskReadEvent defines the signature of the CBDisk DiskRead event's handler function.
pub trait CBDiskDiskReadEvent {
  fn on_disk_read(&self, sender : CBDisk, e : &mut CBDiskDiskReadEventArgs);
}

impl <'a> CBDisk<'a> {
  pub fn on_disk_read(&self) -> &'a dyn CBDiskDiskReadEvent;
  pub fn set_on_disk_read(&mut self, value : &'a dyn CBDiskDiskReadEvent);
  ...
}

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 see 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_disk_write Event (CBDisk Struct)

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

Syntax

// CBDiskDiskWriteEventArgs carries the CBDisk DiskWrite event's parameters.
pub struct CBDiskDiskWriteEventArgs {
  fn offset(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn bytes_to_write(&self) -> i64
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBDiskDiskWriteEvent defines the signature of the CBDisk DiskWrite event's handler function.
pub trait CBDiskDiskWriteEvent {
  fn on_disk_write(&self, sender : CBDisk, e : &mut CBDiskDiskWriteEventArgs);
}

impl <'a> CBDisk<'a> {
  pub fn on_disk_write(&self) -> &'a dyn CBDiskDiskWriteEvent;
  pub fn set_on_disk_write(&mut self, value : &'a dyn CBDiskDiskWriteEvent);
  ...
}

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 see 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_ejected Event (CBDisk Struct)

Fires when the media and virtual disk have been ejected.

Syntax

// CBDiskEjectedEventArgs carries the CBDisk Ejected event's parameters.
pub struct CBDiskEjectedEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBDiskEjectedEvent defines the signature of the CBDisk Ejected event's handler function.
pub trait CBDiskEjectedEvent {
  fn on_ejected(&self, sender : CBDisk, e : &mut CBDiskEjectedEventArgs);
}

impl <'a> CBDisk<'a> {
  pub fn on_ejected(&self) -> &'a dyn CBDiskEjectedEvent;
  pub fn set_on_ejected(&mut self, value : &'a dyn CBDiskEjectedEvent);
  ...
}

Remarks

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

For ejection via the system notification area (tray) to work correctly, the storage_type property must be set to STGT_DISK_PNP, and the storage_characteristics 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 unmount_media or delete_storage (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 Handling topic for more information.

on_error Event (CBDisk Struct)

This event fires if an unhandled error occurs during an event.

Syntax

// CBDiskErrorEventArgs carries the CBDisk Error event's parameters.
pub struct CBDiskErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// CBDiskErrorEvent defines the signature of the CBDisk Error event's handler function.
pub trait CBDiskErrorEvent {
  fn on_error(&self, sender : CBDisk, e : &mut CBDiskErrorEventArgs);
}

impl <'a> CBDisk<'a> {
  pub fn on_error(&self) -> &'a dyn CBDiskErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn CBDiskErrorEvent);
  ...
}

Remarks

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

on_flush Event (CBDisk Struct)

TBD.

Syntax

// CBDiskFlushEventArgs carries the CBDisk Flush event's parameters.
pub struct CBDiskFlushEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBDiskFlushEvent defines the signature of the CBDisk Flush event's handler function.
pub trait CBDiskFlushEvent {
  fn on_flush(&self, sender : CBDisk, e : &mut CBDiskFlushEventArgs);
}

impl <'a> CBDisk<'a> {
  pub fn on_flush(&self) -> &'a dyn CBDiskFlushEvent;
  pub fn set_on_flush(&mut self, value : &'a dyn CBDiskFlushEvent);
  ...
}

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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_disk_size Event (CBDisk Struct)

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

Syntax

// CBDiskGetDiskSizeEventArgs carries the CBDisk GetDiskSize event's parameters.
pub struct CBDiskGetDiskSizeEventArgs {
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBDiskGetDiskSizeEvent defines the signature of the CBDisk GetDiskSize event's handler function.
pub trait CBDiskGetDiskSizeEvent {
  fn on_get_disk_size(&self, sender : CBDisk, e : &mut CBDiskGetDiskSizeEventArgs);
}

impl <'a> CBDisk<'a> {
  pub fn on_get_disk_size(&self) -> &'a dyn CBDiskGetDiskSizeEvent;
  pub fn set_on_get_disk_size(&mut self, value : &'a dyn CBDiskGetDiskSizeEvent);
  ...
}

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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Config Settings (CBDisk Struct)

The struct 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 struct, 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 delete_storage.

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 File 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 struct; it is disabled by default. Please refer to the Error 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 struct 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 Struct)

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

Special Use Errors

21   ERROR_NOT_READY: Reported by the methods of the struct if initialize has not been called or did not succeed.
191   ERROR_INVALID_EXE_SIGNATURE: Reported by the install method when the CAB file signature cannot be validated.
575   ERROR_APP_INIT_FAILURE: Reported by the methods of the struct 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.