FUSE Class

Properties Methods Events Config Settings Errors

The FUSE class gives applications the ability to create a virtual filesystem using a FUSE-like API.

Syntax

FUSE

Remarks

The FUSE class is used to create a virtual filesystem whose contents are stored and exposed in an application-defined manner. The FUSE class offers applications an API similar to the one used by the FUSE library on Linux.

Getting Started

Each FUSE class instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the FUSE 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:

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 (dynamic link library). Please refer to the Driver Installation topic for more information.
Call the Initialize method to initialize the FUSE class. This must be done each time the application starts (if the application is using multiple FUSE class instances, only the first instance created should be used to call Initialize).
Ensure that all of the necessary event handlers have been implemented. Some event handlers, such as Open, Read, GetAttr, and ReadDir, are mandatory and must be implemented by all applications (this is not an exhaustive list). Others are optional, and need to be implemented only when certain features are enabled. Please refer to the events' documentation for more information.
Create a virtual drive by calling the Mount method. This operation incorporates several steps, such as creation of the virtual disk, mounting a "storage media" and adding a mounting point. A mounting point can be a drive letter, a universal naming convention (UNC) path, or a directory on an existing NTFS-formatted drive (see Mounting Points for details).
The application can unmount the "media" from the virtual drive using the Unmount method.
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.


SerializeEvents	Whether events should be fired on a single worker thread, or many.
StorageCharacteristics	This property includes the characteristic flags with which to create the virtual drive (Windows only).
Tag	This property stores application-defined data specific to a particular instance of the class.

Method List

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


Config	Sets or retrieves a configuration setting.
FileTimeToNanoseconds	This method returns the subsecond part of the time expressed in nanoseconds.
FileTimeToUnixTime	This method converts FileTime to the Unix time format.
FillDir	This method fills the buffer with information about a directory entry.
GetDriverStatus	This method retrieves the status of the system driver.
GetDriverVersion	This method retrieves the version of the system driver.
GetGid	This method returns the group Id of the caller process.
GetUid	The method returns the user Id of the caller process.
Initialize	This method initializes the class.
Install	This method installs or upgrades the product's system drivers (Windows only).
Mount	This method creates a virtual drive or directory and mounts a filesystem.
Uninstall	Uninstalls the product's system drivers and/or helper DLL (Windows only).
UnixTimeToFileTime	This event converts the date/time in Unix format to Windows FileTime format.
Unmount	This method unmounts a filesystem.

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.


Access	This event fires when the OS needs to check file access permissions.
Chmod	This event fires when the OS needs to change the permission bits of a file.
Chown	This event fires when the OS needs to change the owner and group of a file.
CopyFileRange	This event fires when the OS needs to copy a range of data from one file to another.
Create	This event fires when the OS wants to create a file.
Destroy	This event fires upon filesystem exit.
Error	This event fires if an unhandled error occurs during an event.
FAllocate	This event fires when the OS needs to allocate space for an open file.
Flush	This event fires when the OS needs to flush an open file's data out to storage before the file is closed.
FSync	This event fires when the OS needs to flush an open file's data out to storage.
GetAttr	This event fires when the OS needs information about a file or directory.
Init	This event fires on filesystem startup.
Lock	This event fires when the OS needs to lock or unlock the range of bytes of a file.
MkDir	This event fires when the OS needs to create a directory.
Open	This event fires when the OS wants to open a file.
Read	This event fires when the OS needs to read data from an open file.
ReadDir	This event fires when the OS wants to read (enumerate) a directory's contents.
Release	This event fires when the OS needs to release (close) a file.
Rename	This event fires when the OS wants to rename or move a file or directory within the virtual filesystem.
RmDir	This event fires when the OS wants to remove (delete) a directory.
StatFS	This event fires when the OS needs information about the virtual drive's capacity and free space.
Truncate	This event fires when the OS needs to truncate (set the size of) a file.
Unlink	This event fires when the OS wants to unlink (delete) a file.
Utimens	This event fires when the OS needs to change access and modification times of a file.
Write	This event fires when the OS needs to write data to an open file.

Config Settings

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


AsyncMountingPointNotifications	Whether system broadcasts for virtual drive mounting and unmounting are sent asynchronously.
LinuxFUSEParams	A placeholder for additional parameters used for fine-tuning FUSE on Linux.
MaxWorkerThreadCount	The maximum number of worker threads to use to fire events.
MetadataCacheEnabled	Whether or not the metadata cache should be used.
MinWorkerThreadCount	The minimum number of worker threads to use to fire events.
NonExistentFilesCacheEnabled	Whether or not the nonexistent files cache should be used.
Timeout	Specifies how many milliseconds the driver will wait for events to execute before cancelling the underlying OS requests. (Windows-only).
TranslateDOSCharsInEnumMasks	Whether the DOS wildcard characters should be translated during search.
WorkerInitialStackSize	The initial stack size to create worker threads with.
BuildInfo	Information about the product's build.
LicenseInfo	Information about the current license.

SerializeEvents Property (FUSE Class)

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

Syntax

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

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

Possible Values

SE_ON_MULTIPLE_THREADS(0), 
SE_ON_ONE_WORKER_THREAD(1)

int cbfsconnect_fuse_getserializeevents(void* lpObj);
int cbfsconnect_fuse_setserializeevents(void* lpObj, int iSerializeEvents);

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

Default Value

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:


0 (seOnMultipleThreads)	The class fires events in the context of multiple worker threads. Windows: The MinWorkerThreadCount and MaxWorkerThreadCount configuration settings control how many worker threads are used for this.
1 (seOnOneWorkerThread)	The class fires events in the context of one background worker thread.

Windows: 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. Please refer to the Threading and Concurrency topic for more information.

Linux: with this property set to seOnMultipleThreads, the class may fire events related to the same file concurrently in several threads. If the application doesn't support this, it should stick to the seOnOneWorkerThread mode.

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

Data Type

Integer

StorageCharacteristics Property (FUSE Class)

This property includes the characteristic flags with which to create the virtual drive (Windows only).

Syntax

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

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

int cbfsconnect_fuse_getstoragecharacteristics(void* lpObj);
int cbfsconnect_fuse_setstoragecharacteristics(void* lpObj, int iStorageCharacteristics);

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

Default Value

Remarks

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


STGC_FLOPPY_DISKETTE	`0x00000001`	The storage is a floppy disk device. This flag is not supported when StorageType is set to `STGT_DISK_PNP`.
STGC_READONLY_DEVICE	`0x00000002`	The storage is a read-only device.
STGC_WRITE_ONCE_MEDIA	`0x00000008`	The storage device's media can only be written to once. This flag is not supported when StorageType is set to `STGT_DISK_PNP`.
STGC_REMOVABLE_MEDIA	`0x00000010`	The storage device's media is removable. Users may remove the storage media from the virtual drive at any time. (Note that this flag does not indicate that the virtual drive itself is removable.)
STGC_AUTOCREATE_DRIVE_LETTER	`0x00002000`	The system should automatically create a drive letter for the storage device. *Deprecated:* Include the `STGMP_AUTOCREATE_DRIVE_LETTER` flag in the value passed for the AddMountingPoint method's `Flags` parameter instead. When this flag is present, the StorageGUID property must be set. This flag only works when StorageType is set to `STGT_DISK_PNP`.
STGC_SHOW_IN_EJECTION_TRAY	`0x00004000`	The storage device should be shown in the 'Safely Remove Hardware and Eject Media' menu in the system notification area (system tray). This flag only works when StorageType is set to `STGT_DISK_PNP`.
STGC_ALLOW_EJECTION	`0x00008000`	The storage device can be ejected. Users may eject the virtual drive at any time. When the virtual drive is ejected, it is destroyed. This flag only works when StorageType is set to `STGT_DISK_PNP`.
STGC_RESERVED_1	`0x00010000`	Reserved, do not use.
STGC_RESERVED_2	`0x00020000`	Reserved, do not use.

Note: This property cannot be changed when the drive is mounted and cannot be changed within events.

Data Type

Integer

Tag Property (FUSE Class)

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

Syntax

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

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

int64 cbfsconnect_fuse_gettag(void* lpObj);
int cbfsconnect_fuse_settag(void* lpObj, int64 lTag);

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

Default Value

Remarks

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

Data Type

Long64

Config Method (FUSE Class)

Sets or retrieves a configuration setting.

Syntax

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

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cbfsconnect_fuse_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.

FileTimeToNanoseconds Method (FUSE Class)

This method returns the subsecond part of the time expressed in nanoseconds.

Syntax

ANSI (Cross Platform)
int FileTimeToNanoseconds(int64 lFileTime);

Unicode (Windows)
INT FileTimeToNanoseconds(LONG64 lFileTime);

int cbfsconnect_fuse_filetimetonanoseconds(void* lpObj, int64 lFileTime);

int FileTimeToNanoseconds(QDateTime qdtFileTime);

Remarks

Use this method to obtain the subsecond part of the FileTime value, expressed in nanoseconds.

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.

FileTimeToUnixTime Method (FUSE Class)

This method converts FileTime to the Unix time format.

Syntax

ANSI (Cross Platform)
int64 FileTimeToUnixTime(int64 lFileTime);

Unicode (Windows)
LONG64 FileTimeToUnixTime(LONG64 lFileTime);

int64 cbfsconnect_fuse_filetimetounixtime(void* lpObj, int64 lFileTime);

qint64 FileTimeToUnixTime(QDateTime qdtFileTime);

Remarks

Use this method to convert the FileTime value to the Unix time format. The subsecond part of the value is not preserved; to obtain it, use the FileTimeToNanoseconds method.

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.

FillDir Method (FUSE Class)

This method fills the buffer with information about a directory entry.

Syntax

ANSI (Cross Platform)
int FillDir(int64 lFillerContext, const char* lpszName, int64 lIno, int iMode, int iUid, int iGid, int iLinkCount, int64 lSize, int64 lATime, int64 lMTime, int64 lCTime);

Unicode (Windows)
INT FillDir(LONG64 lFillerContext, LPCWSTR lpszName, LONG64 lIno, INT iMode, INT iUid, INT iGid, INT iLinkCount, LONG64 lSize, LONG64 lATime, LONG64 lMTime, LONG64 lCTime);

int cbfsconnect_fuse_filldir(void* lpObj, int64 lFillerContext, const char* lpszName, int64 lIno, int iMode, int iUid, int iGid, int iLinkCount, int64 lSize, int64 lATime, int64 lMTime, int64 lCTime);

int FillDir(qint64 lFillerContext, const QString& qsName, qint64 lIno, int iMode, int iUid, int iGid, int iLinkCount, qint64 lSize, QDateTime qdtATime, QDateTime qdtMTime, QDateTime qdtCTime);

Remarks

Use the FillDir method from the ReadDir event handler to fill the buffer with the information about a file.

Call the method in a loop to add multiple entries.

The FillerContext parameter is passed to the ReadDir event handler and must be passed by the event handler to this method without modifications.

The Name parameter should contain the name of the directory entry.

The Ino parameter should be set to the Id of the file, which must be unique within a filesystem. Ino is optional on Windows and is ignored on Linux, where FUSE internally generates internal Ids.

The Mode parameter is a combination of bit flags.

Windows: Mode may include 0x4000 (S_IFDIR) to indicate that the entry is a directory, and it must include either 0x80 (S_IWUSR) to indicate a file that can be read and written or 0x100 (S_IRUSR) to indicate a read-only file. Other flags are ignored.

Linux: Mode may include any appropriate file mode flags. See inode(7) for more information.

Windows: The Uid, Gid, and LinkCount parameters are not used.

Linux: The Uid and Gid parameters must be set to the owner's user Id and group Id, respectively. LinkCount should be set to the number of hard links that the file has (which usually is 1).

Size must be set to the size of the file's data. For directories, the parameter should be set to 0.

ATime, MTime, CTime: Set, respectively, to the Access Time, Modification Time, and Creation Time values of the file or directory. All date/time parameters in the class are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC (Windows) or as a number of seconds since Jan 1, 1970 00:00:00 UTC (Linux).

To convert Unix time to a format suitable for this function, use the UnixTimeToFileTime method.

Windows:

Any nonapplicable time values can be set to 0.

The method returns 0 on success and sends an error code otherwise.

Note: This method cannot be called within events.

Error Handling (C++)

GetDriverStatus Method (FUSE Class)

This method retrieves the status of the system driver.

Syntax

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

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID);

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

int GetDriverStatus(const QString& qsProductGUID);

Remarks

Windows:

This method retrieves the status of the system driver. 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:


MODULE_STATUS_NOT_PRESENT	`0x00000000`	The specified module is not present on the system.
MODULE_STATUS_STOPPED	`0x00000001`	The specified module is in the Stopped state.
MODULE_STATUS_RUNNING	`0x00000004`	The specified module is loaded and running.

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

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.

Linux:

This method currently is not used.

Error Handling (C++)

GetDriverVersion Method (FUSE Class)

This method retrieves the version of the system driver.

Syntax

ANSI (Cross Platform)
int64 GetDriverVersion(const char* lpszProductGUID);

Unicode (Windows)
LONG64 GetDriverVersion(LPCWSTR lpszProductGUID);

int64 cbfsconnect_fuse_getdriverversion(void* lpObj, const char* lpszProductGUID);

qint64 GetDriverVersion(const QString& qsProductGUID);

Remarks

This method retrieves the version of the system driver. 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 driver is not installed, this method returns 0.

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

Install
Uninstall
GetDriverStatus
GetModuleVersion
RegisterIcon
UnregisterIcon
Initialize

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++)

GetGid Method (FUSE Class)

This method returns the group Id of the caller process.

Syntax

ANSI (Cross Platform)
int GetGid();

Unicode (Windows)
INT GetGid();

int cbfsconnect_fuse_getgid(void* lpObj);

int GetGid();

Remarks

Windows:

This event currently is not used.

Linux:

Call this method from the event handlers to obtain the group Id of the caller process.

Error Handling (C++)

GetUid Method (FUSE Class)

The method returns the user Id of the caller process.

Syntax

ANSI (Cross Platform)
int GetUid();

Unicode (Windows)
INT GetUid();

int cbfsconnect_fuse_getuid(void* lpObj);

int GetUid();

Remarks

Windows:

This event currently is not used.

Linux:

Call this method from the event handlers to obtain the user Id of the caller process.

Error Handling (C++)

Initialize Method (FUSE Class)

This method initializes the class.

Syntax

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

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);

int cbfsconnect_fuse_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.

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

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 (FUSE Class)

This method installs or upgrades the product's system drivers (Windows only).

Syntax

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

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

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

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

Remarks

Windows:

This method is used to install or upgrade the product's system driver. If the system must be rebooted to complete the installation process, this method will return a nonzero value.

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.

Note: This .cab file must remain on the target system (or be available in some other way) after installation, because it is required to uninstall the modules from the system.

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

Install
Uninstall
GetDriverStatus
GetModuleVersion
RegisterIcon
UnregisterIcon
Initialize

PathToInstall controls where the modules are installed. Pass an empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

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


INSTALL_REMOVE_OLD_VERSIONS	`0x00000001`	Uninstall drivers and helper DLLs from previous class versions (e.g., 2017).
INSTALL_KEEP_START_TYPE	`0x00000002`	Keep the driver's current start type setting in the registry. If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application itself) set it previously.
INSTALL_OVERWRITE_SAME_VERSION	`0x00000004`	Install files when their version is the same as the version of already installed files. If this flag is not set (default), the installation logic will overwrite the existing file only if the version number of the file being installed is larger than the version of the file being overwritten. Setting this flag causes the installation logic to overwrite the file even when it has the same version.
INSTALL_FORCE_SHA1_DRIVERS	`0x00000008`	Tell the installer to use SHA1-signed drivers regardless of the OS. If this flag is not set (default), the installation logic will use SHA1 drivers only on Windows 7. However, some systems based on Windows 8.x, despite supporting SHA2 driver signatures, refuse to install the Plug-n-play drivers signed by Microsoft using SHA256 (error 0xe0000244 is reported). To work around this problem, you may use this flag - a system should accept SHA1-signed drivers then. Note that the flag should be used only as a fallback when the system returns the above-mentioned error code during the regular installation procedure.

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.

Linux:

This method currently is not used.

Error Handling (C++)

Mount Method (FUSE Class)

This method creates a virtual drive or directory and mounts a filesystem.

Syntax

ANSI (Cross Platform)
int Mount(const char* lpszMountPoint);

Unicode (Windows)
INT Mount(LPCWSTR lpszMountPoint);

int cbfsconnect_fuse_mount(void* lpObj, const char* lpszMountPoint);

int Mount(const QString& qsMountPoint);

Remarks

Call this method to create a virtual drive or directory and mount a filesystem.

The MountPoint parameter contains a path to the directory, into which the virtual filesystem is "inserted". This path must exist at the time of mounting and must be empty.

Windows:

The MountPoint parameter may also contain a drive letter or a UNC path; please refer to the Mounting Points topic for more information.

Error Handling (C++)

Uninstall Method (FUSE Class)

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

Syntax

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_fuse_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).

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:


UNINSTALL_VERSION_PREVIOUS	`0x00000001`	Uninstall modules from previous product versions.
UNINSTALL_VERSION_CURRENT	`0x00000002`	Uninstall modules from the current product version.
UNINSTALL_VERSION_ALL	`0x00000003`	Uninstall modules from all product versions.

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++)

UnixTimeToFileTime Method (FUSE Class)

This event converts the date/time in Unix format to Windows FileTime format.

Syntax

ANSI (Cross Platform)
int64 UnixTimeToFileTime(int64 lUnixTime, int iNanoseconds);

Unicode (Windows)
LONG64 UnixTimeToFileTime(LONG64 lUnixTime, INT iNanoseconds);

int64 cbfsconnect_fuse_unixtimetofiletime(void* lpObj, int64 lUnixTime, int iNanoseconds);

QDateTime UnixTimeToFileTime(qint64 lUnixTime, int iNanoseconds);

Remarks

Use this method to convert the date/time in Unix format to Windows FileTime format.

Pass the Unix time value to UnixTime and optionally pass the subsecond part of the time, expressed in nanoseconds, to the Nanoseconds parameter. If the subsecond part of the time is not available, set Nanoseconds to zero (0) value.

Error Handling (C++)

Unmount Method (FUSE Class)

This method unmounts a filesystem.

Syntax

ANSI (Cross Platform)
int Unmount();

Unicode (Windows)
INT Unmount();

int cbfsconnect_fuse_unmount(void* lpObj);

int Unmount();

Remarks

This method unmounts the mounted filesystem and deletes a virtual device from the system.

Linux:

To handle requests of the sytem FUSE library, the class uses a dedicated thread. If there exist open handles to items in a mounting point, FUSE doesn't finish its operations, while the class waits for FUSE to finish. The class can forcefully stop FUSE operations, but only in the application that uses the class didn't set a handler for the SIGINT signal. If such a handler is set, the class cannot forcefully stop the operations and has to wait for the handles to be closed and for FUSE to stop.

If a process that uses the class is killed or crashes, there's a hanging FUSE mounting point left visible in the system. To remove it, call one of these commands:

if a process was run under the same user account that performs the removal operation, call "fusermount -u <mounting_point>", where "mounting_point" is a mounting point, to which the virtual filesystem was mounted.
if a process was run under a different user account, call "sudo umount <mounting_point>" instead. Note that this operation requires that a user either is root or is included in the sodoers group.

Error Handling (C++)

Access Event (FUSE Class)

This event fires when the OS needs to check file access permissions.

Syntax

ANSI (Cross Platform)
virtual int FireAccess(FUSEAccessEventParams *e);

typedef struct {
  const char *Path;
  int Mask;
  int Result;
  int reserved;
} FUSEAccessEventParams;


Unicode (Windows)
virtual INT FireAccess(FUSEAccessEventParams *e);

typedef struct {
  LPCWSTR Path;
  INT Mask;
  INT Result;
  INT reserved;
} FUSEAccessEventParams;

#define EID_FUSE_ACCESS 1

virtual INT CBFSCONNECT_CALL FireAccess(LPWSTR &lpszPath, INT &iMask, INT &iResult);

class FUSEAccessEventParams {
public:
  const QString &Path();

  int Mask();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireAccess(FUSEAccessEventParams *e) {...}

Remarks

Windows:

This event fires when the OS needs to know whether the file or directory specified in Path can be deleted. For this, the Mask parameter is set to 2 (W_OK).

The application must return 0 in the Result parameter to indicate that deletion is permitted, or otherwise sends an error code.

Linux:

This event fires when the OS needs to check access permissions of the file or directory specified in Path. Specifically, the event fires when a process uses the access() system call.

The application must return 0 in the Result parameter to indicate that access requested by the Mask parameter is permitted, or otherwise sends -EACCES< to indicate that access is denied.

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 negative error code value (e.g., -ENOENT to indicate that the file does not exist) to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Chmod Event (FUSE Class)

This event fires when the OS needs to change the permission bits of a file.

Syntax

ANSI (Cross Platform)
virtual int FireChmod(FUSEChmodEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int Mode;
  int Result;
  int reserved;
} FUSEChmodEventParams;


Unicode (Windows)
virtual INT FireChmod(FUSEChmodEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT Mode;
  INT Result;
  INT reserved;
} FUSEChmodEventParams;

#define EID_FUSE_CHMOD 2

virtual INT CBFSCONNECT_CALL FireChmod(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iMode, INT &iResult);

class FUSEChmodEventParams {
public:
  const QString &Path();

  void *FileContext();

  int Mode();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireChmod(FUSEChmodEventParams *e) {...}

Remarks

Windows:

This event is not used.

Linux:

This event fires when the OS needs to change the permission bits of a file or directory and is identified either by Path or FileContext.

Mode contains the new permission bits.

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 negative error code value (e.g., -ENOENT to indicate that the file does not exist) to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Chown Event (FUSE Class)

This event fires when the OS needs to change the owner and group of a file.

Syntax

ANSI (Cross Platform)
virtual int FireChown(FUSEChownEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int Uid;
  int Gid;
  int Result;
  int reserved;
} FUSEChownEventParams;


Unicode (Windows)
virtual INT FireChown(FUSEChownEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT Uid;
  INT Gid;
  INT Result;
  INT reserved;
} FUSEChownEventParams;

#define EID_FUSE_CHOWN 3

virtual INT CBFSCONNECT_CALL FireChown(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iUid, INT &iGid, INT &iResult);

class FUSEChownEventParams {
public:
  const QString &Path();

  void *FileContext();

  int Uid();

  int Gid();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireChown(FUSEChownEventParams *e) {...}

Remarks

Windows:

This event currently is not used.

Linux:

This event fires when the OS needs to change the owner and group of a file or directory and is identified by either Path or FileContext.

Uid and Gid contain the new owner Id and group Id, respectively.

CopyFileRange Event (FUSE Class)

This event fires when the OS needs to copy a range of data from one file to another.

Syntax

ANSI (Cross Platform)
virtual int FireCopyFileRange(FUSECopyFileRangeEventParams *e);

typedef struct {
  const char *PathIn;
  void *FileContextIn;
  int64 OffsetIn;
  const char *PathOut;
  void *FileContextOut;
  int64 OffsetOut;
  int64 Size;
  int Flags;
  int Result;
  int reserved;
} FUSECopyFileRangeEventParams;


Unicode (Windows)
virtual INT FireCopyFileRange(FUSECopyFileRangeEventParams *e);

typedef struct {
  LPCWSTR PathIn;
  LPVOID FileContextIn;
  LONG64 OffsetIn;
  LPCWSTR PathOut;
  LPVOID FileContextOut;
  LONG64 OffsetOut;
  LONG64 Size;
  INT Flags;
  INT Result;
  INT reserved;
} FUSECopyFileRangeEventParams;

#define EID_FUSE_COPYFILERANGE 4

virtual INT CBFSCONNECT_CALL FireCopyFileRange(LPWSTR &lpszPathIn, LPVOID &lpFileContextIn, LONG64 &lOffsetIn, LPWSTR &lpszPathOut, LPVOID &lpFileContextOut, LONG64 &lOffsetOut, LONG64 &lSize, INT &iFlags, INT &iResult);

class FUSECopyFileRangeEventParams {
public:
  const QString &PathIn();

  void *FileContextIn();

  qint64 OffsetIn();

  const QString &PathOut();

  void *FileContextOut();

  qint64 OffsetOut();

  qint64 Size();

  int Flags();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireCopyFileRange(FUSECopyFileRangeEventParams *e) {...}

Remarks

Windows:

This event currently is not used.

Linux:

This event fires when the OS needs to copy a range of data from one file to another. The source file is identified either by PathIn or FileContextIn. The destination file is identified either by PathOut or FileContextOut.

OffsetIn specifies the starting offset in the source file from which the data are taken.

OffsetOut specifies the starting offset in the destination file, to which the data should be written.

Size specifies the size of the data block to be copied.

Flags is provided for future extensions and currently is not used.

Create Event (FUSE Class)

This event fires when the OS wants to create a file.

Syntax

ANSI (Cross Platform)
virtual int FireCreate(FUSECreateEventParams *e);

typedef struct {
  const char *Path;
  int Mode;
  void *FileContext;
  int Result;
  int reserved;
} FUSECreateEventParams;


Unicode (Windows)
virtual INT FireCreate(FUSECreateEventParams *e);

typedef struct {
  LPCWSTR Path;
  INT Mode;
  LPVOID FileContext;
  INT Result;
  INT reserved;
} FUSECreateEventParams;

#define EID_FUSE_CREATE 5

virtual INT CBFSCONNECT_CALL FireCreate(LPWSTR &lpszPath, INT &iMode, LPVOID &lpFileContext, INT &iResult);

class FUSECreateEventParams {
public:
  const QString &Path();

  int Mode();

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

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireCreate(FUSECreateEventParams *e) {...}

Remarks

This event fires when the OS wants to create a file named Path.

Linux:

The application must create the file according to the creation mode and open it afterward. The creation mode is specified in the Mode parameter, whose values correspond to the ones used in the creat() function in POSIX and the Linux API.

The application may use the FileContext parameter to store a file handle or other information that is related to the open file. Windows:

The stored information will be shared between all concurrent file open operations performed on this file.

Destroy Event (FUSE Class)

This event fires upon filesystem exit.

Syntax

ANSI (Cross Platform)
virtual int FireDestroy(FUSEDestroyEventParams *e);

typedef struct {
  int reserved;
} FUSEDestroyEventParams;


Unicode (Windows)
virtual INT FireDestroy(FUSEDestroyEventParams *e);

typedef struct {
  INT reserved;
} FUSEDestroyEventParams;

#define EID_FUSE_DESTROY 6

virtual INT CBFSCONNECT_CALL FireDestroy();

class FUSEDestroyEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

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

// Or, subclass FUSE and override this emitter function.
virtual int FireDestroy(FUSEDestroyEventParams *e) {...}

Remarks

This event fires when the filesystem is shut down.

Error Event (FUSE Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireError(FUSEErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} FUSEErrorEventParams;


Unicode (Windows)
virtual INT FireError(FUSEErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} FUSEErrorEventParams;

#define EID_FUSE_ERROR 7

virtual INT CBFSCONNECT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class FUSEErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireError(FUSEErrorEventParams *e) {...}

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

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

FAllocate Event (FUSE Class)

This event fires when the OS needs to allocate space for an open file.

Syntax

ANSI (Cross Platform)
virtual int FireFAllocate(FUSEFAllocateEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int Mode;
  int64 Offset;
  int64 Length;
  int Result;
  int reserved;
} FUSEFAllocateEventParams;


Unicode (Windows)
virtual INT FireFAllocate(FUSEFAllocateEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT Mode;
  LONG64 Offset;
  LONG64 Length;
  INT Result;
  INT reserved;
} FUSEFAllocateEventParams;

#define EID_FUSE_FALLOCATE 8

virtual INT CBFSCONNECT_CALL FireFAllocate(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iMode, LONG64 &lOffset, LONG64 &lLength, INT &iResult);

class FUSEFAllocateEventParams {
public:
  const QString &Path();

  void *FileContext();

  int Mode();

  qint64 Offset();

  qint64 Length();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireFAllocate(FUSEFAllocateEventParams *e) {...}

Remarks

This event fires when the OS needs to allocate space for an open file. The file is identified by FileContext, and the Path parameter contains the name of the file.

The event should increase the allocation size (it may not decrease the allocation size) according to the following rule: new allocation size of the file must be the greater of Offset+Length and the current file size. The actual file size must be adjusted up to match the new allocation size unless the Mode parameter includes the value 1 (FALLOC_FL_KEEP_SIZE). In the latter case, the size remains unchanged. On Windows, the class always specifies FALLOC_FL_KEEP_SIZE, but on other systems, the flag may be absent. If the size was increased, the event handler must fill the newly added space with zeros (i.e., zeroize space).

Linux: The OS may send additional flags in the Mode parameter to manipulate file contents. An event handler should check the presense of such flags and deny the request if the requested flags are not supported.

The range of the file data to allocate space for and zeroize starts from Offset and occupies Length bytes.

The event handler must ensure that the required space is allocated for specified file. If the event handler returns success, then any subsequent write request to the specified range must be guaranteed not to fail because of lack of space in the backend storage.

Flush Event (FUSE Class)

This event fires when the OS needs to flush an open file's data out to storage before the file is closed.

Syntax

ANSI (Cross Platform)
virtual int FireFlush(FUSEFlushEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int Result;
  int reserved;
} FUSEFlushEventParams;


Unicode (Windows)
virtual INT FireFlush(FUSEFlushEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT Result;
  INT reserved;
} FUSEFlushEventParams;

#define EID_FUSE_FLUSH 9

virtual INT CBFSCONNECT_CALL FireFlush(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iResult);

class FUSEFlushEventParams {
public:
  const QString &Path();

  void *FileContext();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireFlush(FUSEFlushEventParams *e) {...}

Remarks

This event fires any time the OS needs the virtual filesystem to flush data out to storage when the file is about to be closed. The file to flush is identified by either Path or FileContext.

When the file is opened several times, the event will be fired for each file close. Linux:

The OS gives no guarantee as to the number of times (if any) the event will fire.

To handle this event properly, applications must flush the requested data, writing it out to their backend storage.

FSync Event (FUSE Class)

This event fires when the OS needs to flush an open file's data out to storage.

Syntax

ANSI (Cross Platform)
virtual int FireFSync(FUSEFSyncEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int DataSync;
  int Result;
  int reserved;
} FUSEFSyncEventParams;


Unicode (Windows)
virtual INT FireFSync(FUSEFSyncEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT DataSync;
  INT Result;
  INT reserved;
} FUSEFSyncEventParams;

#define EID_FUSE_FSYNC 10

virtual INT CBFSCONNECT_CALL FireFSync(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iDataSync, INT &iResult);

class FUSEFSyncEventParams {
public:
  const QString &Path();

  void *FileContext();

  int DataSync();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireFSync(FUSEFSyncEventParams *e) {...}

Remarks

This event fires when the OS needs the virtual filesystem to flush data of the file out to storage, which can happen at any time the file is opened. The file to flush is identified by either Path or FileContext.

To handle this event properly, applications must flush the requested data, writing it out to their backend storage.

Linux:

The nonzero of the DataSync parameter indicates that only the user data should be flushed and not the metadata.

GetAttr Event (FUSE Class)

This event fires when the OS needs information about a file or directory.

Syntax

ANSI (Cross Platform)
virtual int FireGetAttr(FUSEGetAttrEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int64 *pIno;
  int Mode;
  int Uid;
  int Gid;
  int LinkCount;
  int64 *pSize;
  int64 *pATime;
  int64 *pMTime;
  int64 *pCTime;
  int Result;
  int reserved;
} FUSEGetAttrEventParams;


Unicode (Windows)
virtual INT FireGetAttr(FUSEGetAttrEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  LONG64 *pIno;
  INT Mode;
  INT Uid;
  INT Gid;
  INT LinkCount;
  LONG64 *pSize;
  LONG64 *pATime;
  LONG64 *pMTime;
  LONG64 *pCTime;
  INT Result;
  INT reserved;
} FUSEGetAttrEventParams;

#define EID_FUSE_GETATTR 11

virtual INT CBFSCONNECT_CALL FireGetAttr(LPWSTR &lpszPath, LPVOID &lpFileContext, LONG64 &lIno, INT &iMode, INT &iUid, INT &iGid, INT &iLinkCount, LONG64 &lSize, LONG64 &lATime, LONG64 &lMTime, LONG64 &lCTime, INT &iResult);

class FUSEGetAttrEventParams {
public:
  const QString &Path();

  void *FileContext();

  qint64 Ino();
  void SetIno(qint64 lIno);

  int Mode();
  void SetMode(int iMode);

  int Uid();
  void SetUid(int iUid);

  int Gid();
  void SetGid(int iGid);

  int LinkCount();
  void SetLinkCount(int iLinkCount);

  qint64 Size();
  void SetSize(qint64 lSize);

  const QDateTime &ATime();
  void SetATime(const QDateTime &qdtATime);

  const QDateTime &MTime();
  void SetMTime(const QDateTime &qdtMTime);

  const QDateTime &CTime();
  void SetCTime(const QDateTime &qdtCTime);

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireGetAttr(FUSEGetAttrEventParams *e) {...}

Remarks

This event fires when the OS needs information about the file or directory identified by either Path or FileContext (the latter in most cases will not be initialized). If the entry with the specified name does not exist, the handler must return ENOENT in the Result parameter.

The Ino parameter should be set to the Id of the file, which must be unique within a filesystem. Ino is optional on Windows and is ignored on Linux, where FUSE internally generates internal Ids.

The Mode parameter is a combination of bit flags.

Linux: Mode may include any appropriate file mode flags. See inode(7) for more information.

Windows: The Uid, Gid, and LinkCount parameters are not used.

Linux: The Uid and Gid parameters must be set to the owner's user Id and group Id, respectively. LinkCount should be set to the number of hard links that the file has (which usually is 1).

Size must be set to the size of the file's data. For directories, the parameter should be set to 0.

To convert Unix time to the format that is suitable for this event, use the UnixTimeToFileTime method.

Windows:

Any nonapplicable time values can be left unchanged, or set to 0.

Note: For this event, returning ERROR_FILE_INVALID has no effect.

Init Event (FUSE Class)

This event fires on filesystem startup.

Syntax

ANSI (Cross Platform)
virtual int FireInit(FUSEInitEventParams *e);

typedef struct {
  int Result;
  int reserved;
} FUSEInitEventParams;


Unicode (Windows)
virtual INT FireInit(FUSEInitEventParams *e);

typedef struct {
  INT Result;
  INT reserved;
} FUSEInitEventParams;

#define EID_FUSE_INIT 12

virtual INT CBFSCONNECT_CALL FireInit(INT &iResult);

class FUSEInitEventParams {
public:
  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireInit(FUSEInitEventParams *e) {...}

Remarks

This event fires when the filesystem is started.

Lock Event (FUSE Class)

This event fires when the OS needs to lock or unlock the range of bytes of a file.

Syntax

ANSI (Cross Platform)
virtual int FireLock(FUSELockEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int LockType;
  int64 LockStart;
  int64 LockLen;
  int Cmd;
  int64 LockOwner;
  int LockPid;
  int Result;
  int reserved;
} FUSELockEventParams;


Unicode (Windows)
virtual INT FireLock(FUSELockEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT LockType;
  LONG64 LockStart;
  LONG64 LockLen;
  INT Cmd;
  LONG64 LockOwner;
  INT LockPid;
  INT Result;
  INT reserved;
} FUSELockEventParams;

#define EID_FUSE_LOCK 13

virtual INT CBFSCONNECT_CALL FireLock(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iLockType, LONG64 &lLockStart, LONG64 &lLockLen, INT &iCmd, LONG64 &lLockOwner, INT &iLockPid, INT &iResult);

class FUSELockEventParams {
public:
  const QString &Path();

  void *FileContext();

  int LockType();

  qint64 LockStart();

  qint64 LockLen();

  int Cmd();

  qint64 LockOwner();

  int LockPid();
  void SetLockPid(int iLockPid);

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireLock(FUSELockEventParams *e) {...}

Remarks

This event fires when the OS needs to lock or unlock the range of bytes of the file, identified by either Path or FileContext. Local locking is performed by the system and your application needs to handle this even when it needs to perform an operation over the network.

LockType identifies whether the range is to be locked or unlocked. It can be one of the following:


FUSE_RDLCK	`0x0000`	Read lock should be acquired. Other applications may read from the locked range but not write to it. The constant is the same as the F_RDLCK constant used in Linux.
FUSE_WRLCK	`0x0001`	Write lock should be acquired. No other application may write to the locked range. The constant is the same as the F_WRLCK constant used in Linux.
FUSE_UNLCK	`0x0002`	The lock should be released. The constant is the same as the F_UNLCK constant used in Linux.

LockStart and LockLen specify the starting position and the length of the block to be locked or unlocked. Cmd can be one of


FUSE_GETLK	`0x0005`	The lock owner is to be retrieved. This command is not used in Windows. In Linux, the process identifier (PID) of the lock owner must be returned. The constant is the same as the F_GETLK constant used in Linux.
FUSE_SETLK	`0x0006`	Set lock. If the lock cannot be set immediately, return immediately with an error (EAGAIN and EACCES are recommended). The constant is the same as the F_SETLK constant used in Linux.
FUSE_SETLKW	`0x0007`	Set lock and wait. If the lock cannot be set immediately, wait until this becomes possible. The constant is the same as the F_SETLKW constant used in Linux.

Windows:

LockOwner and LockPid parameters are not used and are set to 0.

Linux:

This event fires for a POSIX-style lock. For additional information about LockOwner and other parameters, please refer to http://libfuse.github.io/doxygen/structfuse__operations.html#a1c3fff5cf0c1c2003d117e764b9a76fd.

if Cmd is F_GETLK, the event handler should place the PID of the owner process to the LockPid parameter.

MkDir Event (FUSE Class)

This event fires when the OS needs to create a directory.

Syntax

ANSI (Cross Platform)
virtual int FireMkDir(FUSEMkDirEventParams *e);

typedef struct {
  const char *Path;
  int Mode;
  int Result;
  int reserved;
} FUSEMkDirEventParams;


Unicode (Windows)
virtual INT FireMkDir(FUSEMkDirEventParams *e);

typedef struct {
  LPCWSTR Path;
  INT Mode;
  INT Result;
  INT reserved;
} FUSEMkDirEventParams;

#define EID_FUSE_MKDIR 14

virtual INT CBFSCONNECT_CALL FireMkDir(LPWSTR &lpszPath, INT &iMode, INT &iResult);

class FUSEMkDirEventParams {
public:
  const QString &Path();

  int Mode();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireMkDir(FUSEMkDirEventParams *e) {...}

Remarks

This event fires when the OS needs to create a directory, referenced as Path.

The Mode parameter is a combination of bit flags.

Windows:

Mode includes 0x4000 (S_IFDIR) to indicate that the entry is a directory and may include 0x80 (S_IWUSR) to indicate that the directory must not have its ReadOnly attribute set. If the 0x80 flag is not set, the event handler must set a read-only attribute for a newly created directory.

Linux:

Mode includes permission bits and may include additional bits depending on the OS.

Open Event (FUSE Class)

This event fires when the OS wants to open a file.

Syntax

ANSI (Cross Platform)
virtual int FireOpen(FUSEOpenEventParams *e);

typedef struct {
  const char *Path;
  int Flags;
  int DirectIO;
  int KeepCache;
  int NonSeekable;
  void *FileContext;
  int Result;
  int reserved;
} FUSEOpenEventParams;


Unicode (Windows)
virtual INT FireOpen(FUSEOpenEventParams *e);

typedef struct {
  LPCWSTR Path;
  INT Flags;
  BOOL DirectIO;
  BOOL KeepCache;
  BOOL NonSeekable;
  LPVOID FileContext;
  INT Result;
  INT reserved;
} FUSEOpenEventParams;

#define EID_FUSE_OPEN 15

virtual INT CBFSCONNECT_CALL FireOpen(LPWSTR &lpszPath, INT &iFlags, BOOL &bDirectIO, BOOL &bKeepCache, BOOL &bNonSeekable, LPVOID &lpFileContext, INT &iResult);

class FUSEOpenEventParams {
public:
  const QString &Path();

  int Flags();

  bool DirectIO();
  void SetDirectIO(bool bDirectIO);

  bool KeepCache();
  void SetKeepCache(bool bKeepCache);

  bool NonSeekable();
  void SetNonSeekable(bool bNonSeekable);

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

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireOpen(FUSEOpenEventParams *e) {...}

Remarks

This event fires when the OS wants to open the existing file specified by Path using the open options reflected in Flags. The set of possible flags and options corresponds to the Flags parameter of Linux open(2) call.

The application may use the FileContext parameter to store a file handle or other information, related to the open file.

Windows:

The stored information will be shared between all concurrent file open operations performed on this file.

Linux:

DirectIO parameter may be set by the application to tell the kernel that buffering or caching should be avoided. KeepCache parameter may be set by the application to tell the kernel that existing file caches (if any) should not be invalidated. NonSeekable parameter may be set by the application to tell the kernel that the file is not seekable.

Read Event (FUSE Class)

This event fires when the OS needs to read data from an open file.

Syntax

ANSI (Cross Platform)
virtual int FireRead(FUSEReadEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  void *Buffer;
  int64 Size;
  int64 Offset;
  int Result;
  int reserved;
} FUSEReadEventParams;


Unicode (Windows)
virtual INT FireRead(FUSEReadEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  LPVOID Buffer;
  LONG64 Size;
  LONG64 Offset;
  INT Result;
  INT reserved;
} FUSEReadEventParams;

#define EID_FUSE_READ 16

virtual INT CBFSCONNECT_CALL FireRead(LPWSTR &lpszPath, LPVOID &lpFileContext, LPVOID &lpBuffer, LONG64 &lSize, LONG64 &lOffset, INT &iResult);

class FUSEReadEventParams {
public:
  const QString &Path();

  void *FileContext();

  void *Buffer();

  qint64 Size();

  qint64 Offset();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireRead(FUSEReadEventParams *e) {...}

Remarks

This event fires when the OS needs to read data from an already-open file, identified by either Path or FileContext.

To handle this event properly, applications should read Size bytes of data from the specified file into the memory region pointed to by Buffer. Reading must begin at the specified Offset in the file and all of the requested data are expected to be read. Applications must not attempt to copy more than Size bytes of data into Buffer.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

When reading is complete, applications must set Result to the actual number of bytes written to Buffer. Note: Although it is technically possible for an application to return fewer than Size bytes of data, doing so is abnormal and should be avoided. Most processes treat read requests as "all or nothing", so returning less data than requested is likely to cause an ungraceful failure.

ReadDir Event (FUSE Class)

This event fires when the OS wants to read (enumerate) a directory's contents.

Syntax

ANSI (Cross Platform)
virtual int FireReadDir(FUSEReadDirEventParams *e);

typedef struct {
  const char *Path;
  int64 FillerContext;
  int Result;
  int reserved;
} FUSEReadDirEventParams;


Unicode (Windows)
virtual INT FireReadDir(FUSEReadDirEventParams *e);

typedef struct {
  LPCWSTR Path;
  LONG64 FillerContext;
  INT Result;
  INT reserved;
} FUSEReadDirEventParams;

#define EID_FUSE_READDIR 17

virtual INT CBFSCONNECT_CALL FireReadDir(LPWSTR &lpszPath, LONG64 &lFillerContext, INT &iResult);

class FUSEReadDirEventParams {
public:
  const QString &Path();

  qint64 FillerContext();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireReadDir(FUSEReadDirEventParams *e) {...}

Remarks

This event fires when the OS wants to enumerate the contents of the directory, identified by Path. In response to this event, the application must call the FillDir method and pass the FillerContextparameter as well as the information about the directory entry. Please refer to the description of FillDir for further details.

If FillDir returns an error code, set Result to the returned code (do not negate the code). If there are no more files to pass, set Result to 0.

Note: For this event, returning ERROR_FILE_INVALID has no effect.

Release Event (FUSE Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireRelease(FUSEReleaseEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int Flags;
  int Result;
  int reserved;
} FUSEReleaseEventParams;


Unicode (Windows)
virtual INT FireRelease(FUSEReleaseEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  INT Flags;
  INT Result;
  INT reserved;
} FUSEReleaseEventParams;

#define EID_FUSE_RELEASE 18

virtual INT CBFSCONNECT_CALL FireRelease(LPWSTR &lpszPath, LPVOID &lpFileContext, INT &iFlags, INT &iResult);

class FUSEReleaseEventParams {
public:
  const QString &Path();

  void *FileContext();

  int Flags();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireRelease(FUSEReleaseEventParams *e) {...}

Remarks

This event fires when the OS wants to close the file identified by either Path or FileContext.

The Flags parameter contains the same value as the one passed during file creation or opening.

Windows:

If the file is opened two or more times concurrently (i.e., several open handles exist), this parameter will contain the flags of the last open operation rather than the flags of an operation that opened a handle being closed.

Rename Event (FUSE Class)

This event fires when the OS wants to rename or move a file or directory within the virtual filesystem.

Syntax

ANSI (Cross Platform)
virtual int FireRename(FUSERenameEventParams *e);

typedef struct {
  const char *OldPath;
  const char *NewPath;
  int Flags;
  int Result;
  int reserved;
} FUSERenameEventParams;


Unicode (Windows)
virtual INT FireRename(FUSERenameEventParams *e);

typedef struct {
  LPCWSTR OldPath;
  LPCWSTR NewPath;
  INT Flags;
  INT Result;
  INT reserved;
} FUSERenameEventParams;

#define EID_FUSE_RENAME 19

virtual INT CBFSCONNECT_CALL FireRename(LPWSTR &lpszOldPath, LPWSTR &lpszNewPath, INT &iFlags, INT &iResult);

class FUSERenameEventParams {
public:
  const QString &OldPath();

  const QString &NewPath();

  int Flags();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireRename(FUSERenameEventParams *e) {...}

Remarks

This event fires when the OS wants to rename or move the specified file or directory from OldPath to NewPath, both of which are fully qualified and located in the virtual filesystem. The Flags parameter currently is not used.

To handle this event properly, applications must perform any actions needed to rename or move the specified file or directory in their backend storage, overwriting the destination file if necessary. An application may also, for its own reasons, decide not to overwrite a destination file, in which case it must deny the operation by returning an appropriate error code via ResultCode.

Windows:

This event fires only if a file or directory with the specified NewPath does not exist; or if such a file does exist, and an overwrite was requested. Cases in which a file with the specified NewPath exists, and an overwrite was not requested, are handled by the class internally. Note: Windows only allows files to be overwritten, and denies a rename or move request automatically if the destination is an existing directory.

Any handles to the file being renamed are closed before the rename operation and are reopened after the operation. If the rename operation fails, then the file handles are reopened using the old name. If any of the reopen operations fail, the reopening process is stopped, and any handles that already have been reopened are closed again.

The value returned by the application in the ResultCode parameter is passed back to the system.

RmDir Event (FUSE Class)

This event fires when the OS wants to remove (delete) a directory.

Syntax

ANSI (Cross Platform)
virtual int FireRmDir(FUSERmDirEventParams *e);

typedef struct {
  const char *Path;
  int Result;
  int reserved;
} FUSERmDirEventParams;


Unicode (Windows)
virtual INT FireRmDir(FUSERmDirEventParams *e);

typedef struct {
  LPCWSTR Path;
  INT Result;
  INT reserved;
} FUSERmDirEventParams;

#define EID_FUSE_RMDIR 20

virtual INT CBFSCONNECT_CALL FireRmDir(LPWSTR &lpszPath, INT &iResult);

class FUSERmDirEventParams {
public:
  const QString &Path();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireRmDir(FUSERmDirEventParams *e) {...}

Remarks

This event fires when the OS has decided to delete the directory specified by Path.

Windows:

The resulting error value is ignored because of the OS design.

StatFS Event (FUSE Class)

This event fires when the OS needs information about the virtual drive's capacity and free space.

Syntax

ANSI (Cross Platform)
virtual int FireStatFS(FUSEStatFSEventParams *e);

typedef struct {
  const char *Path;
  int64 *pBlockSize;
  int64 *pTotalBlocks;
  int64 *pFreeBlocks;
  int64 *pFreeBlocksAvail;
  int64 *pTotalFiles;
  int64 *pFreeFiles;
  int MaxFilenameLength;
  int Result;
  int reserved;
} FUSEStatFSEventParams;


Unicode (Windows)
virtual INT FireStatFS(FUSEStatFSEventParams *e);

typedef struct {
  LPCWSTR Path;
  LONG64 *pBlockSize;
  LONG64 *pTotalBlocks;
  LONG64 *pFreeBlocks;
  LONG64 *pFreeBlocksAvail;
  LONG64 *pTotalFiles;
  LONG64 *pFreeFiles;
  INT MaxFilenameLength;
  INT Result;
  INT reserved;
} FUSEStatFSEventParams;

#define EID_FUSE_STATFS 21

virtual INT CBFSCONNECT_CALL FireStatFS(LPWSTR &lpszPath, LONG64 &lBlockSize, LONG64 &lTotalBlocks, LONG64 &lFreeBlocks, LONG64 &lFreeBlocksAvail, LONG64 &lTotalFiles, LONG64 &lFreeFiles, INT &iMaxFilenameLength, INT &iResult);

class FUSEStatFSEventParams {
public:
  const QString &Path();

  qint64 BlockSize();
  void SetBlockSize(qint64 lBlockSize);

  qint64 TotalBlocks();
  void SetTotalBlocks(qint64 lTotalBlocks);

  qint64 FreeBlocks();
  void SetFreeBlocks(qint64 lFreeBlocks);

  qint64 FreeBlocksAvail();
  void SetFreeBlocksAvail(qint64 lFreeBlocksAvail);

  qint64 TotalFiles();
  void SetTotalFiles(qint64 lTotalFiles);

  qint64 FreeFiles();
  void SetFreeFiles(qint64 lFreeFiles);

  int MaxFilenameLength();
  void SetMaxFilenameLength(int iMaxFilenameLength);

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireStatFS(FUSEStatFSEventParams *e) {...}

Remarks

This event fires anytime the OS needs to retrieve the virtual drive's total storage capacity and free space. This event is mandatory to handle. Without it, the OS will not be able to initialize the drive.

To handle this event properly, applications must set event parameters accordingly. BlockSize must be set to the size of the block, and TotalBlocks must be set to the total number of blocks on the virtual drive. FreeBlocks and FreeBlocksAvail denote the number of free blocks available to the system and to the unprivileged user, respectively.

Windows:

The minimum drive size accepted by Windows is 6144 bytes. However, the class adjusts the minimum size to be at least 49152 bytes to ensure compatibility with possible changes in future Windows updates.

Linux:

TotalFiles and FreeFiles must be set to the total and available number of file slots (inodes) available within a filesystem. MaxFilenameLength should be set to the maximal length of the filename (path component) supported by the filesystem.

Truncate Event (FUSE Class)

This event fires when the OS needs to truncate (set the size of) a file.

Syntax

ANSI (Cross Platform)
virtual int FireTruncate(FUSETruncateEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int64 Size;
  int Result;
  int reserved;
} FUSETruncateEventParams;


Unicode (Windows)
virtual INT FireTruncate(FUSETruncateEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  LONG64 Size;
  INT Result;
  INT reserved;
} FUSETruncateEventParams;

#define EID_FUSE_TRUNCATE 22

virtual INT CBFSCONNECT_CALL FireTruncate(LPWSTR &lpszPath, LPVOID &lpFileContext, LONG64 &lSize, INT &iResult);

class FUSETruncateEventParams {
public:
  const QString &Path();

  void *FileContext();

  qint64 Size();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireTruncate(FUSETruncateEventParams *e) {...}

Remarks

This event fires when the OS wants to set the size of the file, which is identified by either Path or FileContext.

Note: On non-Windows systems, FileContext may be 0 even for a file that is opened at the moment when the event fires.

The Size parameter contains the new file size. If the new size is larger than the old size, the added space is expected to be filled with null bytes ('\0').

Unlink Event (FUSE Class)

This event fires when the OS wants to unlink (delete) a file.

Syntax

ANSI (Cross Platform)
virtual int FireUnlink(FUSEUnlinkEventParams *e);

typedef struct {
  const char *Path;
  int Result;
  int reserved;
} FUSEUnlinkEventParams;


Unicode (Windows)
virtual INT FireUnlink(FUSEUnlinkEventParams *e);

typedef struct {
  LPCWSTR Path;
  INT Result;
  INT reserved;
} FUSEUnlinkEventParams;

#define EID_FUSE_UNLINK 23

virtual INT CBFSCONNECT_CALL FireUnlink(LPWSTR &lpszPath, INT &iResult);

class FUSEUnlinkEventParams {
public:
  const QString &Path();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireUnlink(FUSEUnlinkEventParams *e) {...}

Remarks

This event fires when the OS has decided to delete the file specified by Path.

Windows:

The resulting error value is ignored because of the OS design.

Utimens Event (FUSE Class)

This event fires when the OS needs to change access and modification times of a file.

Syntax

ANSI (Cross Platform)
virtual int FireUtimens(FUSEUtimensEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int64 ATime;
  int64 MTime;
  int Result;
  int reserved;
} FUSEUtimensEventParams;


Unicode (Windows)
virtual INT FireUtimens(FUSEUtimensEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  LONG64 ATime;
  LONG64 MTime;
  INT Result;
  INT reserved;
} FUSEUtimensEventParams;

#define EID_FUSE_UTIMENS 24

virtual INT CBFSCONNECT_CALL FireUtimens(LPWSTR &lpszPath, LPVOID &lpFileContext, LONG64 &lATime, LONG64 &lMTime, INT &iResult);

class FUSEUtimensEventParams {
public:
  const QString &Path();

  void *FileContext();

  const QDateTime &ATime();

  const QDateTime &MTime();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireUtimens(FUSEUtimensEventParams *e) {...}

Remarks

This event fires when the OS needs to change access and modification times of the file, which is identified by either Path or FileContext. The ATime and MTime parameters contain the access time and modification time, respectively. All date/time parameters in the class are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC (Windows) or as a number of seconds since Jan 1, 1970 00:00:00 UTC (Linux)

To convert the values of the ATime and MTime parameters to Unix time, use the FileTimeToUnixTime method.

The ATimeNS and MTimeNS parameters contain the subsecond part of the ATime and MTime date/time value, respectively, counted in nanoseconds.

Write Event (FUSE Class)

This event fires when the OS needs to write data to an open file.

Syntax

ANSI (Cross Platform)
virtual int FireWrite(FUSEWriteEventParams *e);

typedef struct {
  const char *Path;
  void *FileContext;
  int WritePage;
  int64 Offset;
  const void *Buffer;
  int64 Size;
  int Result;
  int reserved;
} FUSEWriteEventParams;


Unicode (Windows)
virtual INT FireWrite(FUSEWriteEventParams *e);

typedef struct {
  LPCWSTR Path;
  LPVOID FileContext;
  BOOL WritePage;
  LONG64 Offset;
  LPCVOID Buffer;
  LONG64 Size;
  INT Result;
  INT reserved;
} FUSEWriteEventParams;

#define EID_FUSE_WRITE 25

virtual INT CBFSCONNECT_CALL FireWrite(LPWSTR &lpszPath, LPVOID &lpFileContext, BOOL &bWritePage, LONG64 &lOffset, LPVOID &lpBuffer, LONG64 &lSize, INT &iResult);

class FUSEWriteEventParams {
public:
  const QString &Path();

  void *FileContext();

  bool WritePage();

  qint64 Offset();

  const void *Buffer();

  qint64 Size();

  int Result();
  void SetResult(int iResult);

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

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

// Or, subclass FUSE and override this emitter function.
virtual int FireWrite(FUSEWriteEventParams *e) {...}

Remarks

This event fires when the OS needs to write data to the already-open file, which is identified by either Path or FileContext.

To handle this event properly, applications should write Size bytes of data from the memory region pointed to by Buffer to the specified file. Writing must begin at the specified Offset in the file and all of the provided data are expected to be written.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The WritePage parameter will be set to a nonzero value when writing is performed by the cache manager or another system component. If this is the case, FileContext may not match the value that would be passed in the case of a nonbuffered write by a user-mode process.

When writing is complete, applications must set Result to the actual number of bytes written to the file.

Config Settings (FUSE Class)

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

FUSE Config Settings

AsyncMountingPointNotifications: Whether system broadcasts for virtual drive mounting and unmounting are sent asynchronously.

This Windows-only configuration setting specifies whether the WM_DEVICECHANGE broadcast is sent asynchronously (true) or synchronously (false) when the virtual drive is mounted or unmounted using the Mount and Unmount methods, respectively.

By default, this setting is enabled, and the broadcast is sent asynchronously. Typically, this is sufficient, but applications may disable this setting during unmounting if they find that Windows Explorer is still presenting virtual drives as available after they have been deleted (which may occur if the application exits immediately after unmounting a virtual drive).

On Linux, this setting is not used.

LinuxFUSEParams: A placeholder for additional parameters used for fine-tuning FUSE on Linux.

The string that the application passes is parsed, and for each argument, the fuse_opt_add_arg() function of FUSE is called. Arguments must start with "-" (dash); multiple arguments must be separated with a space.

Example: "-oallow_other -omax_read=4096" (without quotes).

MaxWorkerThreadCount: The maximum number of worker threads to use to fire events.

(CBFS and FUSE classes on Windows only) This setting specifies the maximum number of worker threads the class may create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (If other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: 4 * number_of_processors.

MetadataCacheEnabled: Whether or not the metadata cache should be used.

This Windows-only configuration setting specifies whether the file metadata cache is enabled for a virtual drive.

By default, this setting is enabled, and the class caches file information and uses the cached metadata to serve operating system requests, thus reducing how often the GetAttr 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.

Disable this setting if your filesystem contents may be modified on the backend side, and the modifications need to be re-read when the OS refreshes its knowledge about directory contents.

On Linux, this setting is not used.

MinWorkerThreadCount: The minimum number of worker threads to use to fire events.

(CBFS and FUSE classes on Windows only) This setting specifies the minimum number of worker threads the class should create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (In other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: max(number_of_processors, 4). If this setting's value exceeds the MaxWorkerThreadCount value, the latter is used instead.

NonExistentFilesCacheEnabled: Whether or not the nonexistent files cache should be used.

This Windows-only configuration setting specifies whether the nonexistent files cache is enabled for a virtual drive.

By default, this setting is enabled, and the class will cache any GetAttr 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 GetAttr event again.

Disable this setting if your filesystem contents may be modified on the backend side, and the modifications need to be re-read when the OS refreshes its knowledge about directory contents.

On Linux, this setting is not used.

Timeout: Specifies how many milliseconds the driver will wait for events to execute before cancelling the underlying OS requests. (Windows-only).

Because the FUSE class's events typically are tied directly to requests from the OS itself, it is critical that event handlers complete quickly to prevent the system from being blocked. To prevent such blocking, the CBFS Connect system driver can enforce request timeouts on a per-virtual-drive basis.

When timeout enforcement is in effect, and an event executes long enough for its timeout to expire, the driver cancels the underlying request by reporting an error to the OS. The tardy event still runs to completion, but any results it returns once finished are ignored because the underlying request has already been handled.

Applications should always strive to ensure that all event handlers complete quickly, even if request timeouts are disabled. Do not perform time-consuming work, especially network operations, within event handlers; offload such work to background threads.

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 the Config method to fail with an ERROR_IMPLEMENTATION_LIMIT (1292, 0x50C) error code.) The default value is 30,000 or 30 seconds.

TranslateDOSCharsInEnumMasks: Whether the DOS wildcard characters should be translated during search.

In addition to * and ?, Windows uses special wildcard characters for compatibility with DOS applications and short (8.3) names. These characters are <, >, and " . Their meanings are described in MSDN and .NET reference source code as follows:

DOS_STAR (<) - Matches zero or more characters until encountering and matching the final dot (.) in the name. (Source code comment: "DOS_STAR matches any character except . zero or more times.")
DOS_QM (>) - Matches any single character or, upon encountering a period or end of name string, advances the expression to the end of the set of contiguous DOS_QMs. (Source code comment: "A DOS_DOT can match either a period, or zero characters beyond the end of name.")
DOS_DOT (") - Matches either a period or zero characters beyond the name string. (Source code comment: "DOS_QM is the most complicated. If the name is finished, we can match zero characters. If this name is a '.', we don't match, but look at the next expression. Otherwise, we match a single character.")

When this setting is enabled (default), the class translates them to * and ?, but such a translation is not able to fully represent all the logic behind DOS_* wildcard characters; however, this translation is usually sufficient for end-user needs.

If your application needs to perform exact matching, disable this setting and implement handling of DOS_* wildcard characters in your application. Further explanation about the characters can be found in the MSDN article. The RtlIsNameInExpression function of Windows API may be used to perform such a matching. Note: as the explanation states, "When you do a case-insensitive search and don't provide a translation table, the name is converted to uppercase."

In FUSE on Linux, this setting is not used.

WorkerInitialStackSize: The initial stack size to create worker threads with.

(CBFS and FUSE classes on Windows only) This setting specifies the initial size of the stack each worker thread is created with. The system rounds this value to the nearest page.

By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).

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

Base Config Settings

BuildInfo: Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo: Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

Product: The product the license is for.
Product Key: The key the license was generated from.
License Source: Where the license was found (e.g., RuntimeLicense, License File).
License Type: The type of license installed (e.g., Royalty Free, Single Server).

Trappable Errors (FUSE Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

The class uses Unix/Linux system error codes during operation, as necessary. Please refer to the Error Reporting and Handling topic for more information.