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

cbfsdisk.CBDisk

Remarks

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

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

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

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

Getting Started

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

Here's how to get up and running:

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

Property List

---

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

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

func (obj *CBDisk) Active() (bool, error)

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.

Data Type

bool

MountingPointCount Property (CBDisk Component)

The number of records in the MountingPoint arrays.

Syntax

func (obj *CBDisk) MountingPointCount() (int32, error)

Default Value

0

Remarks

This property controls the size of the following arrays:

• MountingPointAuthenticationId
• MountingPointFlags
• MountingPointName

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

This property is read-only.

Data Type

int32

MountingPointAuthenticationId Property (CBDisk Component)

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

Syntax

func (obj *CBDisk) MountingPointAuthenticationId(MountingPointIndex int32) (int64, error)

Default Value

0

Remarks

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

If the STGMP_LOCAL flag is included in the MountingPointFlags 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

int64

MountingPointFlags Property (CBDisk Component)

The flags used to create the mounting point.

Syntax

func (obj *CBDisk) MountingPointFlags(MountingPointIndex int32) (int32, error)

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

int32

MountingPointName Property (CBDisk Component)

The mounting point name.

Syntax

func (obj *CBDisk) MountingPointName(MountingPointIndex int32) (string, error)

Default Value

""

Remarks

The mounting point name.

This property reflects the name of the mounting point (i.e., the value passed to the AddMountingPoint 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

ReadOnly Property (CBDisk Component)

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

Syntax

func (obj *CBDisk) ReadOnly() (bool, error)
func (obj *CBDisk) SetReadOnly(value bool) error

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.

Data Type

bool

StorageCharacteristics Property (CBDisk Component)

The characteristic flags to create the virtual disk with.

Syntax

func (obj *CBDisk) StorageCharacteristics() (int32, error)
func (obj *CBDisk) SetStorageCharacteristics(value int32) error

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.

Data Type

int32

StorageGUID Property (CBDisk Component)

The GUID to create the virtual disk with.

Syntax

func (obj *CBDisk) StorageGUID() (string, error)
func (obj *CBDisk) SetStorageGUID(value string) error

Default Value

""

Remarks

When the StorageType property is set to STGT_DISK_PNP, this property is used to specify a GUID for the virtual disk, and must be set to GUID-formatted string (e.g., {676D0357-A23A-49c3-B433-65AAD72DD282}). Otherwise, this property 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.

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

Data Type

string

StoragePresent Property (CBDisk Component)

Whether a virtual disk has been created.

Syntax

func (obj *CBDisk) StoragePresent() (bool, error)

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.

Data Type

bool

StorageType Property (CBDisk Component)

The type of virtual disk to create.

Syntax

func (obj *CBDisk) StorageType() (int32, error)
func (obj *CBDisk) SetStorageType(value int32) error

Default Value

0

Remarks

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

Possible values are:

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.

Data Type

int32

Tag Property (CBDisk Component)

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

Syntax

func (obj *CBDisk) Tag() (int64, error)
func (obj *CBDisk) SetTag(value int64) error

Default Value

0

Remarks

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

Data Type

int64

AddMountingPoint Method (CBDisk Component)

Adds a mounting point for the virtual disk.

Syntax

func (obj *CBDisk) AddMountingPoint(MountingPoint string, Flags int32, AuthenticationId int64) error

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

func (obj *CBDisk) Config(ConfigurationString string) (string, error)

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

func (obj *CBDisk) CreateStorage() error

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

func (obj *CBDisk) DeleteStorage(ForceUnmount bool) error

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 returns an error.

Note: This method cannot be called within events.

GetDriverStatus Method (CBDisk Component)

Retrieves the status of the system driver.

Syntax

func (obj *CBDisk) GetDriverStatus(ProductGUID string, Module int32) (int32, error)

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

func (obj *CBDisk) GetModuleVersion(ProductGUID string, Module int32) (int64, error)

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

func (obj *CBDisk) Initialize(ProductGUID string) error

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

func (obj *CBDisk) Install(CabFileName string, ProductGUID string, PathToInstall string, ModulesToInstall int32, Flags int32) (int32, error)

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 (0x0522) error.

Note: This method cannot be called within events.

IsIconRegistered Method (CBDisk Component)

Checks whether the specified icon is registered.

Syntax

func (obj *CBDisk) IsIconRegistered(IconId string) (bool, error)

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

func (obj *CBDisk) MountMedia(Timeout int32) error

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 returns an error, and additional information is logged to the Windows system log as described in the Error Reporting and 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 Explorer.

Syntax

func (obj *CBDisk) RegisterIcon(IconPath string, ProductGUID string, IconId string) (bool, error)

Remarks

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

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

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

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

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

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

• 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 (0x0522) error.

Note: This method cannot be called within events.

RemoveMountingPoint Method (CBDisk Component)

Removes a mounting point for the virtual disk.

Syntax

func (obj *CBDisk) RemoveMountingPoint(Index int32, MountingPoint string, Flags int32, AuthenticationId int64) error

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

func (obj *CBDisk) ResetIcon() error

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

Syntax

func (obj *CBDisk) SetIcon(IconId string) error

Remarks

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

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

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

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

func (obj *CBDisk) ShutdownSystem(ShutdownPrompt string, Timeout int32, ForceCloseApps bool, Reboot bool) (bool, error)

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

func (obj *CBDisk) Uninstall(CabFileName string, ProductGUID string, InstalledPath string, Flags int32) (int32, error)

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 (0x0522) error.

Note: This method cannot be called within events.

UnmountMedia Method (CBDisk Component)

Unmounts media from the virtual disk.

Syntax

func (obj *CBDisk) UnmountMedia(ForceUnmount bool) error

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 returns an error.

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

func (obj *CBDisk) UnregisterIcon(ProductGUID string, IconId string) (bool, error)

Remarks

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

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

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

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

Note: This method cannot be called within events.

DiskRead Event (CBDisk Component)

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

Syntax

// CBDiskDiskReadEventArgs carries the CBDisk DiskRead event's parameters.
type CBDiskDiskReadEventArgs struct {...}

func (args *CBDiskDiskReadEventArgs) Offset() int64
func (args *CBDiskDiskReadEventArgs) Buffer() []byte
func (args *CBDiskDiskReadEventArgs) SetBuffer(value []byte)

func (args *CBDiskDiskReadEventArgs) BytesToRead() int64
func (args *CBDiskDiskReadEventArgs) BytesRead() int64
func (args *CBDiskDiskReadEventArgs) SetBytesRead(value int64)

func (args *CBDiskDiskReadEventArgs) ResultCode() int32
func (args *CBDiskDiskReadEventArgs) SetResultCode(value int32)

// CBDiskDiskReadEvent defines the signature of the CBDisk DiskRead event's handler function.
type CBDiskDiskReadEvent func(sender *CBDisk, args *CBDiskDiskReadEventArgs)

func (obj *CBDisk) GetOnDiskReadHandler() CBDiskDiskReadEvent
func (obj *CBDisk) SetOnDiskReadHandler(handlerFunc 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 Reporting and Handling topic for more information.

DiskWrite Event (CBDisk Component)

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

Syntax

// CBDiskDiskWriteEventArgs carries the CBDisk DiskWrite event's parameters.
type CBDiskDiskWriteEventArgs struct {...}

func (args *CBDiskDiskWriteEventArgs) Offset() int64
func (args *CBDiskDiskWriteEventArgs) Buffer() []byte
func (args *CBDiskDiskWriteEventArgs) BytesToWrite() int64
func (args *CBDiskDiskWriteEventArgs) ResultCode() int32
func (args *CBDiskDiskWriteEventArgs) SetResultCode(value int32)

// CBDiskDiskWriteEvent defines the signature of the CBDisk DiskWrite event's handler function.
type CBDiskDiskWriteEvent func(sender *CBDisk, args *CBDiskDiskWriteEventArgs)

func (obj *CBDisk) GetOnDiskWriteHandler() CBDiskDiskWriteEvent
func (obj *CBDisk) SetOnDiskWriteHandler(handlerFunc 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 Reporting and Handling topic for more information.

Ejected Event (CBDisk Component)

Fires when the media and virtual disk have been ejected.

Syntax

// CBDiskEjectedEventArgs carries the CBDisk Ejected event's parameters.
type CBDiskEjectedEventArgs struct {...}

func (args *CBDiskEjectedEventArgs) ResultCode() int32
func (args *CBDiskEjectedEventArgs) SetResultCode(value int32)

// CBDiskEjectedEvent defines the signature of the CBDisk Ejected event's handler function.
type CBDiskEjectedEvent func(sender *CBDisk, args *CBDiskEjectedEventArgs)

func (obj *CBDisk) GetOnEjectedHandler() CBDiskEjectedEvent
func (obj *CBDisk) SetOnEjectedHandler(handlerFunc CBDiskEjectedEvent)

Remarks

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

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

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

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

Error Event (CBDisk Component)

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

Syntax

// CBDiskErrorEventArgs carries the CBDisk Error event's parameters.
type CBDiskErrorEventArgs struct {...}

func (args *CBDiskErrorEventArgs) ErrorCode() int32
func (args *CBDiskErrorEventArgs) Description() string
// CBDiskErrorEvent defines the signature of the CBDisk Error event's handler function.
type CBDiskErrorEvent func(sender *CBDisk, args *CBDiskErrorEventArgs)

func (obj *CBDisk) GetOnErrorHandler() CBDiskErrorEvent
func (obj *CBDisk) SetOnErrorHandler(handlerFunc 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.

Flush Event (CBDisk Component)

TBD.

Syntax

// CBDiskFlushEventArgs carries the CBDisk Flush event's parameters.
type CBDiskFlushEventArgs struct {...}

func (args *CBDiskFlushEventArgs) ResultCode() int32
func (args *CBDiskFlushEventArgs) SetResultCode(value int32)

// CBDiskFlushEvent defines the signature of the CBDisk Flush event's handler function.
type CBDiskFlushEvent func(sender *CBDisk, args *CBDiskFlushEventArgs)

func (obj *CBDisk) GetOnFlushHandler() CBDiskFlushEvent
func (obj *CBDisk) SetOnFlushHandler(handlerFunc 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 Reporting and Handling topic for more information.

GetDiskSize Event (CBDisk Component)

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

Syntax

// CBDiskGetDiskSizeEventArgs carries the CBDisk GetDiskSize event's parameters.
type CBDiskGetDiskSizeEventArgs struct {...}

func (args *CBDiskGetDiskSizeEventArgs) Size() int64
func (args *CBDiskGetDiskSizeEventArgs) SetSize(value int64)

func (args *CBDiskGetDiskSizeEventArgs) ResultCode() int32
func (args *CBDiskGetDiskSizeEventArgs) SetResultCode(value int32)

// CBDiskGetDiskSizeEvent defines the signature of the CBDisk GetDiskSize event's handler function.
type CBDiskGetDiskSizeEvent func(sender *CBDisk, args *CBDiskGetDiskSizeEventArgs)

func (obj *CBDisk) GetOnGetDiskSizeHandler() CBDiskGetDiskSizeEvent
func (obj *CBDisk) SetOnGetDiskSizeHandler(handlerFunc 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 Reporting and Handling topic for more information.

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 Reporting and Handling topic for more information.

Special Use Errors

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