CBFS Class

Properties   Methods   Events   Config Settings   Errors  

The CBFS class gives applications the ability to create a virtual filesystem.

Syntax

CBFS

Remarks

The CBFS class is used to create a virtual filesystem whose contents are stored and exposed in an application-defined manner. The CBFS class's unique and powerful event-based design gives applications the flexibility needed to support a wide range of use cases, ranging from something as simple as translating filesystem calls to files and directories on another storage medium, to something as complex as generating the entire contents of the virtual filesystem on the fly based on some application-specific data source.

Getting Started

Each CBFS class instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the CBFS class if their use case requires the creation of multiple virtual drives; the class's Tag property can be used to distinguish between instances during event handlers.

Here's how to get up and running:

1. If the system driver has not been installed yet, call the Install method to do so. This needs to be done only 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 CBFS class. This must be done each time the application starts (if the application is using multiple CBFS class instances, only the first instance created should be used to call Initialize).
3. Ensure that all of the necessary event handlers have been implemented. Some event handlers, such as OpenFile, ReadFile, GetFileInfo, and EnumerateDirectory are mandatory and must be implemented by all applications (this is not an exhaustive list). Others are optional, and only need to be implemented when certain features are enabled. Please refer to the event's documentation for more information.
4. Create a virtual drive by calling the CreateStorage method.
5. Call the MountMedia method to "insert storage media" into the virtual drive. (This "media" can be changed at any time later using the UnmountMedia and MountMedia methods.)
6. Create one or more Mounting Points for the virtual drive using the AddMountingPoint method. A mounting point can be a drive letter, a UNC path, or a directory on an existing NTFS-formatted drive.
7. Later, the application can unmount the "media" from the virtual drive 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 drive 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 class with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

AccessDeniedProcessCount Property (CBFS Class)

The number of records in the AccessDeniedProcess arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessCount();

Unicode (Windows)
INT GetAccessDeniedProcessCount();

int cbfsconnect_cbfs_getaccessdeniedprocesscount(void* lpObj);

int GetAccessDeniedProcessCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• AccessDeniedProcessDesiredAccess
• AccessDeniedProcessId
• AccessDeniedProcessIncludeChildren
• AccessDeniedProcessName

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

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

Data Type

Integer

AccessDeniedProcessDesiredAccess Property (CBFS Class)

The kind of access granted or denied.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessDesiredAccess(int iAccessDeniedProcessIndex);

Unicode (Windows)
INT GetAccessDeniedProcessDesiredAccess(INT iAccessDeniedProcessIndex);

int cbfsconnect_cbfs_getaccessdeniedprocessdesiredaccess(void* lpObj, int accessdeniedprocessindex);

int GetAccessDeniedProcessDesiredAccess(int iAccessDeniedProcessIndex);

Default Value

0

Remarks

The kind of access granted or denied.

This property specifies what kind of access is granted or denied by the rule. Possible values are:

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

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

Data Type

Integer

AccessDeniedProcessIncludeChildren Property (CBFS Class)

Whether child processes are affected.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessIncludeChildren(int iAccessDeniedProcessIndex);

Unicode (Windows)
BOOL GetAccessDeniedProcessIncludeChildren(INT iAccessDeniedProcessIndex);

int cbfsconnect_cbfs_getaccessdeniedprocessincludechildren(void* lpObj, int accessdeniedprocessindex);

bool GetAccessDeniedProcessIncludeChildren(int iAccessDeniedProcessIndex);

Default Value

FALSE

Remarks

Whether child processes are affected.

This property indicates whether the rule applies to children of the target process.

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

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

Data Type

Boolean

AccessDeniedProcessId Property (CBFS Class)

The Id of the target process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessId(int iAccessDeniedProcessIndex);

Unicode (Windows)
INT GetAccessDeniedProcessId(INT iAccessDeniedProcessIndex);

int cbfsconnect_cbfs_getaccessdeniedprocessid(void* lpObj, int accessdeniedprocessindex);

int GetAccessDeniedProcessId(int iAccessDeniedProcessIndex);

Default Value

0

Remarks

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by AccessDeniedProcessProcessName, or -1 if the rule applies to all processes.

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

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

Data Type

Integer

AccessDeniedProcessName Property (CBFS Class)

The filename of the target process's executable.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccessDeniedProcessName(int iAccessDeniedProcessIndex);

Unicode (Windows)
LPWSTR GetAccessDeniedProcessName(INT iAccessDeniedProcessIndex);

char* cbfsconnect_cbfs_getaccessdeniedprocessname(void* lpObj, int accessdeniedprocessindex);

QString GetAccessDeniedProcessName(int iAccessDeniedProcessIndex);

Default Value

""

Remarks

The filename of the target process's executable.

This property reflects the full filename of the target process's executable. Will be empty if the target process was specified by AccessDeniedProcessProcessId (or if the rule applies to all processes, in which case AccessDeniedProcessProcessId will be -1).

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

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

Data Type

String

AccessGrantedProcessCount Property (CBFS Class)

The number of records in the AccessGrantedProcess arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessCount();

Unicode (Windows)
INT GetAccessGrantedProcessCount();

int cbfsconnect_cbfs_getaccessgrantedprocesscount(void* lpObj);

int GetAccessGrantedProcessCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• AccessGrantedProcessDesiredAccess
• AccessGrantedProcessId
• AccessGrantedProcessIncludeChildren
• AccessGrantedProcessName

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

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

Data Type

Integer

AccessGrantedProcessDesiredAccess Property (CBFS Class)

The kind of access granted or denied.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessDesiredAccess(int iAccessGrantedProcessIndex);

Unicode (Windows)
INT GetAccessGrantedProcessDesiredAccess(INT iAccessGrantedProcessIndex);

int cbfsconnect_cbfs_getaccessgrantedprocessdesiredaccess(void* lpObj, int accessgrantedprocessindex);

int GetAccessGrantedProcessDesiredAccess(int iAccessGrantedProcessIndex);

Default Value

0

Remarks

The kind of access granted or denied.

This property specifies what kind of access is granted or denied by the rule. Possible values are:

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

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

Data Type

Integer

AccessGrantedProcessIncludeChildren Property (CBFS Class)

Whether child processes are affected.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessIncludeChildren(int iAccessGrantedProcessIndex);

Unicode (Windows)
BOOL GetAccessGrantedProcessIncludeChildren(INT iAccessGrantedProcessIndex);

int cbfsconnect_cbfs_getaccessgrantedprocessincludechildren(void* lpObj, int accessgrantedprocessindex);

bool GetAccessGrantedProcessIncludeChildren(int iAccessGrantedProcessIndex);

Default Value

FALSE

Remarks

Whether child processes are affected.

This property indicates whether the rule applies to children of the target process.

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

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

Data Type

Boolean

AccessGrantedProcessId Property (CBFS Class)

The Id of the target process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessId(int iAccessGrantedProcessIndex);

Unicode (Windows)
INT GetAccessGrantedProcessId(INT iAccessGrantedProcessIndex);

int cbfsconnect_cbfs_getaccessgrantedprocessid(void* lpObj, int accessgrantedprocessindex);

int GetAccessGrantedProcessId(int iAccessGrantedProcessIndex);

Default Value

0

Remarks

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by AccessGrantedProcessProcessName, or -1 if the rule applies to all processes.

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

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

Data Type

Integer

AccessGrantedProcessName Property (CBFS Class)

The filename of the target process's executable.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccessGrantedProcessName(int iAccessGrantedProcessIndex);

Unicode (Windows)
LPWSTR GetAccessGrantedProcessName(INT iAccessGrantedProcessIndex);

char* cbfsconnect_cbfs_getaccessgrantedprocessname(void* lpObj, int accessgrantedprocessindex);

QString GetAccessGrantedProcessName(int iAccessGrantedProcessIndex);

Default Value

""

Remarks

The filename of the target process's executable.

This property reflects the full filename of the target process's executable. Will be empty if the target process was specified by AccessGrantedProcessProcessId (or if the rule applies to all processes, in which case AccessGrantedProcessProcessId will be -1).

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

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

Data Type

String

Active Property (CBFS Class)

This property specifies whether the class is active and handling OS requests.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int cbfsconnect_cbfs_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class is currently active and handling OS requests.

The property will be true once both CreateStorage and MountMedia have been called.

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

Data Type

Boolean

FileCache Property (CBFS Class)

This property specifies which file data cache implementation to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFileCache();
int SetFileCache(int iFileCache);

Unicode (Windows)
INT GetFileCache();
INT SetFileCache(INT iFileCache);

FC_NONE(0), 
FC_SYSTEM(1), 
FC_INTERNAL_KERNEL_MODE(2), 
FC_INTERNAL_USER_MODE(3)

int cbfsconnect_cbfs_getfilecache(void* lpObj);
int cbfsconnect_cbfs_setfilecache(void* lpObj, int iFileCache);

int GetFileCache();
int SetFileCache(int iFileCache);

Default Value

1

Remarks

This property specifies which file data cache implementation a virtual drive should use, if any. Possible values are as follows:

• fcNone (0): Do not use file data caching.
• fcSystem (1, default): Delegate file data caching to the Windows file management system cache (recommended).
• fcInternalKernelMode (2): Use the CBFS kernel mode file data cache implementation.
• fcInternalUserMode (3): Use the CBFS user mode file data cache implementation.

When set to fcInternalUserMode (3), the UserModeFileCacheSize configuration setting can be used to control the cache size.

Please refer to the Caching topic for detailed information on each of the cache implementations.

Note: This property cannot be changed within events.

Data Type

Integer

FileSystemName Property (CBFS Class)

The name of the virtual filesystem.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFileSystemName();
int SetFileSystemName(const char* lpszFileSystemName);

Unicode (Windows)
LPWSTR GetFileSystemName();
INT SetFileSystemName(LPCWSTR lpszFileSystemName);

char* cbfsconnect_cbfs_getfilesystemname(void* lpObj);
int cbfsconnect_cbfs_setfilesystemname(void* lpObj, const char* lpszFileSystemName);

QString GetFileSystemName();
int SetFileSystemName(QString qsFileSystemName);

Default Value

"FAT32"

Remarks

This property specifies the name of the virtual filesystem. Windows, and some other applications, use this name to identify the filesystem.

In general, the filesystem name can be any reasonable string up to 10 characters in length. However, some versions of Windows and some third-party programs may behave differently when they encounter an unknown filesystem name (i.e., anything other than FAT, FAT32, exFAT, NTFS, etc.). Applications should keep this restriction in mind when choosing a filesystem name.

This property is set to FAT32 by default, which may cause some applications to fail when attempting to copy large (>4GB) files to and from the virtual drive. It is recommended that applications set this property to exFAT if such issues occur.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

String

FireAllOpenCloseEvents Property (CBFS Class)

This property specifies whether to fire events for all file open/close operations, or just the first and last.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFireAllOpenCloseEvents();
int SetFireAllOpenCloseEvents(int bFireAllOpenCloseEvents);

Unicode (Windows)
BOOL GetFireAllOpenCloseEvents();
INT SetFireAllOpenCloseEvents(BOOL bFireAllOpenCloseEvents);

int cbfsconnect_cbfs_getfireallopencloseevents(void* lpObj);
int cbfsconnect_cbfs_setfireallopencloseevents(void* lpObj, int bFireAllOpenCloseEvents);

bool GetFireAllOpenCloseEvents();
int SetFireAllOpenCloseEvents(bool bFireAllOpenCloseEvents);

Default Value

FALSE

Remarks

This property specifies when the class should fire the CreateFile/OpenFile and CleanupFile/CloseFile events.

When this property is disabled (default), the class will not fire CreateFile/OpenFile for a file if another handle is already open for it. Similarly, the CleanupFile/CloseFile events will not be fired unless the handle being closed is the last handle open for the file in question. This behavior results in better overall performance because the number of event firings is minimized, but there are some drawbacks as well:

• If the file is opened only for reading initially, and then another process opens it for writing, the application will not be notified about the new mode, and may not be prepared to respond to the "unexpected" WriteFile events that will arrive should the second process start writing to the file. (Such an application may be able to mitigate this issue by always opening the file data from the backend store in read-write mode.)
• The HandleInfo parameter of various events has no effect; they carry handle-specific information that is not accessible to the application if this property is disabled.

When this property is enabled, the class fires the CreateFile/OpenFile and CleanupFile/CloseFile events every time a file handle is opened or closed.

This table shows when events will fire based on how this property is set:

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

Data Type

Boolean

HandleAllFsctls Property (CBFS Class)

This property specifies whether or not to fire the Fsctl event for all FSCTL_* requests.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetHandleAllFsctls();
int SetHandleAllFsctls(int bHandleAllFsctls);

Unicode (Windows)
BOOL GetHandleAllFsctls();
INT SetHandleAllFsctls(BOOL bHandleAllFsctls);

int cbfsconnect_cbfs_gethandleallfsctls(void* lpObj);
int cbfsconnect_cbfs_sethandleallfsctls(void* lpObj, int bHandleAllFsctls);

bool GetHandleAllFsctls();
int SetHandleAllFsctls(bool bHandleAllFsctls);

Default Value

FALSE

Remarks

This property specifies when the class should fire the Fsctl event. When disabled (default), the Fsctl event will fire only for FSCTLs whose function codes are in the 2400-4096 range (these codes are reserved by CBFS Connect for application use). When enabled, this Fsctl will fire for every FSCTL, except those processed by CBFS Connect itself.

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

Data Type

Boolean

MaxFileNameLength Property (CBFS Class)

This property includes the maximum filename length supported by the virtual filesystem.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMaxFileNameLength();
int SetMaxFileNameLength(int iMaxFileNameLength);

Unicode (Windows)
INT GetMaxFileNameLength();
INT SetMaxFileNameLength(INT iMaxFileNameLength);

int cbfsconnect_cbfs_getmaxfilenamelength(void* lpObj);
int cbfsconnect_cbfs_setmaxfilenamelength(void* lpObj, int iMaxFileNameLength);

int GetMaxFileNameLength();
int SetMaxFileNameLength(int iMaxFileNameLength);

Default Value

260

Remarks

This property specifies the virtual filesystem's maximum supported filename length, measured in characters. Setting this property to a value less than its default of 260 characters, which corresponds to Windows' MAX_PATH constant, is not recommended.

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

Data Type

Integer

MaxFilePathLength Property (CBFS Class)

This property includes the maximum file path length supported by the virtual filesystem.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMaxFilePathLength();
int SetMaxFilePathLength(int iMaxFilePathLength);

Unicode (Windows)
INT GetMaxFilePathLength();
INT SetMaxFilePathLength(INT iMaxFilePathLength);

int cbfsconnect_cbfs_getmaxfilepathlength(void* lpObj);
int cbfsconnect_cbfs_setmaxfilepathlength(void* lpObj, int iMaxFilePathLength);

int GetMaxFilePathLength();
int SetMaxFilePathLength(int iMaxFilePathLength);

Default Value

32767

Remarks

This property specifies the virtual filesystem's maximum supported file path length, measured in characters; where file path means "a string containing all directory names plus the name of the file itself". Setting this property to a value of less than 260 characters, which corresponds to Windows' MAX_PATH constant, is not recommended.

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

Data Type

Integer

MaxFileSize Property (CBFS Class)

This property includes the maximum file size supported by the virtual filesystem.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetMaxFileSize();
int SetMaxFileSize(int64 lMaxFileSize);

Unicode (Windows)
LONG64 GetMaxFileSize();
INT SetMaxFileSize(LONG64 lMaxFileSize);

int64 cbfsconnect_cbfs_getmaxfilesize(void* lpObj);
int cbfsconnect_cbfs_setmaxfilesize(void* lpObj, int64 lMaxFileSize);

qint64 GetMaxFileSize();
int SetMaxFileSize(qint64 lMaxFileSize);

Default Value

0

Remarks

This property specifies the maximum file size, in bytes, supported by the virtual filesystem. The default value of 0 means "no limit".

Note: This property cannot be changed within events.

Data Type

Long64

MetadataCacheEnabled Property (CBFS Class)

This property specifies whether or not the metadata cache should be used.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMetadataCacheEnabled();
int SetMetadataCacheEnabled(int bMetadataCacheEnabled);

Unicode (Windows)
BOOL GetMetadataCacheEnabled();
INT SetMetadataCacheEnabled(BOOL bMetadataCacheEnabled);

int cbfsconnect_cbfs_getmetadatacacheenabled(void* lpObj);
int cbfsconnect_cbfs_setmetadatacacheenabled(void* lpObj, int bMetadataCacheEnabled);

bool GetMetadataCacheEnabled();
int SetMetadataCacheEnabled(bool bMetadataCacheEnabled);

Default Value

TRUE

Remarks

This property controls whether the file metadata cache is enabled for a virtual drive. The size of the file metadata cache can be controlled using the MetadataCacheSize property.

When enabled, the class caches file information obtained via EnumerateDirectory and GetFileInfo events and uses the cached metadata to serve operating system requests, thus reducing how often the GetFileInfo events fire.

While a file or directory is open, its metadata is kept available in a special record called a File Control Block, regardless of whether or not the metadata cache is enabled.

For closed files and directories, the metadata is kept in the cache for the time, defined by the UnusedMetadataLifetime configuration setting.

Please refer to the Caching topic for more information.

Note: This property cannot be changed within events.

Data Type

Boolean

MetadataCacheSize Property (CBFS Class)

This property includes the size of the metadata cache.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMetadataCacheSize();
int SetMetadataCacheSize(int iMetadataCacheSize);

Unicode (Windows)
INT GetMetadataCacheSize();
INT SetMetadataCacheSize(INT iMetadataCacheSize);

int cbfsconnect_cbfs_getmetadatacachesize(void* lpObj);
int cbfsconnect_cbfs_setmetadatacachesize(void* lpObj, int iMetadataCacheSize);

int GetMetadataCacheSize();
int SetMetadataCacheSize(int iMetadataCacheSize);

Default Value

2048

Remarks

This property specifies the size of the file metadata cache as a number of entries. The value must be a positive number. The maximum valid value is 65536.

Please refer to the MetadataCacheEnabled property, as well as the Caching topic, for more information.

Note: This property cannot be changed within events.

Data Type

Integer

MountingPointCount Property (CBFS Class)

The number of records in the MountingPoint arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMountingPointCount();

Unicode (Windows)
INT GetMountingPointCount();

int cbfsconnect_cbfs_getmountingpointcount(void* lpObj);

int GetMountingPointCount();

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 and not available at design time.

Data Type

Integer

MountingPointAuthenticationId Property (CBFS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetMountingPointAuthenticationId(int iMountingPointIndex);

Unicode (Windows)
LONG64 GetMountingPointAuthenticationId(INT iMountingPointIndex);

int64 cbfsconnect_cbfs_getmountingpointauthenticationid(void* lpObj, int mountingpointindex);

qint64 GetMountingPointAuthenticationId(int iMountingPointIndex);

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 and not available at design time.

Data Type

Long64

MountingPointFlags Property (CBFS Class)

The flags used to create the mounting point.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMountingPointFlags(int iMountingPointIndex);

Unicode (Windows)
INT GetMountingPointFlags(INT iMountingPointIndex);

int cbfsconnect_cbfs_getmountingpointflags(void* lpObj, int mountingpointindex);

int GetMountingPointFlags(int iMountingPointIndex);

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 and not available at design time.

Data Type

Integer

MountingPointName Property (CBFS Class)

The mounting point name.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMountingPointName(int iMountingPointIndex);

Unicode (Windows)
LPWSTR GetMountingPointName(INT iMountingPointIndex);

char* cbfsconnect_cbfs_getmountingpointname(void* lpObj, int mountingpointindex);

QString GetMountingPointName(int iMountingPointIndex);

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 and not available at design time.

Data Type

String

NonExistentFilesCacheEnabled Property (CBFS Class)

This property specifies whether or not the nonexistent files cache should be used.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetNonExistentFilesCacheEnabled();
int SetNonExistentFilesCacheEnabled(int bNonExistentFilesCacheEnabled);

Unicode (Windows)
BOOL GetNonExistentFilesCacheEnabled();
INT SetNonExistentFilesCacheEnabled(BOOL bNonExistentFilesCacheEnabled);

int cbfsconnect_cbfs_getnonexistentfilescacheenabled(void* lpObj);
int cbfsconnect_cbfs_setnonexistentfilescacheenabled(void* lpObj, int bNonExistentFilesCacheEnabled);

bool GetNonExistentFilesCacheEnabled();
int SetNonExistentFilesCacheEnabled(bool bNonExistentFilesCacheEnabled);

Default Value

TRUE

Remarks

This property controls whether the nonexistent files cache is enabled for a virtual drive. The size of the nonexistent files cache can be controlled using the NonExistentFilesCacheSize property.

When enabled, the class will cache any GetFileInfo responses that indicate that the requested file does not exist. If another request is later made for the same file, the class will use this information to automatically report a file not found error rather than firing the GetFileInfo event again.

Please refer to the Caching topic for more information.

Note: This property cannot be changed within events.

Data Type

Boolean

NonExistentFilesCacheSize Property (CBFS Class)

This property includes the size of the nonexistent files cache.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetNonExistentFilesCacheSize();
int SetNonExistentFilesCacheSize(int iNonExistentFilesCacheSize);

Unicode (Windows)
INT GetNonExistentFilesCacheSize();
INT SetNonExistentFilesCacheSize(INT iNonExistentFilesCacheSize);

int cbfsconnect_cbfs_getnonexistentfilescachesize(void* lpObj);
int cbfsconnect_cbfs_setnonexistentfilescachesize(void* lpObj, int iNonExistentFilesCacheSize);

int GetNonExistentFilesCacheSize();
int SetNonExistentFilesCacheSize(int iNonExistentFilesCacheSize);

Default Value

2048

Remarks

This property specifies the maximum size of the nonexistent files cache as a number of entries. The value must be a positive number. The maximum valid value is 65536.

Please refer to the NonExistentFilesCacheEnabled property, as well as the Caching topic, for more information.

Note: This property cannot be changed within events.

Data Type

Integer

OpenFilesCount Property (CBFS Class)

The number of records in the OpenFile arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenFilesCount();

Unicode (Windows)
INT GetOpenFilesCount();

int cbfsconnect_cbfs_getopenfilescount(void* lpObj);

int GetOpenFilesCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• OpenFileHandleClosed
• OpenFileName
• OpenFileProcessId
• OpenFileProcessName

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

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

Data Type

Integer

OpenFileHandleClosed Property (CBFS Class)

This property reflects whether the handle to the file has been closed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenFileHandleClosed(int iOpenFileIndex);

Unicode (Windows)
BOOL GetOpenFileHandleClosed(INT iOpenFileIndex);

int cbfsconnect_cbfs_getopenfilehandleclosed(void* lpObj, int openfileindex);

bool GetOpenFileHandleClosed(int iOpenFileIndex);

Default Value

FALSE

Remarks

This property reflects whether the handle to the file has been closed.

This property reflects whether the handle to the file has been closed.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

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

Data Type

Boolean

OpenFileName Property (CBFS Class)

This property reflects the name of the open file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOpenFileName(int iOpenFileIndex);

Unicode (Windows)
LPWSTR GetOpenFileName(INT iOpenFileIndex);

char* cbfsconnect_cbfs_getopenfilename(void* lpObj, int openfileindex);

QString GetOpenFileName(int iOpenFileIndex);

Default Value

""

Remarks

This property reflects the name of the open file.

This property reflects the name of the open file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

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

Data Type

String

OpenFileProcessId Property (CBFS Class)

This property reflects the Id of the process that opened the file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenFileProcessId(int iOpenFileIndex);

Unicode (Windows)
INT GetOpenFileProcessId(INT iOpenFileIndex);

int cbfsconnect_cbfs_getopenfileprocessid(void* lpObj, int openfileindex);

int GetOpenFileProcessId(int iOpenFileIndex);

Default Value

0

Remarks

This property reflects the Id of the process that opened the file.

This property reflects the Id of the process (PID) that opened the file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

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

Data Type

Integer

OpenFileProcessName Property (CBFS Class)

This property reflects the name of the process that opened the file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOpenFileProcessName(int iOpenFileIndex);

Unicode (Windows)
LPWSTR GetOpenFileProcessName(INT iOpenFileIndex);

char* cbfsconnect_cbfs_getopenfileprocessname(void* lpObj, int openfileindex);

QString GetOpenFileProcessName(int iOpenFileIndex);

Default Value

""

Remarks

This property reflects the name of the process that opened the file.

This property reflects the name of the process that opened the file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

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

Data Type

String

OpenHandlesCount Property (CBFS Class)

This property includes the number of handles to filesystem objects in the virtual drive that are currently open.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenHandlesCount();

Unicode (Windows)
INT GetOpenHandlesCount();

int cbfsconnect_cbfs_getopenhandlescount(void* lpObj);

int GetOpenHandlesCount();

Default Value

0

Remarks

This property reflects the number of handles to filesystem objects (e.g., files, directories) in the virtual drive that are currently open. It is populated when CreateOpenedFilesSnapshot is called, and cleared when CloseOpenedFilesSnapshot is called; please refer to those methods for more information.

This property's value may differ from that of the OpenObjectsCount property, and from the number of items in the OpenFile* properties. This occurs because each object can be opened several times, and because the OS may keep files open even after all handles to them have been closed.

Note: The methods and properties related to open files snapshots 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 creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

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

Data Type

Integer

OpenObjectsCount Property (CBFS Class)

This property includes the number of filesystem objects in the virtual drive that are currently open.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenObjectsCount();

Unicode (Windows)
INT GetOpenObjectsCount();

int cbfsconnect_cbfs_getopenobjectscount(void* lpObj);

int GetOpenObjectsCount();

Default Value

0

Remarks

This property reflects the number of filesystem objects (e.g., files, directories) in the virtual drive that are currently open. It is populated when CreateOpenedFilesSnapshot is called and cleared when CloseOpenedFilesSnapshot is called; please refer to those methods for more information.

This property's value may differ from that of the OpenHandlesCount property, and from the number of items in the OpenFile* properties. This occurs because each object can be opened several times, and because the OS may keep files open even after all handles to them have been closed.

Note: The methods and properties related to open files snapshots 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 creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

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

Data Type

Integer

ProcessRestrictionsEnabled Property (CBFS Class)

Whether process access restrictions are enabled.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProcessRestrictionsEnabled();
int SetProcessRestrictionsEnabled(int bProcessRestrictionsEnabled);

Unicode (Windows)
BOOL GetProcessRestrictionsEnabled();
INT SetProcessRestrictionsEnabled(BOOL bProcessRestrictionsEnabled);

int cbfsconnect_cbfs_getprocessrestrictionsenabled(void* lpObj);
int cbfsconnect_cbfs_setprocessrestrictionsenabled(void* lpObj, int bProcessRestrictionsEnabled);

bool GetProcessRestrictionsEnabled();
int SetProcessRestrictionsEnabled(bool bProcessRestrictionsEnabled);

Default Value

FALSE

Remarks

This property controls whether the class should enforce per-process access restrictions; by default, it is disabled. When enabled, the AddGrantedProcess and AddDeniedProcess methods can be used to add process-specific access rules for the class to enforce across the entire virtual drive.

When an application enables this propery, it should use the AddGrantedProcess method to add at least one pocess as allowed; otherwise, the data will be inaccessible.

The current process access rules are reflected by the AccessGrantedProcess* and AccessDeniedProcess* properties.

Note: The methods and properties related to process access lists 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 process access information occurs in a thread-safe manner.

Data Type

Boolean

SerializeAccess Property (CBFS Class)

This property specifies whether nonintersecting operations against the same file should execute serially or in parallel.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSerializeAccess();
int SetSerializeAccess(int bSerializeAccess);

Unicode (Windows)
BOOL GetSerializeAccess();
INT SetSerializeAccess(BOOL bSerializeAccess);

int cbfsconnect_cbfs_getserializeaccess(void* lpObj);
int cbfsconnect_cbfs_setserializeaccess(void* lpObj, int bSerializeAccess);

bool GetSerializeAccess();
int SetSerializeAccess(bool bSerializeAccess);

Default Value

TRUE

Remarks

This property specifies whether the class should force nonintersecting operations against a single file or directory to execute serially (default), or allow them to execute in parallel.

Parallel processing can speed up operations, to a certain extent. When this property is disabled, and two or more requests (which do not change filesystem information) are made against the same file or directory, those requests are surfaced in parallel through the appropriate events (assuming that enough worker threads are available to service them at the time). By default, this property is enabled, and such requests are serialized. Please refer to the Threading and Concurrency topic for more information.

Note: For parallel processing to work, the SerializeEvents property must be disabled, and the MinWorkerThreadCount and MaxWorkerThreadCount configuration settings must be set such that parallel processing can actually occur.

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

Data Type

Boolean

SerializeEvents Property (CBFS Class)

Whether events should be fired on a single worker thread, or many.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Unicode (Windows)
INT GetSerializeEvents();
INT SetSerializeEvents(INT iSerializeEvents);

SE_ON_MULTIPLE_THREADS(0), 
SE_ON_ONE_WORKER_THREAD(1)

int cbfsconnect_cbfs_getserializeevents(void* lpObj);
int cbfsconnect_cbfs_setserializeevents(void* lpObj, int iSerializeEvents);

int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Default Value

0

Remarks

This property specifies whether the class should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:

Please note that, in general, the class will always fire events related to a single file sequentially (though not necessarily on the same worker thread all the time), regardless of how this property is set. The one exception is that, if this property is set to seOnMultipleThreads, the SerializeAccess property can be enabled to allow multiple read requests made against a single file to execute concurrently. Please refer to the Threading and Concurrency topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Integer

StorageCharacteristics Property (CBFS Class)

The characteristic flags to create the virtual drive with (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetStorageCharacteristics();
int SetStorageCharacteristics(int iStorageCharacteristics);

Unicode (Windows)
INT GetStorageCharacteristics();
INT SetStorageCharacteristics(INT iStorageCharacteristics);

int cbfsconnect_cbfs_getstoragecharacteristics(void* lpObj);
int cbfsconnect_cbfs_setstoragecharacteristics(void* lpObj, int iStorageCharacteristics);

int GetStorageCharacteristics();
int SetStorageCharacteristics(int iStorageCharacteristics);

Default Value

16

Remarks

The system, as well as other applications, use these flags to optimize their use of the virtual drive. 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 drive is created, and it cannot be changed within events.

Data Type

Integer

StorageGUID Property (CBFS Class)

The GUID to create the virtual drive with.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetStorageGUID();
int SetStorageGUID(const char* lpszStorageGUID);

Unicode (Windows)
LPWSTR GetStorageGUID();
INT SetStorageGUID(LPCWSTR lpszStorageGUID);

char* cbfsconnect_cbfs_getstorageguid(void* lpObj);
int cbfsconnect_cbfs_setstorageguid(void* lpObj, const char* lpszStorageGUID);

QString GetStorageGUID();
int SetStorageGUID(QString qsStorageGUID);

Default Value

""

Remarks

This property is used to specify a GUID for the virtual drive, 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 drive is mounted.

Some software uses a drive'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 drive 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 drive is created, and it cannot be changed within events.

Data Type

String

StoragePresent Property (CBFS Class)

This property specifies whether a virtual drive has been created.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetStoragePresent();

Unicode (Windows)
BOOL GetStoragePresent();

int cbfsconnect_cbfs_getstoragepresent(void* lpObj);

bool GetStoragePresent();

Default Value

FALSE

Remarks

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

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

Data Type

Boolean

StorageType Property (CBFS Class)

The type of virtual drive to create (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetStorageType();
int SetStorageType(int iStorageType);

Unicode (Windows)
INT GetStorageType();
INT SetStorageType(INT iStorageType);

int cbfsconnect_cbfs_getstoragetype(void* lpObj);
int cbfsconnect_cbfs_setstoragetype(void* lpObj, int iStorageType);

int GetStorageType();
int SetStorageType(int iStorageType);

Default Value

0

Remarks

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

Possible values are:

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

Plug-and-play Virtual Drives

Virtual drives 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 drive's media is removable or non-removable, plug-and-play virtual drives also support the STGC_ALLOW_EJECTION flag, which specifies whether a virtual drive itself is removable or non-removable.

Data Type

Integer

SupportChangeTimeAttribute Property (CBFS Class)

This property specifies whether the virtual filesystem supports the ChangeTime file attribute.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSupportChangeTimeAttribute();
int SetSupportChangeTimeAttribute(int bSupportChangeTimeAttribute);

Unicode (Windows)
BOOL GetSupportChangeTimeAttribute();
INT SetSupportChangeTimeAttribute(BOOL bSupportChangeTimeAttribute);

int cbfsconnect_cbfs_getsupportchangetimeattribute(void* lpObj);
int cbfsconnect_cbfs_setsupportchangetimeattribute(void* lpObj, int bSupportChangeTimeAttribute);

bool GetSupportChangeTimeAttribute();
int SetSupportChangeTimeAttribute(bool bSupportChangeTimeAttribute);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports the ChangeTime file attribute, which tracks the last time a file's metadata (e.g., permissions) or content was changed. The ChangeTime attribute is optional, and applications can choose not to handle it in events by simply leaving the value of the corresponding parameter unchanged.

Note: If the application is identifying its virtual filesystem (via FileSystemName) as NTFS, and this property is disabled, the class will still handle the ChangeTime attribute implicitly by setting it equal to LastWriteTime.

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

Data Type

Boolean

SupportCompressedAttribute Property (CBFS Class)

This property specifies whether the virtual filesystem supports the Compressed file attribute.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSupportCompressedAttribute();
int SetSupportCompressedAttribute(int bSupportCompressedAttribute);

Unicode (Windows)
BOOL GetSupportCompressedAttribute();
INT SetSupportCompressedAttribute(BOOL bSupportCompressedAttribute);

int cbfsconnect_cbfs_getsupportcompressedattribute(void* lpObj);
int cbfsconnect_cbfs_setsupportcompressedattribute(void* lpObj, int bSupportCompressedAttribute);

bool GetSupportCompressedAttribute();
int SetSupportCompressedAttribute(bool bSupportCompressedAttribute);

Default Value

FALSE

Remarks

When enabled, this property tells the driver to report support of compression to the operating system. When such a support is reported, processes may read or change the Compressed attribute of a file. An implementation of a virtual filesystem should provide the Compressed status through the file attributes in the GetFileInfo and EnumerateDirectory events. The attribute may be changed by the system, and such a change is communicated to the implementation by the Attributes parameter in the SetFileAttributes event.

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

Data Type

Boolean

SupportLastAccessTimeAttribute Property (CBFS Class)

This property specifies whether the virtual filesystem supports the LastAccessTime file attribute.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSupportLastAccessTimeAttribute();
int SetSupportLastAccessTimeAttribute(int bSupportLastAccessTimeAttribute);

Unicode (Windows)
BOOL GetSupportLastAccessTimeAttribute();
INT SetSupportLastAccessTimeAttribute(BOOL bSupportLastAccessTimeAttribute);

int cbfsconnect_cbfs_getsupportlastaccesstimeattribute(void* lpObj);
int cbfsconnect_cbfs_setsupportlastaccesstimeattribute(void* lpObj, int bSupportLastAccessTimeAttribute);

bool GetSupportLastAccessTimeAttribute();
int SetSupportLastAccessTimeAttribute(bool bSupportLastAccessTimeAttribute);

Default Value

TRUE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports the LastAccessTime file attribute, which tracks the last time a file's contents were accessed.

When this property is enabled (default), a file's LastAccessTime attribute gets updated whenever the file is closed (unless fewer than 60 seconds have elapsed since the previous LastAccessTime). When this property is disabled, a file's LastAccessTime is still tracked and passed along with its LastWriteTime when the latter is changed, but it is not updated separately when the file is closed.

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

Data Type

Boolean

SupportODXReadWrite Property (CBFS Class)

This property specifies whether the virtual filesystem supports ODX (Offloaded Data Transfer) operations.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSupportODXReadWrite();
int SetSupportODXReadWrite(int bSupportODXReadWrite);

Unicode (Windows)
BOOL GetSupportODXReadWrite();
INT SetSupportODXReadWrite(BOOL bSupportODXReadWrite);

int cbfsconnect_cbfs_getsupportodxreadwrite(void* lpObj);
int cbfsconnect_cbfs_setsupportodxreadwrite(void* lpObj, int bSupportODXReadWrite);

bool GetSupportODXReadWrite();
int SetSupportODXReadWrite(bool bSupportODXReadWrite);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports ODX (Offloaded Data Transfer) operations. Please refer to Microsoft's Offloaded Data Transfer article for more information.

If this property is enabled, the application must properly handle the OffloadReadFile and OffloadWriteFile events, which will fire anytime the OS sends an offload read or offload write request to the virtual filesystem.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

Tag Property (CBFS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetTag();
int SetTag(int64 lTag);

Unicode (Windows)
LONG64 GetTag();
INT SetTag(LONG64 lTag);

int64 cbfsconnect_cbfs_gettag(void* lpObj);
int cbfsconnect_cbfs_settag(void* lpObj, int64 lTag);

qint64 GetTag();
int SetTag(qint64 lTag);

Default Value

0

Remarks

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

Data Type

Long64

UseAlternateDataStreams Property (CBFS Class)

This property specifies whether or not the virtual filesystem supports alternate data streams.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseAlternateDataStreams();
int SetUseAlternateDataStreams(int bUseAlternateDataStreams);

Unicode (Windows)
BOOL GetUseAlternateDataStreams();
INT SetUseAlternateDataStreams(BOOL bUseAlternateDataStreams);

int cbfsconnect_cbfs_getusealternatedatastreams(void* lpObj);
int cbfsconnect_cbfs_setusealternatedatastreams(void* lpObj, int bUseAlternateDataStreams);

bool GetUseAlternateDataStreams();
int SetUseAlternateDataStreams(bool bUseAlternateDataStreams);

Default Value

FALSE

Remarks

This property specifies whether or not the virtual filesystem should indicate to the system that it supports alternate data streams (ADS, otherwise known as "named streams"). Alternate data streams can be present in both files and directories.

If this property is enabled, the application must properly handle the EnumerateNamedStreams and CloseNamedStreamsEnumeration events for alternate data streams to function correctly. Additionally, the application's GetFileInfo and EnumerateDirectory event handlers must take into account requests made by the OS to work with the alternate data streams.

Note: Alternate data streams are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting alternate data streams is recommended.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseCaseSensitiveFileNames Property (CBFS Class)

This property specifies whether the virtual filesystem is case-sensitive or just case-preserving.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseCaseSensitiveFileNames();
int SetUseCaseSensitiveFileNames(int bUseCaseSensitiveFileNames);

Unicode (Windows)
BOOL GetUseCaseSensitiveFileNames();
INT SetUseCaseSensitiveFileNames(BOOL bUseCaseSensitiveFileNames);

int cbfsconnect_cbfs_getusecasesensitivefilenames(void* lpObj);
int cbfsconnect_cbfs_setusecasesensitivefilenames(void* lpObj, int bUseCaseSensitiveFileNames);

bool GetUseCaseSensitiveFileNames();
int SetUseCaseSensitiveFileNames(bool bUseCaseSensitiveFileNames);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it is case-sensitive (true) or just case-preserving (false; default).

Traditionally, Windows uses a case-insensitive filesystem architecture. The NTFS filesystem has a case-sensitive mode, however, to support a POSIX subsystem; enabling this property will make the class behave in a manner similar to NTFS with regards to case-sensitivity by doing the following:

• Informing Windows that it supports preserving filename casing (which the application must actually do in its code).
• Working in a case-sensitive manner when managing caches.
• Firing the GetFileInfo event to obtain a real filename if a mixed-case name is encountered.

In addition to enabling this property, a flag must be set in the registry for case-sensitive filename support to work. Specifically, in the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel registry key, the DWORD ObCaseInsensitive must be set to 0.

Note: The class always attempts to work with case-sensitive filenames, regardless of how this property is set. When a file is being opened, the CBFS Connect driver looks for the name of the file in the metadata cache, if an exact match is not found, the GetFileInfo event is fired to allow the application to supply a corrected filename through the RealFileName parameter. If the application chooses not to do so, the case-insensitive name will be used.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseDirectoryEmptyCheck Property (CBFS Class)

This property specifies whether the IsDirectoryEmpty event should be used.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseDirectoryEmptyCheck();
int SetUseDirectoryEmptyCheck(int bUseDirectoryEmptyCheck);

Unicode (Windows)
BOOL GetUseDirectoryEmptyCheck();
INT SetUseDirectoryEmptyCheck(BOOL bUseDirectoryEmptyCheck);

int cbfsconnect_cbfs_getusedirectoryemptycheck(void* lpObj);
int cbfsconnect_cbfs_setusedirectoryemptycheck(void* lpObj, int bUseDirectoryEmptyCheck);

bool GetUseDirectoryEmptyCheck();
int SetUseDirectoryEmptyCheck(bool bUseDirectoryEmptyCheck);

Default Value

TRUE

Remarks

This property specifies whether the class should fire the IsDirectoryEmpty event when the OS needs to check whether a directory is empty. Such checks typically are performed just before the OS requests that a directory be deleted.

If this property is enabled (default), the application must properly handle the IsDirectoryEmpty event.

Note: Use of the IsDirectoryEmpty event is efficient only if the virtual filesystem has a fast way to check whether directories contain any entries (e.g., files, subdirectories, links). If such a check would require enumerating child entries, it is more efficient for the application to disable this property and perform the check directly within the CanFileBeDeleted event instead.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseDiskQuotas Property (CBFS Class)

This property specifies whether the virtual filesystem supports disk quotas.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseDiskQuotas();
int SetUseDiskQuotas(int bUseDiskQuotas);

Unicode (Windows)
BOOL GetUseDiskQuotas();
INT SetUseDiskQuotas(BOOL bUseDiskQuotas);

int cbfsconnect_cbfs_getusediskquotas(void* lpObj);
int cbfsconnect_cbfs_setusediskquotas(void* lpObj, int bUseDiskQuotas);

bool GetUseDiskQuotas();
int SetUseDiskQuotas(bool bUseDiskQuotas);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports disk quota management.

If this property is enabled, the application must properly handle the QueryQuotas, SetQuotas, GetDefaultQuotaInfo, and SetDefaultQuotaInfo events for quota management to function correctly. The GetFileNameByFileId event must be handled as well.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseFileIds Property (CBFS Class)

This property specifies whether the virtual filesystem supports file Ids.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseFileIds();
int SetUseFileIds(int bUseFileIds);

Unicode (Windows)
BOOL GetUseFileIds();
INT SetUseFileIds(BOOL bUseFileIds);

int cbfsconnect_cbfs_getusefileids(void* lpObj);
int cbfsconnect_cbfs_setusefileids(void* lpObj, int bUseFileIds);

bool GetUseFileIds();
int SetUseFileIds(bool bUseFileIds);

Default Value

TRUE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports File IDs.

If this property is enabled, the application must properly handle the GetFileInfo and EnumerateDirectory events and return proper file Ids for files and directories. The GetFileNameByFileId event must be handled as well.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseHardLinks Property (CBFS Class)

This property specifies whether the virtual filesystem supports hard links.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseHardLinks();
int SetUseHardLinks(int bUseHardLinks);

Unicode (Windows)
BOOL GetUseHardLinks();
INT SetUseHardLinks(BOOL bUseHardLinks);

int cbfsconnect_cbfs_getusehardlinks(void* lpObj);
int cbfsconnect_cbfs_setusehardlinks(void* lpObj, int bUseHardLinks);

bool GetUseHardLinks();
int SetUseHardLinks(bool bUseHardLinks);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports hard links to files.

If this property is enabled, the application must properly handle the CreateHardLink, EnumerateHardLinks, and CloseHardLinksEnumeration events for hard links to function correctly. The GetFileNameByFileId event must be handled as well, and the GetFileInfo must always be sure to return the number of hard links a file has by setting the HardLinkCount event parameter appropriately.

Note: Hard links are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting hard links is recommended.

Please refer to the Hard Links topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseObjectIds Property (CBFS Class)

This property specifies whether the virtual filesystem supports a volume object Id.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseObjectIds();
int SetUseObjectIds(int bUseObjectIds);

Unicode (Windows)
BOOL GetUseObjectIds();
INT SetUseObjectIds(BOOL bUseObjectIds);

int cbfsconnect_cbfs_getuseobjectids(void* lpObj);
int cbfsconnect_cbfs_setuseobjectids(void* lpObj, int bUseObjectIds);

bool GetUseObjectIds();
int SetUseObjectIds(bool bUseObjectIds);

Default Value

TRUE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports a volume object Id.

If this property is true, the application must properly handle the GetVolumeObjectId and SetVolumeObjectId events. Set this property to false to tell the OS that the volume object Id is not supported.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseReparsePoints Property (CBFS Class)

This property specifies whether the virtual filesystem supports reparse points.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseReparsePoints();
int SetUseReparsePoints(int bUseReparsePoints);

Unicode (Windows)
BOOL GetUseReparsePoints();
INT SetUseReparsePoints(BOOL bUseReparsePoints);

int cbfsconnect_cbfs_getusereparsepoints(void* lpObj);
int cbfsconnect_cbfs_setusereparsepoints(void* lpObj, int bUseReparsePoints);

bool GetUseReparsePoints();
int SetUseReparsePoints(bool bUseReparsePoints);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports reparse points.

If this property is enabled, the application must properly handle the SetReparsePoint, GetReparsePoint, and DeleteReparsePoint events for reparse points to function correctly.

Note: Reparse points are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting reparse points is recommended. Reparse point support is also expected by the NFS sharing components of the OS.

Please refer to the Reparse Points topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseShortFileNames Property (CBFS Class)

This property specifies whether the virtual filesystem supports short (8.3) filenames.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseShortFileNames();
int SetUseShortFileNames(int bUseShortFileNames);

Unicode (Windows)
BOOL GetUseShortFileNames();
INT SetUseShortFileNames(BOOL bUseShortFileNames);

int cbfsconnect_cbfs_getuseshortfilenames(void* lpObj);
int cbfsconnect_cbfs_setuseshortfilenames(void* lpObj, int bUseShortFileNames);

bool GetUseShortFileNames();
int SetUseShortFileNames(bool bUseShortFileNames);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports short filenames (also known as 8.3 filenames). Short filename support may be necessary for some older third-party applications to be able to access the virtual filesystem's files.

If this property is enabled, the application must be sure to return short filenames when handling the EnumerateDirectory and GetFileInfo events; and must be able to handle any event firing with a short filename rather than a normal one.

Please refer to the Short File Names topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

UseWindowsSecurity Property (CBFS Class)

This property specifies whether the virtual filesystem supports Windows' ACL-based security mechanisms.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseWindowsSecurity();
int SetUseWindowsSecurity(int bUseWindowsSecurity);

Unicode (Windows)
BOOL GetUseWindowsSecurity();
INT SetUseWindowsSecurity(BOOL bUseWindowsSecurity);

int cbfsconnect_cbfs_getusewindowssecurity(void* lpObj);
int cbfsconnect_cbfs_setusewindowssecurity(void* lpObj, int bUseWindowsSecurity);

bool GetUseWindowsSecurity();
int SetUseWindowsSecurity(bool bUseWindowsSecurity);

Default Value

FALSE

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports Windows' standard security mechanisms, which are based on ACLs (access control lists).

If this property is enabled, the application must properly handle the GetFileSecurity and SetFileSecurity events for Windows' security mechanisms to function properly.

Note: Windows' security attributes are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting Windows' security attributes is recommended.

Please refer to the Security Checks topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

AddDeniedProcess Method (CBFS Class)

Adds a rule that prevents a process from accessing the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddDeniedProcess(const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess);

Unicode (Windows)
INT AddDeniedProcess(LPCWSTR lpszProcessFileName, INT iProcessId, BOOL bChildProcesses, INT iDesiredAccess);

int cbfsconnect_cbfs_adddeniedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess);

int AddDeniedProcess(const QString& qsProcessFileName, int iProcessId, bool bChildProcesses, int iDesiredAccess);

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to add an access rule that denies the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full filename of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to deny; valid values are:

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveDeniedProcess method.

Note: This method can be called only when Active is true, and it cannot be called within events.

The methods and properties related to process access lists 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 process access information occurs in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AddGrantedProcess Method (CBFS Class)

Adds a rule that allows a process to access the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddGrantedProcess(const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess);

Unicode (Windows)
INT AddGrantedProcess(LPCWSTR lpszProcessFileName, INT iProcessId, BOOL bChildProcesses, INT iDesiredAccess);

int cbfsconnect_cbfs_addgrantedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess);

int AddGrantedProcess(const QString& qsProcessFileName, int iProcessId, bool bChildProcesses, int iDesiredAccess);

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to add an access rule that grants the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full filename of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to grant; valid values are:

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveGrantedProcess method.

Note: This method can be called only when Active is true, and it cannot be called within events.

The methods and properties related to process access lists 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 process access information occurs in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AddMountingPoint Method (CBFS Class)

Adds a mounting point for the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddMountingPoint(const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId);

Unicode (Windows)
INT AddMountingPoint(LPCWSTR lpszMountingPoint, INT iFlags, LONG64 lAuthenticationId);

int cbfsconnect_cbfs_addmountingpoint(void* lpObj, const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId);

int AddMountingPoint(const QString& qsMountingPoint, int iFlags, qint64 lAuthenticationId);

Remarks

This method adds a new mounting point for the virtual drive (which must have already been created using CreateStorage). Virtual drives 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 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.

To create a virtual drive in a container from the host, set the container's Id via the DockerContainerId configuration setting prior to calling AddMountingPoint. Note: not all mounting point types are supported when a mounting point is created in a container. Please refer to the Docker Containers 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

In the FUSE class, a mount point is specified as a parameter of the Mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS class.

When applications call the CreateStorage method, a virtual drive is created. Virtual drives 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 drive, applications should call MountMedia to "insert" virtual storage media into the virtual drive. This call will cause the class'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 drive, applications should use the AddMountingPoint method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CloseOpenedFilesSnapshot Method (CBFS Class)

Closes the previously-created opened files snapshot.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CloseOpenedFilesSnapshot();

Unicode (Windows)
INT CloseOpenedFilesSnapshot();

int cbfsconnect_cbfs_closeopenedfilessnapshot(void* lpObj);

int CloseOpenedFilesSnapshot();

Remarks

This method closes the opened files snapshot previously created by CreateOpenedFilesSnapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

The methods and properties related to open files snapshots 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 creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (CBFS Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cbfsconnect_cbfs_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

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

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

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateOpenedFilesSnapshot Method (CBFS Class)

Creates a snapshot of information about files that are currently open.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateOpenedFilesSnapshot();

Unicode (Windows)
INT CreateOpenedFilesSnapshot();

int cbfsconnect_cbfs_createopenedfilessnapshot(void* lpObj);

int CreateOpenedFilesSnapshot();

Remarks

This method creates a snapshot of information about all files and directories in the virtual filesystem that are currently open. This information is then used to populate the OpenFile* properties, as well as the OpenHandlesCount and OpenObjectsCount properties.

Note that there will always be at least one item in the OpenFile* properties since the virtual volume itself is always inherently open.

When the application is finished working with the opened files snapshot, it must close it by calling the CloseOpenedFilesSnapshot method in order to release the associated memory. If this method is called again before an existing snapshot is closed, the class will attempt to close it before creating a new one.

Note: This method can be called only when Active is true, and it cannot be called within events.

The methods and properties related to open files snapshots 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 creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CreateStorage Method (CBFS Class)

This method creates the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateStorage();

Unicode (Windows)
INT CreateStorage();

int cbfsconnect_cbfs_createstorage(void* lpObj);

int CreateStorage();

Remarks

This method creates the virtual drive (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: Many other properties, although not directly used by this method, nonetheless cannot be changed once a virtual drive is created. Such restrictions are noted where applicable.

After the virtual drive 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 class instance in the application before calling this method.

Note: This method cannot be called within events.

Virtual Drives, Media, and Mounting Points

In the FUSE class, a mount point is specified as a parameter of the Mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS class.

When applications call the CreateStorage method, a virtual drive is created. Virtual drives 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 drive, applications should call MountMedia to "insert" virtual storage media into the virtual drive. This call will cause the class'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 drive, applications should use the AddMountingPoint method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteStorage Method (CBFS Class)

This method deletes the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteStorage(int bForceUnmount);

Unicode (Windows)
INT DeleteStorage(BOOL bForceUnmount);

int cbfsconnect_cbfs_deletestorage(void* lpObj, int bForceUnmount);

int DeleteStorage(bool bForceUnmount);

Remarks

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

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 fails with an error.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DisableRouteCache Method (CBFS Class)

This method disables the automatic routing of requests to local files.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DisableRouteCache(int bInvalidateRoutedFiles);

Unicode (Windows)
INT DisableRouteCache(BOOL bInvalidateRoutedFiles);

int cbfsconnect_cbfs_disableroutecache(void* lpObj, int bInvalidateRoutedFiles);

int DisableRouteCache(bool bInvalidateRoutedFiles);

Remarks

This method disables the automatic routing of requests to files in the directory specified by a previous call to EnableRouteCache. Please refer to that method for more information about said request routing.

The InvalidateRoutedFiles parameter controls what happens to any handles currently open for files in the aforementioned directory: passing true will allow them to continue being used, whereas passing false will invalidate them immediately.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DispatchEvents Method (CBFS Class)

Reserved, do not use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DispatchEvents();

Unicode (Windows)
INT DispatchEvents();

int cbfsconnect_cbfs_dispatchevents(void* lpObj);

int DispatchEvents();

Remarks

Reserved, do not use.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

EnableRouteCache Method (CBFS Class)

This method enables the automatic routing of requests to local files.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int EnableRouteCache(const char* lpszLocation, int iFlags);

Unicode (Windows)
INT EnableRouteCache(LPCWSTR lpszLocation, INT iFlags);

int cbfsconnect_cbfs_enableroutecache(void* lpObj, const char* lpszLocation, int iFlags);

int EnableRouteCache(const QString& qsLocation, int iFlags);

Remarks

This method enables the automatic routing of requests to files that exist in the directory specified by Location. The Flags parameter is used to specify which kinds of requests should not be routed automatically (see below).

When automatic request routing is enabled, and a file in the virtual drive is opened, the class will immediately check the cache directory to see if a file with the same path and name exists. If such a file is found, all operations will be performed on it directly and the corresponding events will not fire (except for the operations excluded from routing by the specified Flags).

When attempting to find a matching file, the class assumes that the contents of the specified cache directory mirror that of the virtual drive. That is, the cache directory corresponds to the root of the virtual drive, and the files and directory structure are the same in each. If the class fails to find a matching file (or if the operation in question is excluded from routing), then the applicable events fire as usual.

The Flags value should be created by ORing together zero or more of the following flags:

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

FileMatchesMask Method (CBFS Class)

This method checks whether a particular file or directory name matches the specified mask.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int FileMatchesMask(const char* lpszMask, const char* lpszFileName, int bCaseSensitive);

Unicode (Windows)
INT FileMatchesMask(LPCWSTR lpszMask, LPCWSTR lpszFileName, BOOL bCaseSensitive);

int cbfsconnect_cbfs_filematchesmask(void* lpObj, const char* lpszMask, const char* lpszFileName, int bCaseSensitive);

bool FileMatchesMask(const QString& qsMask, const QString& qsFileName, bool bCaseSensitive);

Remarks

This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns true. The CaseSensitive parameter controls whether a case-sensitive match should be performed.

Note: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.

Note: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverStatus Method (CBFS Class)

Retrieves the status of the system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDriverStatus(const char* lpszProductGUID, int iModule);

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID, INT iModule);

int cbfsconnect_cbfs_getdriverstatus(void* lpObj, const char* lpszProductGUID, int iModule);

int GetDriverStatus(const QString& qsProductGUID, int iModule);

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

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetEventFilename Method (CBFS Class)

This method retrieves the name of the file or directory, to which the event applies.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetEventFilename();

Unicode (Windows)
LPWSTR GetEventFilename();

char* cbfsconnect_cbfs_geteventfilename(void* lpObj);

QString GetEventFilename();

Remarks

This method can be called within event handlers of events, related to the file or directory operations, to retrieve the name of the file or directory, to which the operation applies. If the query fails or an event does not have an associated filename, this method returns an empty string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorProcessId Method (CBFS Class)

This method retrieves the Id of the process (PID) that opened the specified file handle.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetHandleCreatorProcessId(int64 lHandleInfo);

Unicode (Windows)
INT GetHandleCreatorProcessId(LONG64 lHandleInfo);

int cbfsconnect_cbfs_gethandlecreatorprocessid(void* lpObj, int64 lHandleInfo);

int GetHandleCreatorProcessId(qint64 lHandleInfo);

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns 0.

Note: PIDs are not unique and may be reused by different processes over time (although in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorProcessName Method (CBFS Class)

This method retrieves the name of the process that opened the specified file handle.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetHandleCreatorProcessName(int64 lHandleInfo);

Unicode (Windows)
LPWSTR GetHandleCreatorProcessName(LONG64 lHandleInfo);

char* cbfsconnect_cbfs_gethandlecreatorprocessname(void* lpObj, int64 lHandleInfo);

QString GetHandleCreatorProcessName(qint64 lHandleInfo);

Remarks

This method can be called within certain events to retrieve the name of the process that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns an empty string.

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorThreadId Method (CBFS Class)

This method retrieves the Id of the thread that opened the specified file handle.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetHandleCreatorThreadId(int64 lHandleInfo);

Unicode (Windows)
INT GetHandleCreatorThreadId(LONG64 lHandleInfo);

int cbfsconnect_cbfs_gethandlecreatorthreadid(void* lpObj, int64 lHandleInfo);

int GetHandleCreatorThreadId(qint64 lHandleInfo);

Remarks

This method can be called within certain events to retrieve the Id of the thread that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns 0.

Notes: Thread Ids are not unique and may be reused by different threads over time.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetHandleCreatorToken Method (CBFS Class)

This method retrieves the security token associated with the process that opened the specified file handle.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetHandleCreatorToken(int64 lHandleInfo);

Unicode (Windows)
LONG64 GetHandleCreatorToken(LONG64 lHandleInfo);

int64 cbfsconnect_cbfs_gethandlecreatortoken(void* lpObj, int64 lHandleInfo);

qint64 GetHandleCreatorToken(qint64 lHandleInfo);

Remarks

This method can be called within certain events to retrieve the security token associated with the process that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

Note: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

For virtual drives shared on the network, applications may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

• Authenticated mode, in which case the Helper DLL (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
• Guest mode, in which case the retrievable information is for the system's GUEST account.
• Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetModuleVersion Method (CBFS Class)

Retrieves the version of a given product module.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetModuleVersion(const char* lpszProductGUID, int iModule);

Unicode (Windows)
LONG64 GetModuleVersion(LPCWSTR lpszProductGUID, INT iModule);

int64 cbfsconnect_cbfs_getmoduleversion(void* lpObj, const char* lpszProductGUID, int iModule);

qint64 GetModuleVersion(const QString& qsProductGUID, int iModule);

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

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorProcessId Method (CBFS Class)

Retrieves the Id of the process (PID) that initiated the operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOriginatorProcessId();

Unicode (Windows)
INT GetOriginatorProcessId();

int cbfsconnect_cbfs_getoriginatorprocessid(void* lpObj);

int GetOriginatorProcessId();

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that initiated the operation. If the query fails, this method returns 0.

Please note that PIDs are not unique, and may be reused by different processes over time (though in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorProcessName Method (CBFS Class)

Retrieves the name of the process that initiated the operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOriginatorProcessName();

Unicode (Windows)
LPWSTR GetOriginatorProcessName();

char* cbfsconnect_cbfs_getoriginatorprocessname(void* lpObj);

QString GetOriginatorProcessName();

Remarks

This method can be called within certain events to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorThreadId Method (CBFS Class)

Retrieves the Id of the thread that initiated the operation (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOriginatorThreadId();

Unicode (Windows)
INT GetOriginatorThreadId();

int cbfsconnect_cbfs_getoriginatorthreadid(void* lpObj);

int GetOriginatorThreadId();

Remarks

This method can be called within certain events to retrieve the Id of the thread that initiated the operation. If the query fails, this method returns 0.

Please note that thread Ids are not unique, and may be reused by different threads over time.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorToken Method (CBFS Class)

Retrieves the security token associated with the process that initiated the operation (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetOriginatorToken();

Unicode (Windows)
LONG64 GetOriginatorToken();

int64 cbfsconnect_cbfs_getoriginatortoken(void* lpObj);

qint64 GetOriginatorToken();

Remarks

This method can be called within certain events to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

Important: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

For virtual drives shared on the network, applications may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

• Authenticated mode, in which case the Helper DLL (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
• Guest mode, in which case the retrievable information is for the system's GUEST account.
• Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Initialize Method (CBFS Class)

This method initializes the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Initialize(const char* lpszProductGUID);

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);

int cbfsconnect_cbfs_initialize(void* lpObj, const char* lpszProductGUID);

int Initialize(const QString& qsProductGUID);

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Install Method (CBFS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Install(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iModulesToInstall, int iFlags);

Unicode (Windows)
INT Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszPathToInstall, INT iModulesToInstall, INT iFlags);

int cbfsconnect_cbfs_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iModulesToInstall, int iFlags);

int Install(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsPathToInstall, int iModulesToInstall, int iFlags);

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

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

IsCBFSVolume Method (CBFS Class)

This method checks whether the specified volume is powered by CBFS.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int IsCBFSVolume(const char* lpszVolumePath);

Unicode (Windows)
INT IsCBFSVolume(LPCWSTR lpszVolumePath);

int cbfsconnect_cbfs_iscbfsvolume(void* lpObj, const char* lpszVolumePath);

bool IsCBFSVolume(const QString& qsVolumePath);

Remarks

This method checks to see whether the volume specified by VolumePath is powered by CBFS; if it is, this method returns true.

Valid formats for VolumePath include the following:

• Drive letters, like X:.
• Volume GUIDs, like Volume{676D0357-A23A-49C3-B433-65AAD72DD282}.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

IsIconRegistered Method (CBFS Class)

Checks whether the specified icon is registered (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int IsIconRegistered(const char* lpszIconId);

Unicode (Windows)
INT IsIconRegistered(LPCWSTR lpszIconId);

int cbfsconnect_cbfs_isiconregistered(void* lpObj, const char* lpszIconId);

bool IsIconRegistered(const QString& qsIconId);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

MountMedia Method (CBFS Class)

This method mounts media in the virtual drive, making it accessible for reading and writing.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int MountMedia(int iTimeout);

Unicode (Windows)
INT MountMedia(INT iTimeout);

int cbfsconnect_cbfs_mountmedia(void* lpObj, int iTimeout);

int MountMedia(int iTimeout);

Remarks

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

Timeout specifies how many milliseconds the driver will wait for events to execute before canceling 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 nonzero 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: A number of properties 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 fails with 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 drive, and it cannot be called within events.

Virtual Drives, Media, and Mounting Points

In the FUSE class, a mount point is specified as a parameter of the Mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS class.

When applications call the CreateStorage method, a virtual drive is created. Virtual drives 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 drive, applications should call MountMedia to "insert" virtual storage media into the virtual drive. This call will cause the class'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 drive, applications should use the AddMountingPoint method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

NotifyDirectoryChange Method (CBFS Class)

This method notifies the OS that a file or directory has changed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int NotifyDirectoryChange(const char* lpszFileName, int iAction, const char* lpszNewFileName, int bWait);

Unicode (Windows)
INT NotifyDirectoryChange(LPCWSTR lpszFileName, INT iAction, LPCWSTR lpszNewFileName, BOOL bWait);

int cbfsconnect_cbfs_notifydirectorychange(void* lpObj, const char* lpszFileName, int iAction, const char* lpszNewFileName, int bWait);

bool NotifyDirectoryChange(const QString& qsFileName, int iAction, const QString& qsNewFileName, bool bWait);

Remarks

If a file or directory is modified by some means external to the virtual filesystem, this method should be called to notify the OS. Doing so prompts the OS to make any requests necessary to obtain the most up-to-date information, which in turn fires the relevant class events. This method returns either true or false to indicate whether it executed successfully.

Applications must be careful to call this method only when some changes have occurred that the OS has no possibility of detecting on its own. Said another way, applications should not call this method to notify the OS of changes made by invoking filesystem APIs on files or directories in the virtual filesystem; such changes are inherently visible to OS.

For further clarity, the following examples describe scenarios in which NotifyDirectoryChange should and should not be called:

• DO call NotifyDirectoryChange if, for example, the application is in charge of mapping the contents of some database to its virtual filesystem, and an external process changes the database's contents directly. The OS only knows about the filesystem, it does not know or care about the database contents; thus, the application must notify it that "something has changed".
• DO NOT call NotifyDirectoryChange if, for example, the application has created a virtual drive Z:, and either it or some other process makes a filesystem call against the virtual drive's contents; for example, DeleteFile("Z:\SomeFile.txt"). The OS detects such a change automatically because it was made through the filesystem APIs.

FileName specifies the path to the file or directory (in the virtual drive) that has changed. This path must not include a mounting point name.

Several files or directories may be referenced in this parameter at once. To specify the exact names, join the paths with CRLF (characters with codes #13 and #10) and pass the final string to FileName. The paths may reference files and directories in different parent directories.

An application also may specify the path with a mask. When passing a mask, only the filename portion of the mask may contain wildcard characters (* and ?). Such mask will denote multiple entries in a single directory. The class will fire the EnumerateDirectory event with the specified mask to collect the names of files and subdirectories, next they will be reported as changed.

Note: When the EnumerateDirectory event is fired, its HandleInfo, DirectoryContext, and HandleContext parameters will be empty because no system-initiated enumeration takes place and the directory is not opened.

Action specifies the type of change so that the OS knows what kind of information it needs to request. Possible values are as follows:

NewFileName specifies the new path/name of the file or directory (in the virtual drive) if the rename operation was performed. In other cases, the value is ignored.

Wait specifies whether this method should wait until the OS has finished making all of the requests necessary to handle the notification sent by this method. Passing true will cause this method to block until all requests are complete. Passing false will cause it to send the notification to the OS and return immediately, letting the OS make the necessary requests in the background. In the latter case, this method returns false.

Note: This method can be called only when Active is true. It may be called both within and outside of events; when called within an event, the Wait parameter is ignored and is assumed to be set to false.

If this method encounters any issues during its execution, it fails with an error.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

RegisterIcon Method (CBFS Class)

Registers an icon that can be displayed as an overlay on the virtual drive in Windows Explorer (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RegisterIcon(const char* lpszIconPath, const char* lpszProductGUID, const char* lpszIconId);

Unicode (Windows)
INT RegisterIcon(LPCWSTR lpszIconPath, LPCWSTR lpszProductGUID, LPCWSTR lpszIconId);

int cbfsconnect_cbfs_registericon(void* lpObj, const char* lpszIconPath, const char* lpszProductGUID, const char* lpszIconId);

bool RegisterIcon(const QString& qsIconPath, const QString& qsProductGUID, const QString& qsIconId);

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 drive 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 class 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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ReleaseUnusedFiles Method (CBFS Class)

This method instructs the OS to release any files kept open by the cache manager.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ReleaseUnusedFiles();

Unicode (Windows)
INT ReleaseUnusedFiles();

int cbfsconnect_cbfs_releaseunusedfiles(void* lpObj);

bool ReleaseUnusedFiles();

Remarks

This method instructs the OS to release any files that the system cache manager has kept open, and returns either true or false to indicate whether the files were released successfully. Having the OS release open files can be useful in situations in which operations need to be performed while the filesystem is not in use.

Note: The OS may open additional files during the execution of this method. To guard against this, it is recommended that application use a critical section (or other synchronization object) when calling this method, and use the same one in the OpenFile event handler. Such an approach ensures that the cache manager has no files open after calling this method.

Note: This method can be called only when Active is true. It may be called both within and outside of events; when called within an event, it is executed asynchronously on another thread (causing the call to return immediately, and an ERROR_IO_PENDING result code to be reported to the OS).

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

RemoveDeniedProcess Method (CBFS Class)

Removes a rule that prevents a process from accessing the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveDeniedProcess(const char* lpszProcessFileName, int iProcessId);

Unicode (Windows)
INT RemoveDeniedProcess(LPCWSTR lpszProcessFileName, INT iProcessId);

int cbfsconnect_cbfs_removedeniedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId);

int RemoveDeniedProcess(const QString& qsProcessFileName, int iProcessId);

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to remove an access rule previously added with the AddDeniedProcess method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddDeniedProcess was called previously. Please refer to that method's documentation for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

The methods and properties related to process access lists 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 process access information occurs in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

RemoveGrantedProcess Method (CBFS Class)

Removes a rule that allows a process to access the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveGrantedProcess(const char* lpszProcessFileName, int iProcessId);

Unicode (Windows)
INT RemoveGrantedProcess(LPCWSTR lpszProcessFileName, INT iProcessId);

int cbfsconnect_cbfs_removegrantedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId);

int RemoveGrantedProcess(const QString& qsProcessFileName, int iProcessId);

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to remove an access rule previously added with the AddGrantedProcess method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddGrantedProcess was called previously. Please refer to that method's documentation for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

The methods and properties related to process access lists 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 process access information occurs in a thread-safe manner.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

RemoveMountingPoint Method (CBFS Class)

Removes a mounting point for the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveMountingPoint(int iIndex, const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId);

Unicode (Windows)
INT RemoveMountingPoint(INT iIndex, LPCWSTR lpszMountingPoint, INT iFlags, LONG64 lAuthenticationId);

int cbfsconnect_cbfs_removemountingpoint(void* lpObj, int iIndex, const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId);

int RemoveMountingPoint(int iIndex, const QString& qsMountingPoint, int iFlags, qint64 lAuthenticationId);

Remarks

This method removes a previously-created mounting point for the virtual drive.

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.

To remove a virtual drive, created in a container from the host, set the container's Id via the DockerContainerId configuration setting prior to calling RemoveMountingPoint.

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ResetIcon Method (CBFS Class)

Resets the virtual drive's icon back to default by deselecting the active overlay icon (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResetIcon();

Unicode (Windows)
INT ResetIcon();

int cbfsconnect_cbfs_reseticon(void* lpObj);

int ResetIcon();

Remarks

This method deselects the overlay icon currently in use, thus resetting the virtual drive'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 drive, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ResetTimeout Method (CBFS Class)

This method resets the timeout duration for the current event handler.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResetTimeout(int iTimeout);

Unicode (Windows)
INT ResetTimeout(INT iTimeout);

int cbfsconnect_cbfs_resettimeout(void* lpObj, int iTimeout);

bool ResetTimeout(int iTimeout);

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the class that request processing is taking longer than expected.

If called successfully, this method returns true, and the current event handler's timeout timer is immediately reset to 0; when it reaches the number of milliseconds specified by Timeout, the driver will cancel the underlying OS request. Please refer to the Timeouts topic for more information.

Passing 0 for Timeout disables the timeout timer for the current event handler, allowing it to take as long as it needs to complete.

Note: When several events are fired for the same file concurrently (if the SerializeAccess property is set to false), and ResetTimeout is called from one of the handlers of these events, this method will reset the timer for all currently executed event handlers.

Note: This method can be called only within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

RouteToFile Method (CBFS Class)

This method instructs the class to route future requests directly to a given file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RouteToFile(int64 lFileInfo, const char* lpszFileName, int iFlags);

Unicode (Windows)
INT RouteToFile(LONG64 lFileInfo, LPCWSTR lpszFileName, INT iFlags);

int cbfsconnect_cbfs_routetofile(void* lpObj, int64 lFileInfo, const char* lpszFileName, int iFlags);

bool RouteToFile(qint64 lFileInfo, const QString& qsFileName, int iFlags);

Remarks

This method can be called from within the CreateFile or OpenFile event to instruct the class to route any future requests against the file specified by FileInfo directly to the file at the path specified by FileName instead of firing the corresponding events. The Flags parameter is used to specify which kinds of requests should not be routed automatically (see below).

Pass the value obtained from the CreateFile or OpenFile event's FileInfo parameter for this method's FileInfo parameter.

This method returns either true or false to indicate whether routing was set up successfully. If, after this method is called successfully, the application later wishes for routing to cease, it may do one of the following:

• Call the NotifyDirectoryChange method, passing CBFS_NOTIFY_FLAG_METADATA_MODIFIED for its Action parameter, and the same FileName value as received in the original CreateFile or OpenFile event.
• Disable the metadata cache entirely using the MetadataCacheEnabled property.

The Flags value should be created by ORing together zero or more of the following flags:

Note: This method can be called only within the CreateFile and OpenFile event handlers.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

SetIcon Method (CBFS Class)

Selects a registered overlay icon for display on the virtual drive in Windows Explorer (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetIcon(const char* lpszIconId);

Unicode (Windows)
INT SetIcon(LPCWSTR lpszIconId);

int cbfsconnect_cbfs_seticon(void* lpObj, const char* lpszIconId);

int SetIcon(const QString& qsIconId);

Remarks

This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual drive 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 drive'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 drive, and it cannot be called within events. Also, note that the effects of this method only last until the virtual drive is destroyed; applications that always want to have some overlay icon displayed must call this method each time the virtual drive is created.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ShutdownSystem Method (CBFS Class)

Shuts down or reboots the operating system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ShutdownSystem(const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

Unicode (Windows)
INT ShutdownSystem(LPCWSTR lpszShutdownPrompt, INT iTimeout, BOOL bForceCloseApps, BOOL bReboot);

int cbfsconnect_cbfs_shutdownsystem(void* lpObj, const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

bool ShutdownSystem(const QString& qsShutdownPrompt, int iTimeout, bool bForceCloseApps, bool bReboot);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Uninstall Method (CBFS Class)

Uninstalls the product's system drivers and/or helper DLL (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Uninstall(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

Unicode (Windows)
INT Uninstall(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszInstalledPath, INT iFlags);

int cbfsconnect_cbfs_uninstall(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

int Uninstall(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsInstalledPath, int iFlags);

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

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

UnmountMedia Method (CBFS Class)

This method unmounts media from the virtual drive.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UnmountMedia(int bForceUnmount);

Unicode (Windows)
INT UnmountMedia(BOOL bForceUnmount);

int cbfsconnect_cbfs_unmountmedia(void* lpObj, int bForceUnmount);

int UnmountMedia(bool bForceUnmount);

Remarks

This method unmounts the virtual storage media from the virtual drive. The virtual drive, 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 fails with an error.

This method must not be called for plug-and-play virtual drives with nonremovable 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 drive, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UnregisterIcon Method (CBFS Class)

Unregisters an existing overlay icon (Windows only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UnregisterIcon(const char* lpszProductGUID, const char* lpszIconId);

Unicode (Windows)
INT UnregisterIcon(LPCWSTR lpszProductGUID, LPCWSTR lpszIconId);

int cbfsconnect_cbfs_unregistericon(void* lpObj, const char* lpszProductGUID, const char* lpszIconId);

bool UnregisterIcon(const QString& qsProductGUID, const QString& qsIconId);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CanFileBeDeleted Event (CBFS Class)

This event fires when the driver needs to know whether a file or directory can be deleted.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCanFileBeDeleted(CBFSCanFileBeDeletedEventParams *e);

typedef struct {
  const char *FileName;
  int64 HandleInfo;
  void *FileContext;
  void *HandleContext;
  int CanBeDeleted;
  int ResultCode;
  int reserved;
} CBFSCanFileBeDeletedEventParams;


Unicode (Windows)
virtual INT FireCanFileBeDeleted(CBFSCanFileBeDeletedEventParams *e);

typedef struct {
  LPCWSTR FileName;
  LONG64 HandleInfo;
  LPVOID FileContext;
  LPVOID HandleContext;
  BOOL CanBeDeleted;
  INT ResultCode;
  INT reserved;
} CBFSCanFileBeDeletedEventParams;

#define EID_CBFS_CANFILEBEDELETED 1

virtual INT CBFSCONNECT_CALL FireCanFileBeDeleted(LPWSTR &lpszFileName, LONG64 &lHandleInfo, LPVOID &lpFileContext, LPVOID &lpHandleContext, BOOL &bCanBeDeleted, INT &iResultCode);

class CBFSCanFileBeDeletedEventParams {
public:
  const QString &FileName();

  qint64 HandleInfo();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  bool CanBeDeleted();
  void SetCanBeDeleted(bool bCanBeDeleted);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CanFileBeDeleted(CBFSCanFileBeDeletedEventParams *e);

// Or, subclass CBFS and override this emitter function.
virtual int FireCanFileBeDeleted(CBFSCanFileBeDeletedEventParams *e) {...}

Remarks

This event fires when the driver needs to know whether the file or directory specified by FileName can be deleted.

To handle this event properly, applications must set the CanBeDeleted parameter appropriately.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Note: The firing of this event does not necessarily mean the specified file or directory will be deleted if CanBeDeleted is set to true. It means only that the OS needs to know whether or not it can be deleted.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

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.

CleanupFile Event (CBFS Class)

This event fires when the OS needs to clean up a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCleanupFile(CBFSCleanupFileEventParams *e);

typedef struct {
  const char *FileName;
  int64 HandleInfo;
  void *FileContext;
  void *HandleContext;
  int ResultCode;
  int reserved;
} CBFSCleanupFileEventParams;


Unicode (Windows)
virtual INT FireCleanupFile(CBFSCleanupFileEventParams *e);

typedef struct {
  LPCWSTR FileName;
  LONG64 HandleInfo;
  LPVOID FileContext;
  LPVOID HandleContext;
  INT ResultCode;
  INT reserved;
} CBFSCleanupFileEventParams;

#define EID_CBFS_CLEANUPFILE 2

virtual INT CBFSCONNECT_CALL FireCleanupFile(LPWSTR &lpszFileName, LONG64 &lHandleInfo, LPVOID &lpFileContext, LPVOID &lpHandleContext, INT &iResultCode);

class CBFSCleanupFileEventParams {
public:
  const QString &FileName();

  qint64 HandleInfo();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CleanupFile(CBFSCleanupFileEventParams *e);

// Or, subclass CBFS and override this emitter function.
virtual int FireCleanupFile(CBFSCleanupFileEventParams *e) {...}

Remarks

This event fires when the OS needs to close a handle to the currently open file specified by FileName. This event differs from CloseFile in that CleanupFile fires immediately when an open handle to the specified file is closed by a process, whereas CloseFile may be fired much later when the OS itself decides that the file can be formally closed. Similar to CloseFile, however, this event will fire only for the last handle to a file if the FireAllOpenCloseEvents property is disabled.

Other events may fire for the file handle in the time between when this event fires and when the CloseFile event fires. For example, system components such as the memory manager or cache manager may cause the ReadFile and WriteFile events to fire.

This event is optional; it is provided to give applications a chance to, for example, free up resources associated with a file before it's formally closed.

When the FireAllOpenCloseEvents is set to false, this event is fired each time the file is closed by the application. When the file is opened and closed by some process multiple times consequently, the event handler can end up being called multiple times seemingly without a match with the OpenFile and CloseFile . However, such behavior is correct. The exact order of Open/Cleanup/Close events cannot be guaranteed because of the way Windows closes files.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

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.

CloseDirectoryEnumeration Event (CBFS Class)

This event fires when the OS is finished enumerating a directory's contents.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCloseDirectoryEnumeration(CBFSCloseDirectoryEnumerationEventParams *e);

typedef struct {
  const char *DirectoryName;
  void *DirectoryContext;
  void *EnumerationContext;
  int ResultCode;
  int reserved;
} CBFSCloseDirectoryEnumerationEventParams;


Unicode (Windows)
virtual INT FireCloseDirectoryEnumeration(CBFSCloseDirectoryEnumerationEventParams *e);

typedef struct {
  LPCWSTR DirectoryName;
  LPVOID DirectoryContext;
  LPVOID EnumerationContext;
  INT ResultCode;
  INT reserved;
} CBFSCloseDirectoryEnumerationEventParams;

#define EID_CBFS_CLOSEDIRECTORYENUMERATION 3

virtual INT CBFSCONNECT_CALL FireCloseDirectoryEnumeration(LPWSTR &lpszDirectoryName, LPVOID &lpDirectoryContext, LPVOID &lpEnumerationContext, INT &iResultCode);

class CBFSCloseDirectoryEnumerationEventParams {
public:
  const QString &DirectoryName();

  void *DirectoryContext();
  void SetDirectoryContext(void *lpDirectoryContext);

  void *EnumerationContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CloseDirectoryEnumeration(CBFSCloseDirectoryEnumerationEventParams *e);

// Or, subclass CBFS and override this emitter function.
virtual int FireCloseDirectoryEnumeration(CBFSCloseDirectoryEnumerationEventParams *e) {...}

Remarks

This event fires when the OS is finished enumerating the contents of the directory specified by DirectoryName.

To handle this event properly, applications must release any resources that were allocated for/by the directory enumeration in earlier EnumerateDirectory events.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The DirectoryContext and EnumerationContext parameters are placeholders for application-defined data associated with the directory and enumeration, respectively. Please refer to the Contexts topic for more information about them.

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.

CloseFile Event (CBFS Class)

This event fires when the OS needs to close a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCloseFile(CBFSCloseFileEventParams *e);

typedef struct {
  const char *FileName;
  int PendingDeletion;
  int64 HandleInfo;
  void *FileContext;
  void *HandleContext;
  int ResultCode;
  int reserved;
} CBFSCloseFileEventParams;


Unicode (Windows)
virtual INT FireCloseFile(CBFSCloseFileEventParams *e);

typedef struct {
  LPCWSTR FileName;
  BOOL PendingDeletion;
  LONG64 HandleInfo;
  LPVOID FileContext;
  LPVOID HandleContext;
  INT ResultCode;
  INT reserved;
} CBFSCloseFileEventParams;

#define EID_CBFS_CLOSEFILE 4

virtual INT CBFSCONNECT_CALL FireCloseFile(LPWSTR &lpszFileName, BOOL &bPendingDeletion, LONG64 &lHandleInfo, LPVOID &lpFileContext, LPVOID &lpHandleContext, INT &iResultCode);

class CBFSCloseFileEventParams {
public:
  const QString &FileName();

  bool PendingDeletion();

  qint64 HandleInfo();

  void *FileContext();
  void SetFileContext(void *lpFileContext);

  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CloseFile(CBFSCloseFileEventParams *e);

// Or, subclass CBFS and override this emitter function.
virtual int FireCloseFile(CBFSCloseFileEventParams *e) {...}

Remarks

This event fires when the OS needs to close the file specified by FileName. If the FireAllOpenCloseEvents property is disabled, this event will fire only after the last handle to the specified file is closed.

To handle this event properly, applications can (if necessary/applicable) check to see if any other handles are open for the file, and if not, close whatever backend resources are currently open for it.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The PendingDeletion parameter indicates whether the file should be deleted; if it's true, the DeleteFile event will fire immediately after this event. The application may delete the file from either event handler.

If an application uses some object to store user context, uses FileContext to store the reference to this object, and deletes an object referenced in FileContext, the pointer stored in FileContext becomes invalid. In this scenario, if the PendingDeletion parameter is true, the DeleteFile event will fire with the invalid value in its FileContext parameter. The solution to this issue is to inspect the value of the DeleteFile parameter and if it is true, postpone deletion of the object referenced in FileContext until the DeleteFile event. Alternatively, an event handler may set FileContext to an empty value, in which case, a DeleteFile event handler will receive that empty value as a file context.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.