CBDisk Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

TcbdCBDisk

Remarks

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

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

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

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

Getting Started

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

Here's how to get up and running:

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

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

Active Property (CBDisk Component)

Whether the component is active and handling OS requests.

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

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

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

MountingPoints Property (CBDisk Component)

Collection of mounting points for the virtual disk.

Syntax

property MountingPoints: TcbdMountingPointList read get_MountingPoints;

Remarks

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

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

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

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

Please refer to the MountingPoint type for a complete list of fields.

ReadOnly Property (CBDisk Component)

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

Syntax

property ReadOnly: Boolean read get_ReadOnly write set_ReadOnly;

Default Value

false

Remarks

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

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

This property is not available at design time.

StorageCharacteristics Property (CBDisk Component)

The characteristic flags to create the virtual disk with.

Syntax

property StorageCharacteristics: Integer read get_StorageCharacteristics write set_StorageCharacteristics;

Default Value

16

Remarks

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

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

StorageGUID Property (CBDisk Component)

The GUID to create the virtual disk with.

Syntax

property StorageGUID: String read get_StorageGUID write set_StorageGUID;

Default Value

''

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.

StoragePresent Property (CBDisk Component)

Whether a virtual disk has been created.

Syntax

property StoragePresent: Boolean read get_StoragePresent;

Default Value

false

Remarks

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

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

StorageType Property (CBDisk Component)

The type of virtual disk to create.

Syntax

property StorageType: Integer read get_StorageType write set_StorageType;

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 AddMountingPoint method and including the STGMP_MOUNT_MANAGER flag in the value passed for its Flags parameter.

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

Tag Property (CBDisk Component)

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

Syntax

property Tag: Int64 read get_Tag write set_Tag;

Default Value

0

Remarks

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

AddMountingPoint Method (CBDisk Component)

Adds a mounting point for the virtual disk.

Syntax

procedure AddMountingPoint(MountingPoint: String; Flags: Integer; AuthenticationId: Int64);

Remarks

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

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

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

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

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

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

Note: This method cannot be called within events.

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

Virtual Drives, Media, and Mounting Points

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

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

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

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

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

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

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

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

Config Method (CBDisk Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

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

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

CreateStorage Method (CBDisk Component)

Creates the virtual disk.

Syntax

procedure CreateStorage();

Remarks

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

• StorageType
• StorageCharacteristics
• StorageGUID (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 MountMedia method to "insert storage media" into the virtual drive, and use the AddMountingPoint method to create one or more mounting points for it.

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

Note: This method cannot be called within events.

Virtual Drives, Media, and Mounting Points

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

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

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

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

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

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

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

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

DeleteStorage Method (CBDisk Component)

Deletes the virtual disk.

Syntax

procedure DeleteStorage(ForceUnmount: Boolean);

Remarks

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

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

Note: This method cannot be called within events.

GetDriverStatus Method (CBDisk Component)

Retrieves the status of the system driver.

Syntax

function GetDriverStatus(ProductGUID: String; Module: Integer): Integer;

Remarks

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

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

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
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

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

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

Note: This method cannot be called within events.

GetModuleVersion Method (CBDisk Component)

Retrieves the version of a given product module.

Syntax

function GetModuleVersion(ProductGUID: String; Module: Integer): Int64;

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
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

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

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

Note: This method cannot be called within events.

Initialize Method (CBDisk Component)

This method initializes the component.

Syntax

procedure Initialize(ProductGUID: String);

Remarks

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

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

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

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• 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 component can be used.

Install Method (CBDisk Component)

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

Syntax

function Install(CabFileName: String; ProductGUID: String; PathToInstall: String; ModulesToInstall: Integer; Flags: Integer): Integer;

Remarks

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

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

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the .cab file containing the product modules. Important: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required for uninstalling the modules from the system.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

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

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• 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 component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD ($0522) error.

Note: This method cannot be called within events.

IsIconRegistered Method (CBDisk Component)

Checks whether the specified icon is registered.

Syntax

function IsIconRegistered(IconId: String): Boolean;

Remarks

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

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

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

MountMedia Method (CBDisk Component)

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

Syntax

procedure MountMedia(Timeout: Integer);

Remarks

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

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

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

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

If this method encounters any issues during its execution, it raises an exception, 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 CreateStorage method, a virtual disk is created. Virtual disks are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

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

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

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

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

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

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

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

RegisterIcon Method (CBDisk Component)

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

Syntax

function RegisterIcon(IconPath: String; ProductGUID: String; IconId: String): Boolean;

Remarks

This method registers an icon in the file specified by IconPath so that it can later be used to display an overlay on the virtual disk in Windows 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 SetIcon and ResetIcon methods to select an icon for display. Please refer to the Custom Drive Icons topic for more information.

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

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

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

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

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

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

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD ($0522) error.

Note: This method cannot be called within events.

RemoveMountingPoint Method (CBDisk Component)

Removes a mounting point for the virtual disk.

Syntax

procedure RemoveMountingPoint(Index: Integer; MountingPoint: String; Flags: Integer; AuthenticationId: Int64);

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 AddMountingPoint was called previously. Please refer to that method's documentation for more information. (If Index is not -1, these parameters are ignored.)

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

Note: This method cannot be called within events.

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

ResetIcon Method (CBDisk Component)

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

Syntax

procedure ResetIcon();

Remarks

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

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

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

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

SetIcon Method (CBDisk Component)

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

Syntax

procedure SetIcon(IconId: String);

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 RegisterIcon method, and the value passed for IconId must match the one passed RegisterIcon at that time.

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

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

Note: This method can 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.

ShutdownSystem Method (CBDisk Component)

Shuts down or reboots the operating system.

Syntax

function ShutdownSystem(ShutdownPrompt: String; Timeout: Integer; ForceCloseApps: Boolean; Reboot: Boolean): Boolean;

Remarks

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

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

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

Reboot specifies whether the OS should reboot (True) or just shut down (False).

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

Note: This method cannot be called within events.

Uninstall Method (CBDisk Component)

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

Syntax

function Uninstall(CabFileName: String; ProductGUID: String; InstalledPath: String; Flags: Integer): Integer;

Remarks

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

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

Please refer to the Driver Installation topic for more information.

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

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

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

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD ($0522) error.

Note: This method cannot be called within events.

UnmountMedia Method (CBDisk Component)

Unmounts media from the virtual disk.

Syntax

procedure UnmountMedia(ForceUnmount: Boolean);

Remarks

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

If ForceUnmount is True, all open files are forcefully closed. If ForceUnmount is False and open files or directories are detected, this method raises an exception.

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

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

UnregisterIcon Method (CBDisk Component)

Unregisters an existing overlay icon.

Syntax

function UnregisterIcon(ProductGUID: String; IconId: String): Boolean;

Remarks

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

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

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

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD ($0522) error.

Note: This method cannot be called within events.

DiskRead Event (CBDisk Component)

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

Syntax

type TDiskReadEvent = procedure (
  Sender: TObject;
  Offset: Int64;
  Buffer: Pointer;
  BytesToRead: Int64;
  var BytesRead: Int64;
  var ResultCode: Integer
) of Object;

property OnDiskRead: TDiskReadEvent read FOnDiskRead write FOnDiskRead;

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.

DiskWrite Event (CBDisk Component)

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

Syntax

type TDiskWriteEvent = procedure (
  Sender: TObject;
  Offset: Int64;
  Buffer: Pointer;
  BytesToWrite: Int64;
  var ResultCode: Integer
) of Object;

property OnDiskWrite: TDiskWriteEvent read FOnDiskWrite write FOnDiskWrite;

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.

Ejected Event (CBDisk Component)

Fires when the media and virtual disk have been ejected.

Syntax

type TEjectedEvent = procedure (
  Sender: TObject;
  var ResultCode: Integer
) of Object;

property OnEjected: TEjectedEvent read FOnEjected write FOnEjected;

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 StorageType property must be set to STGT_DISK_PNP, and the StorageCharacteristics property must include ejection-related flags.

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

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

Error Event (CBDisk Component)

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

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

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.

Flush Event (CBDisk Component)

TBD.

Syntax

type TFlushEvent = procedure (
  Sender: TObject;
  var ResultCode: Integer
) of Object;

property OnFlush: TFlushEvent read FOnFlush write FOnFlush;

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.

GetDiskSize Event (CBDisk Component)

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

Syntax

type TGetDiskSizeEvent = procedure (
  Sender: TObject;
  var Size: Int64;
  var ResultCode: Integer
) of Object;

property OnGetDiskSize: TGetDiskSizeEvent read FOnGetDiskSize write FOnGetDiskSize;

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.

MountingPoint Type

Represents a mounting point for the virtual disk.

Remarks

This type represents a mounting point for the virtual disk.

Fields

Config Settings (CBDisk Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

CBDisk Config Settings

Base Config Settings

Trappable Errors (CBDisk Component)

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

Special Use Errors