FUSE Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

callback.CBFSConnect.Fuse

Remarks

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

Getting Started

Each FUSE component instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the FUSE component if their use-case requires the creation of multiple virtual drives; the component'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 (dynamic link library). Please refer to the Driver Installation topic for more information.
2. Call the Initialize method to initialize the FUSE component. This must be done each time the application starts (if the application is using multiple FUSE component 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 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.
4. 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).
5. The application can unmount the "media" from the virtual drive using the Unmount method.
6. To uninstall the system driver, call the Uninstall method. This should not be done as part of the driver-upgrade process.
   • In production, the system driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List

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

Method List

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

Event List

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

Config Settings

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

SerializeEvents Property (FUSE Component)

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

Syntax

• C#
• VB.NET

public FuseSerializeEvents SerializeEvents { get; set; }

enum FuseSerializeEvents {
  seOnMultipleThreads,
  seOnOneWorkerThread
}

Public Property SerializeEvents As FuseSerializeEvents

Enum FuseSerializeEvents
  seOnMultipleThreads
  seOnOneWorkerThread
End Enum

Default Value

0

Remarks

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

Windows: in general, the component 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 component 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.

StorageCharacteristics Property (FUSE Component)

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

Syntax

• C#
• VB.NET

public int StorageCharacteristics { get; set; }

Public Property StorageCharacteristics As Integer

Default Value

16

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:

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

Tag Property (FUSE Component)

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

Syntax

• C#
• VB.NET

public long Tag { get; set; }

Public Property Tag As Long

Default Value

0

Remarks

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

Config Method (FUSE Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

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

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

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

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

FileTimeToNanoseconds Method (FUSE Component)

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

Syntax

• C#
• VB.NET

public int FileTimeToNanoseconds(DateTime fileTime);

Public Function FileTimeToNanoseconds(ByVal FileTime As DateTime) As Integer

Remarks

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

FileTimeToUnixTime Method (FUSE Component)

This method converts FileTime to the Unix time format.

Syntax

• C#
• VB.NET

public long FileTimeToUnixTime(DateTime fileTime);

Public Function FileTimeToUnixTime(ByVal FileTime As DateTime) As Long

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.

FillDir Method (FUSE Component)

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

Syntax

• C#
• VB.NET

public int FillDir(long fillerContext, string name, long ino, int mode, int uid, int gid, int linkCount, long size, DateTime ATime, DateTime MTime, DateTime CTime);

Public Function FillDir(ByVal FillerContext As Long, ByVal Name As String, ByVal Ino As Long, ByVal Mode As Integer, ByVal Uid As Integer, ByVal Gid As Integer, ByVal LinkCount As Integer, ByVal Size As Long, ByVal ATime As DateTime, ByVal MTime As DateTime, ByVal CTime As DateTime) As Integer

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 component are specified in UTC.

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

Windows:

Any nonapplicable time values can be set to January 1, 1601 00:00:00 UTC.

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

Note: This method cannot be called within events.

GetDriverStatus Method (FUSE Component)

This method retrieves the status of the system driver.

Syntax

• C#
• VB.NET

public int GetDriverStatus(string productGUID);

Public Function GetDriverStatus(ByVal ProductGUID As String) As Integer

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:

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

Note: This method cannot be called within events.

Linux:

This method currently is not used.

GetDriverVersion Method (FUSE Component)

This method retrieves the version of the system driver.

Syntax

• C#
• VB.NET

public long GetDriverVersion(string productGUID);

Public Function GetDriverVersion(ByVal ProductGUID As String) As Long

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.

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

Note: This method cannot be called within events.

GetGid Method (FUSE Component)

This method returns the group Id of the caller process.

Syntax

• C#
• VB.NET

public int GetGid();

Public Function GetGid() As Integer

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.

GetUid Method (FUSE Component)

The method returns the user Id of the caller process.

Syntax

• C#
• VB.NET

public int GetUid();

Public Function GetUid() As Integer

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.

Initialize Method (FUSE Component)

This method initializes the component.

Syntax

• C#
• VB.NET

public void Initialize(string productGUID);

Public Sub Initialize(ByVal ProductGUID As String)

Remarks

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

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

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

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

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

If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, Initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the Install method is required before the component can be used.

Install Method (FUSE Component)

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

Syntax

• C#
• VB.NET

public int Install(string cabFileName, string productGUID, string pathToInstall, int flags);

Public Function Install(ByVal CabFileName As String, ByVal ProductGUID As String, ByVal PathToInstall As String, ByVal Flags As Integer) As Integer

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.

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 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:

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

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

Note: This method cannot be called within events.

Linux:

This method currently is not used.

Mount Method (FUSE Component)

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

Syntax

• C#
• VB.NET

public void Mount(string mountPoint);

Public Sub Mount(ByVal MountPoint As String)

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.

Uninstall Method (FUSE Component)

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

Syntax

• C#
• VB.NET

public int Uninstall(string cabFileName, string productGUID, string installedPath, int flags);

Public Function Uninstall(ByVal CabFileName As String, ByVal ProductGUID As String, ByVal InstalledPath As String, ByVal Flags As Integer) As Integer

Remarks

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

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

Please refer to the Driver Installation topic for more information.

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

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

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

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

Note: This method cannot be called within events.

UnixTimeToFileTime Method (FUSE Component)

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

Syntax

• C#
• VB.NET

public DateTime UnixTimeToFileTime(long unixTime, int nanoseconds);

Public Function UnixTimeToFileTime(ByVal UnixTime As Long, ByVal Nanoseconds As Integer) As DateTime

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.

Unmount Method (FUSE Component)

This method unmounts a filesystem.

Syntax

• C#
• VB.NET

public void Unmount();

Public Sub 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 component uses a dedicated thread. If there exist open handles to items in a mounting point, FUSE doesn't finish its operations, while the component waits for FUSE to finish. The component can forcefully stop FUSE operations, but only in the application that uses the component didn't set a handler for the SIGINT signal. If such a handler is set, the component 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 component 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.

Access Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnAccessHandler OnAccess;

public delegate void OnAccessHandler(object sender, FuseAccessEventArgs e);

public class FuseAccessEventArgs : EventArgs {
  public string Path { get; }
  public int Mask { get; }
  public int Result { get; set; }
}

Public Event OnAccess As OnAccessHandler

Public Delegate Sub OnAccessHandler(sender As Object, e As FuseAccessEventArgs)

Public Class FuseAccessEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property Mask As Integer
  Public Property Result As Integer
End Class

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

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

Syntax

• C#
• VB.NET

public event OnChmodHandler OnChmod;

public delegate void OnChmodHandler(object sender, FuseChmodEventArgs e);

public class FuseChmodEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int Mode { get; }
  public int Result { get; set; }
}

Public Event OnChmod As OnChmodHandler

Public Delegate Sub OnChmodHandler(sender As Object, e As FuseChmodEventArgs)

Public Class FuseChmodEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property Mode As Integer
  Public Property Result As Integer
End Class

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

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

Syntax

• C#
• VB.NET

public event OnChownHandler OnChown;

public delegate void OnChownHandler(object sender, FuseChownEventArgs e);

public class FuseChownEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int Uid { get; }
  public int Gid { get; }
  public int Result { get; set; }
}

Public Event OnChown As OnChownHandler

Public Delegate Sub OnChownHandler(sender As Object, e As FuseChownEventArgs)

Public Class FuseChownEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property Uid As Integer
  Public ReadOnly Property Gid As Integer
  Public Property Result As Integer
End Class

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.

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.

CopyFileRange Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnCopyFileRangeHandler OnCopyFileRange;

public delegate void OnCopyFileRangeHandler(object sender, FuseCopyFileRangeEventArgs e);

public class FuseCopyFileRangeEventArgs : EventArgs {
  public string PathIn { get; }
  public IntPtr FileContextIn { get; }
  public long OffsetIn { get; }
  public string PathOut { get; }
  public IntPtr FileContextOut { get; }
  public long OffsetOut { get; }
  public long Size { get; }
  public int Flags { get; }
  public int Result { get; set; }
}

Public Event OnCopyFileRange As OnCopyFileRangeHandler

Public Delegate Sub OnCopyFileRangeHandler(sender As Object, e As FuseCopyFileRangeEventArgs)

Public Class FuseCopyFileRangeEventArgs Inherits EventArgs
  Public ReadOnly Property PathIn As String
  Public ReadOnly Property FileContextIn As IntPtr
  Public ReadOnly Property OffsetIn As Long
  Public ReadOnly Property PathOut As String
  Public ReadOnly Property FileContextOut As IntPtr
  Public ReadOnly Property OffsetOut As Long
  Public ReadOnly Property Size As Long
  Public ReadOnly Property Flags As Integer
  Public Property Result As Integer
End Class

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.

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.

Create Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnCreateHandler OnCreate;

public delegate void OnCreateHandler(object sender, FuseCreateEventArgs e);

public class FuseCreateEventArgs : EventArgs {
  public string Path { get; }
  public int Mode { get; }
  public IntPtr FileContext { get; set; }
  public int Result { get; set; }
}

Public Event OnCreate As OnCreateHandler

Public Delegate Sub OnCreateHandler(sender As Object, e As FuseCreateEventArgs)

Public Class FuseCreateEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property Mode As Integer
  Public Property FileContext As IntPtr
  Public Property Result As Integer
End Class

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.

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.

Destroy Event (FUSE Component)

This event fires upon filesystem exit.

Syntax

• C#
• VB.NET

public event OnDestroyHandler OnDestroy;

public delegate void OnDestroyHandler(object sender, FuseDestroyEventArgs e);

public class FuseDestroyEventArgs : EventArgs {
}

Public Event OnDestroy As OnDestroyHandler

Public Delegate Sub OnDestroyHandler(sender As Object, e As FuseDestroyEventArgs)

Public Class FuseDestroyEventArgs Inherits EventArgs
End Class

Remarks

This event fires when the filesystem is shut down.

Error Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, FuseErrorEventArgs e);

public class FuseErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As FuseErrorEventArgs)

Public Class FuseErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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

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

Syntax

• C#
• VB.NET

public event OnFAllocateHandler OnFAllocate;

public delegate void OnFAllocateHandler(object sender, FuseFAllocateEventArgs e);

public class FuseFAllocateEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int Mode { get; }
  public long Offset { get; }
  public long Length { get; }
  public int Result { get; set; }
}

Public Event OnFAllocate As OnFAllocateHandler

Public Delegate Sub OnFAllocateHandler(sender As Object, e As FuseFAllocateEventArgs)

Public Class FuseFAllocateEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property Mode As Integer
  Public ReadOnly Property Offset As Long
  Public ReadOnly Property Length As Long
  Public Property Result As Integer
End Class

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

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.

Flush Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnFlushHandler OnFlush;

public delegate void OnFlushHandler(object sender, FuseFlushEventArgs e);

public class FuseFlushEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int Result { get; set; }
}

Public Event OnFlush As OnFlushHandler

Public Delegate Sub OnFlushHandler(sender As Object, e As FuseFlushEventArgs)

Public Class FuseFlushEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public Property Result As Integer
End Class

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.

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.

FSync Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnFSyncHandler OnFSync;

public delegate void OnFSyncHandler(object sender, FuseFSyncEventArgs e);

public class FuseFSyncEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int DataSync { get; }
  public int Result { get; set; }
}

Public Event OnFSync As OnFSyncHandler

Public Delegate Sub OnFSyncHandler(sender As Object, e As FuseFSyncEventArgs)

Public Class FuseFSyncEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property DataSync As Integer
  Public Property Result As Integer
End Class

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.

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.

GetAttr Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnGetAttrHandler OnGetAttr;

public delegate void OnGetAttrHandler(object sender, FuseGetAttrEventArgs e);

public class FuseGetAttrEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public long Ino { get; set; }
  public int Mode { get; set; }
  public int Uid { get; set; }
  public int Gid { get; set; }
  public int LinkCount { get; set; }
  public long Size { get; set; }
  public DateTime ATime { get; set; }
  public DateTime MTime { get; set; }
  public DateTime CTime { get; set; }
  public int Result { get; set; }
}

Public Event OnGetAttr As OnGetAttrHandler

Public Delegate Sub OnGetAttrHandler(sender As Object, e As FuseGetAttrEventArgs)

Public Class FuseGetAttrEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public Property Ino As Long
  Public Property Mode As Integer
  Public Property Uid As Integer
  Public Property Gid As Integer
  Public Property LinkCount As Integer
  Public Property Size As Long
  Public Property ATime As DateTime
  Public Property MTime As DateTime
  Public Property CTime As DateTime
  Public Property Result As Integer
End Class

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.

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 component are specified in UTC.

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 January 1, 1601 00:00:00 UTC.

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.

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

Init Event (FUSE Component)

This event fires on filesystem startup.

Syntax

• C#
• VB.NET

public event OnInitHandler OnInit;

public delegate void OnInitHandler(object sender, FuseInitEventArgs e);

public class FuseInitEventArgs : EventArgs {
  public int Result { get; set; }
}

Public Event OnInit As OnInitHandler

Public Delegate Sub OnInitHandler(sender As Object, e As FuseInitEventArgs)

Public Class FuseInitEventArgs Inherits EventArgs
  Public Property Result As Integer
End Class

Remarks

This event fires when the filesystem is started.

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.

Lock Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnLockHandler OnLock;

public delegate void OnLockHandler(object sender, FuseLockEventArgs e);

public class FuseLockEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int LockType { get; }
  public long LockStart { get; }
  public long LockLen { get; }
  public int Cmd { get; }
  public long LockOwner { get; }
  public int LockPid { get; set; }
  public int Result { get; set; }
}

Public Event OnLock As OnLockHandler

Public Delegate Sub OnLockHandler(sender As Object, e As FuseLockEventArgs)

Public Class FuseLockEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property LockType As Integer
  Public ReadOnly Property LockStart As Long
  Public ReadOnly Property LockLen As Long
  Public ReadOnly Property Cmd As Integer
  Public ReadOnly Property LockOwner As Long
  Public Property LockPid As Integer
  Public Property Result As Integer
End Class

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:

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

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.

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.

MkDir Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnMkDirHandler OnMkDir;

public delegate void OnMkDirHandler(object sender, FuseMkDirEventArgs e);

public class FuseMkDirEventArgs : EventArgs {
  public string Path { get; }
  public int Mode { get; }
  public int Result { get; set; }
}

Public Event OnMkDir As OnMkDirHandler

Public Delegate Sub OnMkDirHandler(sender As Object, e As FuseMkDirEventArgs)

Public Class FuseMkDirEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property Mode As Integer
  Public Property Result As Integer
End Class

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.

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.

Open Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnOpenHandler OnOpen;

public delegate void OnOpenHandler(object sender, FuseOpenEventArgs e);

public class FuseOpenEventArgs : EventArgs {
  public string Path { get; }
  public int Flags { get; }
  public bool DirectIO { get; set; }
  public bool KeepCache { get; set; }
  public bool NonSeekable { get; set; }
  public IntPtr FileContext { get; set; }
  public int Result { get; set; }
}

Public Event OnOpen As OnOpenHandler

Public Delegate Sub OnOpenHandler(sender As Object, e As FuseOpenEventArgs)

Public Class FuseOpenEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property Flags As Integer
  Public Property DirectIO As Boolean
  Public Property KeepCache As Boolean
  Public Property NonSeekable As Boolean
  Public Property FileContext As IntPtr
  Public Property Result As Integer
End Class

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.

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.

Read Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnReadHandler OnRead;

public delegate void OnReadHandler(object sender, FuseReadEventArgs e);

public class FuseReadEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public IntPtr Buffer { get; }
  public long Size { get; }
  public long Offset { get; }
  public int Result { get; set; }
}

Public Event OnRead As OnReadHandler

Public Delegate Sub OnReadHandler(sender As Object, e As FuseReadEventArgs)

Public Class FuseReadEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property Buffer As IntPtr
  Public ReadOnly Property Size As Long
  Public ReadOnly Property Offset As Long
  Public Property Result As Integer
End Class

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.

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.

ReadDir Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnReadDirHandler OnReadDir;

public delegate void OnReadDirHandler(object sender, FuseReadDirEventArgs e);

public class FuseReadDirEventArgs : EventArgs {
  public string Path { get; }
  public long FillerContext { get; }
  public int Result { get; set; }
}

Public Event OnReadDir As OnReadDirHandler

Public Delegate Sub OnReadDirHandler(sender As Object, e As FuseReadDirEventArgs)

Public Class FuseReadDirEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FillerContext As Long
  Public Property Result As Integer
End Class

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.

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.

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

Release Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnReleaseHandler OnRelease;

public delegate void OnReleaseHandler(object sender, FuseReleaseEventArgs e);

public class FuseReleaseEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public int Flags { get; }
  public int Result { get; set; }
}

Public Event OnRelease As OnReleaseHandler

Public Delegate Sub OnReleaseHandler(sender As Object, e As FuseReleaseEventArgs)

Public Class FuseReleaseEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property Flags As Integer
  Public Property Result As Integer
End Class

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.

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.

Rename Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnRenameHandler OnRename;

public delegate void OnRenameHandler(object sender, FuseRenameEventArgs e);

public class FuseRenameEventArgs : EventArgs {
  public string OldPath { get; }
  public string NewPath { get; }
  public int Flags { get; }
  public int Result { get; set; }
}

Public Event OnRename As OnRenameHandler

Public Delegate Sub OnRenameHandler(sender As Object, e As FuseRenameEventArgs)

Public Class FuseRenameEventArgs Inherits EventArgs
  Public ReadOnly Property OldPath As String
  Public ReadOnly Property NewPath As String
  Public ReadOnly Property Flags As Integer
  Public Property Result As Integer
End Class

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

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.

RmDir Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnRmDirHandler OnRmDir;

public delegate void OnRmDirHandler(object sender, FuseRmDirEventArgs e);

public class FuseRmDirEventArgs : EventArgs {
  public string Path { get; }
  public int Result { get; set; }
}

Public Event OnRmDir As OnRmDirHandler

Public Delegate Sub OnRmDirHandler(sender As Object, e As FuseRmDirEventArgs)

Public Class FuseRmDirEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public Property Result As Integer
End Class

Remarks

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

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.

Windows:

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

StatFS Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnStatFSHandler OnStatFS;

public delegate void OnStatFSHandler(object sender, FuseStatFSEventArgs e);

public class FuseStatFSEventArgs : EventArgs {
  public string Path { get; }
  public long BlockSize { get; set; }
  public long TotalBlocks { get; set; }
  public long FreeBlocks { get; set; }
  public long FreeBlocksAvail { get; set; }
  public long TotalFiles { get; set; }
  public long FreeFiles { get; set; }
  public int MaxFilenameLength { get; set; }
  public int Result { get; set; }
}

Public Event OnStatFS As OnStatFSHandler

Public Delegate Sub OnStatFSHandler(sender As Object, e As FuseStatFSEventArgs)

Public Class FuseStatFSEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public Property BlockSize As Long
  Public Property TotalBlocks As Long
  Public Property FreeBlocks As Long
  Public Property FreeBlocksAvail As Long
  Public Property TotalFiles As Long
  Public Property FreeFiles As Long
  Public Property MaxFilenameLength As Integer
  Public Property Result As Integer
End Class

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

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.

Truncate Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnTruncateHandler OnTruncate;

public delegate void OnTruncateHandler(object sender, FuseTruncateEventArgs e);

public class FuseTruncateEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public long Size { get; }
  public int Result { get; set; }
}

Public Event OnTruncate As OnTruncateHandler

Public Delegate Sub OnTruncateHandler(sender As Object, e As FuseTruncateEventArgs)

Public Class FuseTruncateEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property Size As Long
  Public Property Result As Integer
End Class

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

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.

Unlink Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnUnlinkHandler OnUnlink;

public delegate void OnUnlinkHandler(object sender, FuseUnlinkEventArgs e);

public class FuseUnlinkEventArgs : EventArgs {
  public string Path { get; }
  public int Result { get; set; }
}

Public Event OnUnlink As OnUnlinkHandler

Public Delegate Sub OnUnlinkHandler(sender As Object, e As FuseUnlinkEventArgs)

Public Class FuseUnlinkEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public Property Result As Integer
End Class

Remarks

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

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.

Windows:

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

Utimens Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnUtimensHandler OnUtimens;

public delegate void OnUtimensHandler(object sender, FuseUtimensEventArgs e);

public class FuseUtimensEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public DateTime ATime { get; }
  public DateTime MTime { get; }
  public int Result { get; set; }
}

Public Event OnUtimens As OnUtimensHandler

Public Delegate Sub OnUtimensHandler(sender As Object, e As FuseUtimensEventArgs)

Public Class FuseUtimensEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property ATime As DateTime
  Public ReadOnly Property MTime As DateTime
  Public Property Result As Integer
End Class

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 component are specified in UTC

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.

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.

Write Event (FUSE Component)

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

Syntax

• C#
• VB.NET

public event OnWriteHandler OnWrite;

public delegate void OnWriteHandler(object sender, FuseWriteEventArgs e);

public class FuseWriteEventArgs : EventArgs {
  public string Path { get; }
  public IntPtr FileContext { get; }
  public bool WritePage { get; }
  public long Offset { get; }
  public IntPtr Buffer { get; }
  public long Size { get; }
  public int Result { get; set; }
}

Public Event OnWrite As OnWriteHandler

Public Delegate Sub OnWriteHandler(sender As Object, e As FuseWriteEventArgs)

Public Class FuseWriteEventArgs Inherits EventArgs
  Public ReadOnly Property Path As String
  Public ReadOnly Property FileContext As IntPtr
  Public ReadOnly Property WritePage As Boolean
  Public ReadOnly Property Offset As Long
  Public ReadOnly Property Buffer As IntPtr
  Public ReadOnly Property Size As Long
  Public Property Result As Integer
End Class

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.

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.

Config Settings (FUSE Component)

FUSE Config Settings

Base Config Settings

Trappable Errors (FUSE Component)