Getting Started with the CBCloudDrive Component

Requirements: CBFSCloud

Introduction

The CBCloudDrive component mounts cloud storage services and remote file servers as virtual local drives. Once mounted, the drive is accessible to any application on the system as if it were standard local storage. The component handles the low-level communication with the remote service, local caching of file data, and driver lifecycle management.

The component supports a wide range of connection types. The sections below cover the common setup steps that apply to all connection types. For connection-type-specific configuration details, refer to the relevant guide below.

Guides

Installing the Driver

The CBCloudDrive component requires a kernel-mode driver to create virtual drives on Windows. The driver only needs to be installed once and persists across reboots.

First, set the ProductGUID property to a unique value which should be associated with your application. After that, call GetDriverStatus to check the installation status. A return value of 0 means the driver is not installed; 4 means it is installed and running.

If the driver is not installed, call Install with the path to the cbfs.cab cabinet file included with the product. A non-zero return value indicates a reboot is required to complete the installation.

drive.ProductGUID = "{59B23E1A-119D-4844-AA4E-60E4440646C5}"; int status = drive.GetDriverStatus(); if (status == 0) { int result = drive.Install("/path/to/cbfs.cab"); if (result != 0) { Console.WriteLine("Reboot required to complete driver installation."); return; } }

To uninstall the driver, call Uninstall with the same cabinet file path. Please see the online documentation for additional details and circumstances when this should be used.

Configuring the Connection

Set ConnectionType to identify the remote service, then set ConnectionString to a semicolon-delimited list of connection parameters for that service. The required parameters vary by connection type, see the documentation for more details.

drive.ConnectionType = CBCloudDriveConnectionTypes.ctS3; drive.ConnectionString = "RemoteRoot=/my-bucket;AccessKey=MYACCESSKEY;SecretKey=MYSECRETKEY;";

Two parameters are common across all connection types:

Mounting a Drive

With the driver installed and the connection configured, set the volume name by setting the DriveName property to a descriptive label of your choice (32 characters max). This value will be displayed in File Explorer's tree view.

Next, call Mount to create the virtual drive. Provide a drive letter (e.g., "Z:") or an empty string to let the component pick one automatically. An absolute directory path can also be used to mount the drive as a folder; the directory must already exist and be empty.

drive.DriveName = "My Cloud Drive"; string mountPoint = drive.Mount(""); Console.WriteLine("Drive mounted at: " + mountPoint);

Cache Management

The cache is central to how CBCloudDrive operates and is automatically managed for convenience. File content fetched from the remote service is stored in a disk cache so subsequent reads are served from disk, and all writes are staged in the cache before being uploaded to the remote service in the background.

This lets file operations complete at local disk speeds rather than waiting on network round trips. It also allows interruped uploads to resume if the drive is stopped or connection is lost.

Setting Up the Cache

The CacheDirectory property must be set to a writable local directory path before calling Mount. Each instance of the component corresponds to one virtual drive and should use its own dedicated cache directory.

drive.CacheDirectory = @"C:\MyCloudDrive\cache";

Monitoring Pending Uploads

The ListCacheFiles method returns the current state of the cache as a semicolon-delimited list of virtual file paths. Pass false to list files that have been modified locally but not yet uploaded; pass true to list files that have failed to upload.

string[] pending = drive.ListCacheFiles(false).Split(';'); Console.WriteLine("Files pending upload:"); foreach (string file in pending) Console.WriteLine(" " + file);
string[] conflicts = drive.ListCacheFiles(true).Split(';'); Console.WriteLine("Failed uploads:"); foreach (string file in conflicts) Console.WriteLine(" " + file);

Handling Upload Failures

If an upload fails, the component will retry it automatically up to the number of times configured by the CacheRetryAttempts setting (default: 3). Once all retry attempts are exhausted, the file is marked as conflicted and will no longer be retried. It remains in the cache so the application can detect and respond to the failure. Once the issue is resolved, call DeleteCacheFile with the virtual path of the file to remove it. The virtual path is the path as it appears within the mounted drive (e.g., /documents/report.xlsx), not a physical path on disk. Any unsynced local changes to that file will be discarded.

drive.DeleteCacheFile("/documents/report.xlsx");

Unmounting

Call Unmount to disconnect from the remote service and remove the virtual drive. Check ListCacheFiles(false) beforehand if it is important that all pending writes have been uploaded, as in-progress uploads may be interrupted.

drive.Unmount();

The Mounted property can be checked at any time to determine whether the drive is currently mounted.

Full Example

The following example combines all the steps above into a complete working program using an S3 connection. The pattern is the same for any connection type — only the ConnectionType and ConnectionString values differ.

using callback.CBFSCloud;
CBCloudDrive drive = new CBCloudDrive();
// 1. Install the driver if needed drive.ProductGUID = "{YOUR-PRODUCT-GUID}"; int driverStatus = drive.GetDriverStatus(); if (driverStatus == 0) { int result = drive.Install("/path/to/cbfs.cab"); if (result != 0) { Console.WriteLine("Reboot required to complete driver installation."); return; } }
// 2. Configure the connection drive.ConnectionType = CBCloudDriveConnectionTypes.ctS3; drive.ConnectionString = "RemoteRoot=/my-bucket;AccessKey=MYACCESSKEY;SecretKey=MYSECRETKEY;";
// 3. Configure the cache drive.CacheDirectory = @"C:\my-app\cache"; // CacheEnabledForRead defaults to true
// 4. Mount the drive drive.DriveName = "My Cloud Drive"; string mountPoint = drive.Mount(""); Console.WriteLine("Drive mounted at: " + mountPoint);
// 5. Check cache status string[] pending = drive.ListCacheFiles(false).Split(';'); Console.WriteLine("Files pending upload: " + pending.Length);
string[] conflicts = drive.ListCacheFiles(true).Split(';'); if (conflicts.Length > 0 && conflicts[0] != "") { Console.WriteLine("Failed uploads — removing from cache:"); foreach (string file in conflicts) { Console.WriteLine(" " + file); drive.DeleteCacheFile(file); } }
// 6. Unmount when done drive.Unmount();