Getting Started with the FUSE component

Introduction

The FUSE component consists of two parts: (1) a kernel mode system driver, and (2) a user mode API known as the FUSE component. On Linux, the FUSE driver included in the OS is used, while on Windows the driver is included with the product. The driver works at the system level behind the scenes; you do not interact with it directly. Instead, you integrate the FUSE component into your application, and then use it to create, delete, and manipulate a virtual drive. The FUSE component also provides events that your application must implement to actually handle various filesystem operations related to your virtual drive.

Contents

Install and Uninstall the Drivers (Windows)

On Windows, the FUSE system driver must be installed on a machine before the FUSE component can be used to create and manage virtual drives. This is done using the Install method, which is present in the FUSE component API, as well as in a standalone Installer dynamic library (.dll), included with the toolkit. The FUSE API method is useful when your application is responsible for installing the driver; the Installer dynamic library is designed to be used from installation scripts.

It may be necessary to reboot the system after calling Install to complete the driver installation process; the Install method will return a value that indicates whether or not this is necessary. Once the driver installation is complete, you will be able to use the FUSE component to create and manage virtual drives.

The driver needs to be installed only once. You do not need to install it each time you start your application. If the driver is not installed correctly, you will receive a "File not found" error when trying to use the FUSE component, which means that the driver could not be found or loaded.

To uninstall the system driver, call the Uninstall method; available in both the FUSE component API and the Installer dynamic library. This is not necessary when you install a new minor or major version of the driver.

Mount (Create) and Unmount (Delete) a Virtual Drive

Before doing anything else with the FUSE component, you must call its Initialize method. Once this is done, you will be able to create and mount a virtual drive.

In the FUSE component, both creation and mounting of the drive are done with a single Mount method. On Windows, you can create a visible drive by assigning a drive letter, or you can create an "invisible" drive by assigning a UNC path. Invisible drives are not shown in File Explorer or other file managers; but they can still be accessed by users and applications that know the correct UNC path to use. Alternatively, the virtual filesystem can be mounted as a folder on an existing NTFS drive. On Linux the mounting point is a path to an existing empty directory, into which the virtual filesystem will be "inserted".

At this point, the virtual filesystem will be available for users and other applications to use. For it to function correctly, your application must implement the FUSE component's various events, and handle the various filesystem operations. More information about how to do this is discussed in the following sections as well as in the product's documentation.

When you are finished with the virtual drive, call the Unmount method to remove the "virtual media" from the drive and delete the drive.

Handle the Events

Your application actually implements the functionality of the virtual filesystem with the FUSE component's event handlers. FUSE hides most of the complexities involved; the following sections discuss the primary considerations. Most of the events of the component must be handled for the filesystem to function properly. Please refer to the documentation for more specific information about each individual event.

Provide Information about the Filesystem

To provide information about the virtual filesystem's size and other parameters, your application needs to handle the StatFS event.

Provide Information about the Filesystem's Contents

An important operation for any filesystem is to provide information about its contents to the OS. When the OS needs to read the contents of some directory (starting from the root directory), it sends requests that are translated into the ReadDir event.

The ReadDir event is fired while the OS enumerates the contents of some directory. Each time your application handles the ReadDir event, it must call the Filler method for every entry (e.g., file, subdirectory, symlink) present in the specified directory and then pass all the information about this entry to the Filler method. Do this in a loop for all entries in the directory.

Directory enumeration is used to get a list of entries in the directory, but it is sometimes necessary for the OS to obtain information about a particular file or directory. Such requests are passed to your application through the GetAttr event. This event is similar to ReadDir and requests the same information; however, it also gives you the name of the file or directory of interest.

Create and Open Files

The FUSE component exposes several events related to creating files and directories: Create for files and MkDir for directories. To open an existing file, the Open event is used.

When your application handles these events, it usually obtains access to some resource (e.g., a file, a remote resource, a reference to a memory block). It is necessary to keep a handle to that resource stored somewhere so that it can be used to handle events that fire for subsequent file operations. To assist with this, FUSE provides the FileContext parameter that the application can use to store data related to a particular file. This handle is passed to any other events that fire for the file in question (e.g., read, write, resize, rename), allowing your application to handle them more efficiently. On Windows, this value is shared between handles to the same file, which are opened concurrently.

Close Files

After a file is read from or written to, it is closed by the OS. Closing does not necessarily happen as soon as the application that used the file calls the corresponding system API function. In some cases, various OS components keep the handle to the file open for some time.

The Release event is fired when the OS closes a file. This event includes the FileContext parameter and if your application stored a reference to some context object or structure, such context must be disposed of by your application in the event handler.

File Read/Write Operations

When the OS sends file read and write requests to the filesystem, the FUSE component's Read and Write events will fire. Both events include parameters that describe the offset into the file at which your application must begin reading/writing data and the data itself.

The Read and Write events also include the FileContext parameter described previously.

File Resize Requests

Changes in the file size are communicated through the Truncate event. This event also includes the FileContext parameter described previously.

Renaming and Deletion

Files and directories are deleted through Unlink and RmDir events respectively. Although most files contain just one link (main file name), if the file has several hard links, then only the link specified in the parameters of the Unlink must be removed, and the file must be deleted only when no more links are pointing to it.

File and directory renaming and moving are all atomic operations that must be handled through the Rename event.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@callback.com.