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.

Method List

---

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

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.

Config Settings

---

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

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:

• mounting_point_authentication_id
• mounting_point_flags
• mounting_point_name

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:

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:

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 : &str) ->  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:

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 : &str, flags : i32, authentication_id : i64) -> Result<(), 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:

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 : &str) ->  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) -> Result<(), 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:

• storage_type
• storage_characteristics
• storage_guid (if applicable)
• SectorSize

(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) -> Result<(), 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 : &str, 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:

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:

• install
• uninstall
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

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

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 : &str, 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:

• install
• uninstall
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

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

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 : &str) -> Result<(), 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:

• install
• uninstall
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

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 : &str, product_guid : &str, path_to_install : &str, 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:

• install
• uninstall
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

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:

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

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 : &str) ->  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) -> Result<(), 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 : &str, product_guid : &str, icon_id : &str) ->  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:

• install
• uninstall
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

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 : &str, flags : i32, authentication_id : i64) -> Result<(), 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) -> Result<(), 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 : &str) -> Result<(), 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 : &str, 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 : &str, product_guid : &str, installed_path : &str, 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:

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) -> Result<(), 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 : &str, icon_id : &str) ->  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

Base Config Settings

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