Struct cbfsconnect::FUSE

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

cbfsconnect::FUSE

Remarks

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

Getting Started

Each FUSE struct instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the FUSE struct if their use-case requires the creation of multiple virtual drives; the struct'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 struct. This must be done each time the application starts (if the application is using multiple FUSE struct 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 on_open, on_read, on_get_attr, and on_read_dir, 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.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintainted by CBFSConnect. Due to this, the FUSE struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of FUSE when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

access_denied_process_count Property (FUSE Struct)

The number of records in the AccessDeniedProcess arrays.

Syntax

fn access_denied_process_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• access_denied_process_desired_access
• access_denied_process_id
• access_denied_process_include_children
• access_denied_process_name

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

This property is read-only.

Data Type

i32

access_denied_process_desired_access Property (FUSE Struct)

The kind of access granted or denied.

Syntax

fn access_denied_process_desired_access(&self , AccessDeniedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The kind of access granted or denied.

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

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

This property is read-only.

Data Type

i32

access_denied_process_include_children Property (FUSE Struct)

Whether child processes are affected.

Syntax

fn access_denied_process_include_children(&self , AccessDeniedProcessIndex : i32) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

Whether child processes are affected.

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

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

This property is read-only.

Data Type

bool

access_denied_process_id Property (FUSE Struct)

The Id of the target process.

Syntax

fn access_denied_process_id(&self , AccessDeniedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The Id of the target process.

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

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

This property is read-only.

Data Type

i32

access_denied_process_name Property (FUSE Struct)

The filename of the target process's executable.

Syntax

fn access_denied_process_name(&self , AccessDeniedProcessIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

The filename of the target process's executable.

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

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

This property is read-only.

Data Type

String

access_granted_process_count Property (FUSE Struct)

The number of records in the AccessGrantedProcess arrays.

Syntax

fn access_granted_process_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• access_granted_process_desired_access
• access_granted_process_id
• access_granted_process_include_children
• access_granted_process_name

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

This property is read-only.

Data Type

i32

access_granted_process_desired_access Property (FUSE Struct)

The kind of access granted or denied.

Syntax

fn access_granted_process_desired_access(&self , AccessGrantedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The kind of access granted or denied.

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

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

This property is read-only.

Data Type

i32

access_granted_process_include_children Property (FUSE Struct)

Whether child processes are affected.

Syntax

fn access_granted_process_include_children(&self , AccessGrantedProcessIndex : i32) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

Whether child processes are affected.

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

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

This property is read-only.

Data Type

bool

access_granted_process_id Property (FUSE Struct)

The Id of the target process.

Syntax

fn access_granted_process_id(&self , AccessGrantedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The Id of the target process.

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

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

This property is read-only.

Data Type

i32

access_granted_process_name Property (FUSE Struct)

The filename of the target process's executable.

Syntax

fn access_granted_process_name(&self , AccessGrantedProcessIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

The filename of the target process's executable.

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

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

This property is read-only.

Data Type

String

process_restrictions_enabled Property (FUSE Struct)

Whether process access restrictions are enabled.

Syntax

fn process_restrictions_enabled(&self ) -> Result<bool, CBFSConnectError> 
fn set_process_restrictions_enabled(&self, value : bool) ->  Option<CBFSConnectError> 

Default Value

false

Remarks

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

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

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

Note: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

Data Type

bool

serialize_events Property (FUSE Struct)

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

Syntax

fn serialize_events(&self ) -> Result<i32, CBFSConnectError> 
fn set_serialize_events(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

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

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

i32

storage_characteristics Property (FUSE Struct)

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

Syntax

fn storage_characteristics(&self ) -> Result<i32, CBFSConnectError> 
fn set_storage_characteristics(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

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.

Data Type

i32

tag Property (FUSE Struct)

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

Syntax

fn tag(&self ) -> Result<i64, CBFSConnectError> 
fn set_tag(&self, value : i64) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

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

Data Type

i64

add_denied_process Method (FUSE Struct)

Adds a rule that prevents a process from accessing the virtual drive (Windows only).

Syntax

fn add_denied_process(&self, process_file_name : &String, process_id : i32, child_processes : bool, desired_access : i32) -> Option<CBFSConnectError>

Remarks

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

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

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

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

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

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

add_granted_process Method (FUSE Struct)

Adds a rule that allows a process to access the virtual drive (Windows only).

Syntax

fn add_granted_process(&self, process_file_name : &String, process_id : i32, child_processes : bool, desired_access : i32) -> Option<CBFSConnectError>

Remarks

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

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

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

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

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

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

config Method (FUSE Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &String) ->  Result<String, CBFSConnectError>

Remarks

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

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

file_time_to_nanoseconds Method (FUSE Struct)

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

Syntax

fn file_time_to_nanoseconds(&self, file_time : &chrono::DateTime<Utc>) ->  Result<i32, CBFSConnectError>

Remarks

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

file_time_to_unix_time Method (FUSE Struct)

This method converts FileTime to the Unix time format.

Syntax

fn file_time_to_unix_time(&self, file_time : &chrono::DateTime<Utc>) ->  Result<i64, CBFSConnectError>

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 file_time_to_nanoseconds method.

fill_dir Method (FUSE Struct)

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

Syntax

fn fill_dir(&self, filler_context : i64, name : &String, ino : i64, mode : i32, uid : i32, gid : i32, link_count : i32, size : i64, a_time : &chrono::DateTime<Utc>, m_time : &chrono::DateTime<Utc>, c_time : &chrono::DateTime<Utc>) ->  Result<i32, CBFSConnectError>

Remarks

Use the FillDir method from the on_read_dir 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 on_read_dir 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 struct are specified .

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

Windows:

Any nonapplicable time values can be set to .

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

Note: This method cannot be called within events.

get_driver_status Method (FUSE Struct)

This method retrieves the status of the system driver.

Syntax

fn get_driver_status(&self, product_guid : &String) ->  Result<i32, CBFSConnectError>

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
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

This method is available in both the struct 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.

get_driver_version Method (FUSE Struct)

This method retrieves the version of the system driver.

Syntax

fn get_driver_version(&self, product_guid : &String) ->  Result<i64, CBFSConnectError>

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
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

This method is available in both the struct 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.

get_gid Method (FUSE Struct)

This method returns the group Id of the caller process.

Syntax

fn get_gid(&self) ->  Result<i32, CBFSConnectError>

Remarks

Windows:

This method currently is not used.

Linux:

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

get_originator_process_id Method (FUSE Struct)

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

Syntax

fn get_originator_process_id(&self) ->  Result<i32, CBFSConnectError>

Remarks

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

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

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

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

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

Please refer to the Contexts topic for more information on how to use events' context parameters.

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

get_originator_process_name Method (FUSE Struct)

Retrieves the name of the process that initiated the operation (Windows only).

Syntax

fn get_originator_process_name(&self) ->  Result<String, CBFSConnectError>

Remarks

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

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

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

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

Please refer to the Contexts topic for more information on how to use events' context parameters.

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

get_originator_thread_id Method (FUSE Struct)

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

Syntax

fn get_originator_thread_id(&self) ->  Result<i32, CBFSConnectError>

Remarks

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

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

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

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

Please refer to the Contexts topic for more information on how to use events' context parameters.

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

get_originator_token Method (FUSE Struct)

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

Syntax

fn get_originator_token(&self) ->  Result<i64, CBFSConnectError>

Remarks

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

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

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

Network Access Notes

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

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

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

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

Please refer to the Contexts topic for more information on how to use events' context parameters.

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

get_uid Method (FUSE Struct)

The method returns the user Id of the caller process.

Syntax

fn get_uid(&self) ->  Result<i32, CBFSConnectError>

Remarks

Windows:

This method currently is not used.

Linux:

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

initialize Method (FUSE Struct)

This method initializes the struct.

Syntax

fn initialize(&self, product_guid : &String) -> Option<CBFSConnectError>

Remarks

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

install Method (FUSE Struct)

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

Syntax

fn install(&self, cab_file_name : &String, product_guid : &String, path_to_install : &String, flags : i32) ->  Result<i32, CBFSConnectError>

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
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• 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 struct 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 () error.

Note: This method cannot be called within events.

Linux:

This method currently is not used.

mount Method (FUSE Struct)

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

Syntax

fn mount(&self, mount_point : &String) -> Option<CBFSConnectError>

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.

remove_denied_process Method (FUSE Struct)

Removes a rule that prevents a process from accessing the virtual drive (Windows only).

Syntax

fn remove_denied_process(&self, process_file_name : &String, process_id : i32) -> Option<CBFSConnectError>

Remarks

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

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

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

remove_granted_process Method (FUSE Struct)

Removes a rule that allows a process to access the virtual drive (Windows only).

Syntax

fn remove_granted_process(&self, process_file_name : &String, process_id : i32) -> Option<CBFSConnectError>

Remarks

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

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

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

uninstall Method (FUSE Struct)

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

Syntax

fn uninstall(&self, cab_file_name : &String, product_guid : &String, installed_path : &String, flags : i32) ->  Result<i32, CBFSConnectError>

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

Note: This method cannot be called within events.

unix_time_to_file_time Method (FUSE Struct)

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

Syntax

fn unix_time_to_file_time(&self, unix_time : i64, nanoseconds : i32) ->  Result<chrono::DateTime<Utc>, CBFSConnectError>

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

This method unmounts a filesystem.

Syntax

fn unmount(&self) -> Option<CBFSConnectError>

Remarks

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

on_access Event (FUSE Struct)

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

Syntax

// FUSEAccessEventArgs carries the FUSE Access event's parameters.
pub struct FUSEAccessEventArgs {
  fn path(&self) -> &String
  fn mask(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEAccessEvent defines the signature of the FUSE Access event's handler function.
pub trait FUSEAccessEvent {
  fn on_access(&self, sender : FUSE, e : &mut FUSEAccessEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_access(&self) -> &'a dyn FUSEAccessEvent;
  pub fn set_on_access(&mut self, value : &'a dyn FUSEAccessEvent);
  ...
}

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

on_chmod Event (FUSE Struct)

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

Syntax

// FUSEChmodEventArgs carries the FUSE Chmod event's parameters.
pub struct FUSEChmodEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn mode(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEChmodEvent defines the signature of the FUSE Chmod event's handler function.
pub trait FUSEChmodEvent {
  fn on_chmod(&self, sender : FUSE, e : &mut FUSEChmodEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_chmod(&self) -> &'a dyn FUSEChmodEvent;
  pub fn set_on_chmod(&mut self, value : &'a dyn FUSEChmodEvent);
  ...
}

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

on_chown Event (FUSE Struct)

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

Syntax

// FUSEChownEventArgs carries the FUSE Chown event's parameters.
pub struct FUSEChownEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn uid(&self) -> i32
  fn gid(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEChownEvent defines the signature of the FUSE Chown event's handler function.
pub trait FUSEChownEvent {
  fn on_chown(&self, sender : FUSE, e : &mut FUSEChownEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_chown(&self) -> &'a dyn FUSEChownEvent;
  pub fn set_on_chown(&mut self, value : &'a dyn FUSEChownEvent);
  ...
}

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

on_copy_file_range Event (FUSE Struct)

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

Syntax

// FUSECopyFileRangeEventArgs carries the FUSE CopyFileRange event's parameters.
pub struct FUSECopyFileRangeEventArgs {
  fn path_in(&self) -> &String
  fn file_context_in(&self) -> usize
  fn offset_in(&self) -> i64
  fn path_out(&self) -> &String
  fn file_context_out(&self) -> usize
  fn offset_out(&self) -> i64
  fn size(&self) -> i64
  fn flags(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSECopyFileRangeEvent defines the signature of the FUSE CopyFileRange event's handler function.
pub trait FUSECopyFileRangeEvent {
  fn on_copy_file_range(&self, sender : FUSE, e : &mut FUSECopyFileRangeEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_copy_file_range(&self) -> &'a dyn FUSECopyFileRangeEvent;
  pub fn set_on_copy_file_range(&mut self, value : &'a dyn FUSECopyFileRangeEvent);
  ...
}

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

on_create Event (FUSE Struct)

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

Syntax

// FUSECreateEventArgs carries the FUSE Create event's parameters.
pub struct FUSECreateEventArgs {
  fn path(&self) -> &String
  fn mode(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSECreateEvent defines the signature of the FUSE Create event's handler function.
pub trait FUSECreateEvent {
  fn on_create(&self, sender : FUSE, e : &mut FUSECreateEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_create(&self) -> &'a dyn FUSECreateEvent;
  pub fn set_on_create(&mut self, value : &'a dyn FUSECreateEvent);
  ...
}

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

on_destroy Event (FUSE Struct)

This event fires upon filesystem exit.

Syntax

// FUSEDestroyEventArgs carries the FUSE Destroy event's parameters.
pub struct FUSEDestroyEventArgs {
}

// FUSEDestroyEvent defines the signature of the FUSE Destroy event's handler function.
pub trait FUSEDestroyEvent {
  fn on_destroy(&self, sender : FUSE, e : &mut FUSEDestroyEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_destroy(&self) -> &'a dyn FUSEDestroyEvent;
  pub fn set_on_destroy(&mut self, value : &'a dyn FUSEDestroyEvent);
  ...
}

Remarks

This event fires when the filesystem is shut down.

on_error Event (FUSE Struct)

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

Syntax

// FUSEErrorEventArgs carries the FUSE Error event's parameters.
pub struct FUSEErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// FUSEErrorEvent defines the signature of the FUSE Error event's handler function.
pub trait FUSEErrorEvent {
  fn on_error(&self, sender : FUSE, e : &mut FUSEErrorEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_error(&self) -> &'a dyn FUSEErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn FUSEErrorEvent);
  ...
}

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.

on_f_allocate Event (FUSE Struct)

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

Syntax

// FUSEFAllocateEventArgs carries the FUSE FAllocate event's parameters.
pub struct FUSEFAllocateEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn mode(&self) -> i32
  fn offset(&self) -> i64
  fn length(&self) -> i64
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEFAllocateEvent defines the signature of the FUSE FAllocate event's handler function.
pub trait FUSEFAllocateEvent {
  fn on_f_allocate(&self, sender : FUSE, e : &mut FUSEFAllocateEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_f_allocate(&self) -> &'a dyn FUSEFAllocateEvent;
  pub fn set_on_f_allocate(&mut self, value : &'a dyn FUSEFAllocateEvent);
  ...
}

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

on_flush Event (FUSE Struct)

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

Syntax

// FUSEFlushEventArgs carries the FUSE Flush event's parameters.
pub struct FUSEFlushEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEFlushEvent defines the signature of the FUSE Flush event's handler function.
pub trait FUSEFlushEvent {
  fn on_flush(&self, sender : FUSE, e : &mut FUSEFlushEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_flush(&self) -> &'a dyn FUSEFlushEvent;
  pub fn set_on_flush(&mut self, value : &'a dyn FUSEFlushEvent);
  ...
}

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

on_f_sync Event (FUSE Struct)

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

Syntax

// FUSEFSyncEventArgs carries the FUSE FSync event's parameters.
pub struct FUSEFSyncEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn data_sync(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEFSyncEvent defines the signature of the FUSE FSync event's handler function.
pub trait FUSEFSyncEvent {
  fn on_f_sync(&self, sender : FUSE, e : &mut FUSEFSyncEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_f_sync(&self) -> &'a dyn FUSEFSyncEvent;
  pub fn set_on_f_sync(&mut self, value : &'a dyn FUSEFSyncEvent);
  ...
}

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

on_get_attr Event (FUSE Struct)

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

Syntax

// FUSEGetAttrEventArgs carries the FUSE GetAttr event's parameters.
pub struct FUSEGetAttrEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn ino(&self) -> i64
  fn set_ino(&self, value : i64)
  fn mode(&self) -> i32
  fn set_mode(&self, value : i32)
  fn uid(&self) -> i32
  fn set_uid(&self, value : i32)
  fn gid(&self) -> i32
  fn set_gid(&self, value : i32)
  fn link_count(&self) -> i32
  fn set_link_count(&self, value : i32)
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn a_time(&self) -> &chrono::DateTime<Utc>
  fn set_a_time(&self, value : chrono::DateTime<Utc>)
  fn set_a_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn m_time(&self) -> &chrono::DateTime<Utc>
  fn set_m_time(&self, value : chrono::DateTime<Utc>)
  fn set_m_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn c_time(&self) -> &chrono::DateTime<Utc>
  fn set_c_time(&self, value : chrono::DateTime<Utc>)
  fn set_c_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEGetAttrEvent defines the signature of the FUSE GetAttr event's handler function.
pub trait FUSEGetAttrEvent {
  fn on_get_attr(&self, sender : FUSE, e : &mut FUSEGetAttrEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_get_attr(&self) -> &'a dyn FUSEGetAttrEvent;
  pub fn set_on_get_attr(&mut self, value : &'a dyn FUSEGetAttrEvent);
  ...
}

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 struct are specified .

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

Windows:

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

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

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

on_init Event (FUSE Struct)

This event fires on filesystem startup.

Syntax

// FUSEInitEventArgs carries the FUSE Init event's parameters.
pub struct FUSEInitEventArgs {
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEInitEvent defines the signature of the FUSE Init event's handler function.
pub trait FUSEInitEvent {
  fn on_init(&self, sender : FUSE, e : &mut FUSEInitEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_init(&self) -> &'a dyn FUSEInitEvent;
  pub fn set_on_init(&mut self, value : &'a dyn FUSEInitEvent);
  ...
}

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

on_lock Event (FUSE Struct)

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

Syntax

// FUSELockEventArgs carries the FUSE Lock event's parameters.
pub struct FUSELockEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn lock_type(&self) -> i32
  fn lock_start(&self) -> i64
  fn lock_len(&self) -> i64
  fn cmd(&self) -> i32
  fn lock_owner(&self) -> i64
  fn lock_pid(&self) -> i32
  fn set_lock_pid(&self, value : i32)
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSELockEvent defines the signature of the FUSE Lock event's handler function.
pub trait FUSELockEvent {
  fn on_lock(&self, sender : FUSE, e : &mut FUSELockEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_lock(&self) -> &'a dyn FUSELockEvent;
  pub fn set_on_lock(&mut self, value : &'a dyn FUSELockEvent);
  ...
}

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

on_mk_dir Event (FUSE Struct)

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

Syntax

// FUSEMkDirEventArgs carries the FUSE MkDir event's parameters.
pub struct FUSEMkDirEventArgs {
  fn path(&self) -> &String
  fn mode(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEMkDirEvent defines the signature of the FUSE MkDir event's handler function.
pub trait FUSEMkDirEvent {
  fn on_mk_dir(&self, sender : FUSE, e : &mut FUSEMkDirEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_mk_dir(&self) -> &'a dyn FUSEMkDirEvent;
  pub fn set_on_mk_dir(&mut self, value : &'a dyn FUSEMkDirEvent);
  ...
}

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

on_open Event (FUSE Struct)

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

Syntax

// FUSEOpenEventArgs carries the FUSE Open event's parameters.
pub struct FUSEOpenEventArgs {
  fn path(&self) -> &String
  fn flags(&self) -> i32
  fn direct_io(&self) -> bool
  fn set_direct_io(&self, value : bool)
  fn keep_cache(&self) -> bool
  fn set_keep_cache(&self, value : bool)
  fn non_seekable(&self) -> bool
  fn set_non_seekable(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEOpenEvent defines the signature of the FUSE Open event's handler function.
pub trait FUSEOpenEvent {
  fn on_open(&self, sender : FUSE, e : &mut FUSEOpenEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_open(&self) -> &'a dyn FUSEOpenEvent;
  pub fn set_on_open(&mut self, value : &'a dyn FUSEOpenEvent);
  ...
}

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

on_read Event (FUSE Struct)

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

Syntax

// FUSEReadEventArgs carries the FUSE Read event's parameters.
pub struct FUSEReadEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn buffer(&self) -> *mut u8
  fn size(&self) -> i64
  fn offset(&self) -> i64
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEReadEvent defines the signature of the FUSE Read event's handler function.
pub trait FUSEReadEvent {
  fn on_read(&self, sender : FUSE, e : &mut FUSEReadEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_read(&self) -> &'a dyn FUSEReadEvent;
  pub fn set_on_read(&mut self, value : &'a dyn FUSEReadEvent);
  ...
}

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

on_read_dir Event (FUSE Struct)

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

Syntax

// FUSEReadDirEventArgs carries the FUSE ReadDir event's parameters.
pub struct FUSEReadDirEventArgs {
  fn path(&self) -> &String
  fn filler_context(&self) -> i64
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEReadDirEvent defines the signature of the FUSE ReadDir event's handler function.
pub trait FUSEReadDirEvent {
  fn on_read_dir(&self, sender : FUSE, e : &mut FUSEReadDirEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_read_dir(&self) -> &'a dyn FUSEReadDirEvent;
  pub fn set_on_read_dir(&mut self, value : &'a dyn FUSEReadDirEvent);
  ...
}

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 fill_dir method and pass the FillerContextparameter as well as the information about the directory entry. Please refer to the description of fill_dir for further details.

If fill_dir 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 Handling topic for more information.

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

on_release Event (FUSE Struct)

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

Syntax

// FUSEReleaseEventArgs carries the FUSE Release event's parameters.
pub struct FUSEReleaseEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn flags(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEReleaseEvent defines the signature of the FUSE Release event's handler function.
pub trait FUSEReleaseEvent {
  fn on_release(&self, sender : FUSE, e : &mut FUSEReleaseEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_release(&self) -> &'a dyn FUSEReleaseEvent;
  pub fn set_on_release(&mut self, value : &'a dyn FUSEReleaseEvent);
  ...
}

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

on_rename Event (FUSE Struct)

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

Syntax

// FUSERenameEventArgs carries the FUSE Rename event's parameters.
pub struct FUSERenameEventArgs {
  fn old_path(&self) -> &String
  fn new_path(&self) -> &String
  fn flags(&self) -> i32
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSERenameEvent defines the signature of the FUSE Rename event's handler function.
pub trait FUSERenameEvent {
  fn on_rename(&self, sender : FUSE, e : &mut FUSERenameEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_rename(&self) -> &'a dyn FUSERenameEvent;
  pub fn set_on_rename(&mut self, value : &'a dyn FUSERenameEvent);
  ...
}

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

on_rm_dir Event (FUSE Struct)

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

Syntax

// FUSERmDirEventArgs carries the FUSE RmDir event's parameters.
pub struct FUSERmDirEventArgs {
  fn path(&self) -> &String
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSERmDirEvent defines the signature of the FUSE RmDir event's handler function.
pub trait FUSERmDirEvent {
  fn on_rm_dir(&self, sender : FUSE, e : &mut FUSERmDirEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_rm_dir(&self) -> &'a dyn FUSERmDirEvent;
  pub fn set_on_rm_dir(&mut self, value : &'a dyn FUSERmDirEvent);
  ...
}

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

Windows:

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

on_stat_fs Event (FUSE Struct)

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

Syntax

// FUSEStatFSEventArgs carries the FUSE StatFS event's parameters.
pub struct FUSEStatFSEventArgs {
  fn path(&self) -> &String
  fn block_size(&self) -> i64
  fn set_block_size(&self, value : i64)
  fn total_blocks(&self) -> i64
  fn set_total_blocks(&self, value : i64)
  fn free_blocks(&self) -> i64
  fn set_free_blocks(&self, value : i64)
  fn free_blocks_avail(&self) -> i64
  fn set_free_blocks_avail(&self, value : i64)
  fn total_files(&self) -> i64
  fn set_total_files(&self, value : i64)
  fn free_files(&self) -> i64
  fn set_free_files(&self, value : i64)
  fn max_filename_length(&self) -> i32
  fn set_max_filename_length(&self, value : i32)
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEStatFSEvent defines the signature of the FUSE StatFS event's handler function.
pub trait FUSEStatFSEvent {
  fn on_stat_fs(&self, sender : FUSE, e : &mut FUSEStatFSEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_stat_fs(&self) -> &'a dyn FUSEStatFSEvent;
  pub fn set_on_stat_fs(&mut self, value : &'a dyn FUSEStatFSEvent);
  ...
}

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

on_truncate Event (FUSE Struct)

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

Syntax

// FUSETruncateEventArgs carries the FUSE Truncate event's parameters.
pub struct FUSETruncateEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn size(&self) -> i64
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSETruncateEvent defines the signature of the FUSE Truncate event's handler function.
pub trait FUSETruncateEvent {
  fn on_truncate(&self, sender : FUSE, e : &mut FUSETruncateEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_truncate(&self) -> &'a dyn FUSETruncateEvent;
  pub fn set_on_truncate(&mut self, value : &'a dyn FUSETruncateEvent);
  ...
}

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

on_unlink Event (FUSE Struct)

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

Syntax

// FUSEUnlinkEventArgs carries the FUSE Unlink event's parameters.
pub struct FUSEUnlinkEventArgs {
  fn path(&self) -> &String
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEUnlinkEvent defines the signature of the FUSE Unlink event's handler function.
pub trait FUSEUnlinkEvent {
  fn on_unlink(&self, sender : FUSE, e : &mut FUSEUnlinkEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_unlink(&self) -> &'a dyn FUSEUnlinkEvent;
  pub fn set_on_unlink(&mut self, value : &'a dyn FUSEUnlinkEvent);
  ...
}

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

Windows:

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

on_u_time Event (FUSE Struct)

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

Syntax

// FUSEUTimeEventArgs carries the FUSE UTime event's parameters.
pub struct FUSEUTimeEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn a_time(&self) -> &chrono::DateTime<Utc>
  fn m_time(&self) -> &chrono::DateTime<Utc>
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEUTimeEvent defines the signature of the FUSE UTime event's handler function.
pub trait FUSEUTimeEvent {
  fn on_u_time(&self, sender : FUSE, e : &mut FUSEUTimeEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_u_time(&self) -> &'a dyn FUSEUTimeEvent;
  pub fn set_on_u_time(&mut self, value : &'a dyn FUSEUTimeEvent);
  ...
}

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 struct are specified

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

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

on_write Event (FUSE Struct)

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

Syntax

// FUSEWriteEventArgs carries the FUSE Write event's parameters.
pub struct FUSEWriteEventArgs {
  fn path(&self) -> &String
  fn file_context(&self) -> usize
  fn write_page(&self) -> bool
  fn offset(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn size(&self) -> i64
  fn result(&self) -> i32
  fn set_result(&self, value : i32)
}

// FUSEWriteEvent defines the signature of the FUSE Write event's handler function.
pub trait FUSEWriteEvent {
  fn on_write(&self, sender : FUSE, e : &mut FUSEWriteEventArgs);
}

impl <'a> FUSE<'a> {
  pub fn on_write(&self) -> &'a dyn FUSEWriteEvent;
  pub fn set_on_write(&mut self, value : &'a dyn FUSEWriteEvent);
  ...
}

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

Config Settings (FUSE Struct)

The struct 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 struct, access to these internal properties is provided through the config method.

FUSE Config Settings

Base Config Settings

Trappable Errors (FUSE Struct)

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