Dokan Doxygen

This is the homepage of the Doxygen generated documentation for Dokany.

We recommend you take a look at our wiki for an introduction of how to use the library. You may find mirror samples using Dokan API or Fuse API here useful.

How to create file systems

Dokan operations

To create a file system, an application needs to implement functions in the DOKAN_OPERATIONS structure (declared in dokan.h). Once implemented, the DokanMain function can be invoked with DOKAN_OPERATIONS as a parameter in order to mount the file system. The semantics of functions in DOKAN_OPERATIONS are similar to corresponding Windows APIs with the same name. The parameters for these functions are therefore the same as for their counterpart Windows APIs. These functions are called from many threads so they need to be thread-safe, otherwise many problems may occur.

These functions are typically invoked in this sequence:

1. DOKAN_OPERATIONS::ZwCreateFile
2. Other functions (like DOKAN_OPERATIONS.ReadFile or DOKAN_OPERATIONS.WriteFile)
3. DOKAN_OPERATIONS::Cleanup
4. DOKAN_OPERATIONS::CloseFile

Before file access operations (listing directory entries, reading file attributes, etc.), DOKAN_OPERATIONS.ZwCreateFile is always invoked. On the other hand, the function DOKAN_OPERATIONS.Cleanup always gets called by the Dokan file system driver when the file is closed by the CloseHandle Windows API.

Each function should return STATUS_SUCCESS when the operation succeeds, otherwise if an error occurs, return the proper NTSTATUS (https://support.microsoft.com/en-us/kb/113996). For example, when ZwCreateFile can't open a file (Win32 error ERROR_FILE_NOT_FOUND), it should return STATUS_OBJECT_NAME_NOT_FOUND. Dokan has an exported helper that can be used to convert Win32 Error to NTSTATUS with DokanNtStatusFromWin32.

There is a case with DOKAN_OPERATIONS.ZwCreateFile that should return STATUS_OBJECT_NAME_COLLISION instead of STATUS_SUCCESS when the param CreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS and the file requested successfully opened already existed.

Note: when applications make use of memory mapped files, WriteFile or ReadFile functions may be invoked after Cleanup in order to complete the I/O operations. The file system application should also properly work in this case.

Dokan File Info Life Time

The last parameter of each DOKAN_OPERATIONS functions is a DOKAN_FILE_INFO struct. Each file handle from user mode is associated with a DOKAN_FILE_INFO struct. Hence, the content of the struct does not change if the same file handle is used. The struct is created when the file is opened by CreateFile system call and destroyed when the file is closed by CloseHandle system call. It stores all file information on the current operation.

DOKAN_FILE_INFO.Context is an arbitrary value assigned by the file system application. File system applications can freely use this variable to store values that are constant in a file access session (the period from CreateFile to CloseFile), such as file handle, etc.

When the DOKAN_FILE_INFO.IsDirectory is set to TRUE, the file under the operation is a directory. When it is FALSE, the file system application programmers are required to set the variable to TRUE if the current operation acts on a directory. If the value is FALSE and the current operation is not acting on a directory, the programmers should not change the variable. Note that setting the variable to TRUE when a directory is accessed is very important for the Dokan library. If it is not set correctly, the library does not know the operation is acting on a directory and many problems may occur.

DOKAN_OPERATIONS.Cleanup is invoked when the function CloseHandle in the Windows API is executed. If the file system application stored a file handle in the Context variable when the function DOKAN_OPERATIONS.ZwCreateFile is invoked, this should be closed in the Cleanup function, not in CloseFile function. If the user application calls CloseHandle and subsequently opens the same file, the CloseFile function of the file system application may not be invoked before the CreateFile API is called and therefore may cause a sharing violation error since the HANDLE has not been closed.

Find Files

DOKAN_OPERATIONS.FindFiles or DOKAN_OPERATIONS.FindFilesWithPattern are called in order to respond to directory listing requests. One of the two functions should be implemented.

For each directory entry, file system applications should call the function FillFindData (passed as a function pointer to FindFiles, FindFilesWithPattern) with the WIN32_FIND_DATAW structure filled with directory information: FillFindData( &win32FindDataw, DokanFileInfo ). It is the responsibility of file systems to process wildcard patterns because shells in Windows are not designed to work properly with pattern matching. When file system applications only implement FindFiles, the wildcard patterns are automatically processed by the Dokan library. Wildcard matching can be controlled by implementing DOKAN_OPERATIONS.FindFilesWithPattern function. The function DokanIsNameInExpression exported can be used to process wildcard matching.

Mounting

As stated above, the file system can be mounted by invoking DokanMain function or DokanCreateFileSystem. The function DokanMain blocks until the file system is unmounted while DokanCreateFileSystem only blocks until the file system is mounted. File system applications should fill DOKAN_OPTIONS struct to describe the future device and DOKAN_OPERATIONS with function pointers for file system operations (such as ZwCreateFile, ReadFile, CloseFile, ...) before passing these parameters to one of the functions. Functions in DOKAN_OPERATIONS struct need to be thread-safe, because they are called in several threads (unless the DOKAN_OPTIONS::SingleThread is used) with different execution contexts.

DokanMain can instantly return a DokanMainResult status in case of mount failure. DokanCreateFileSystem will provide a DOKAN_HANDLE that can be used with DokanWaitForFileSystemClosed to wait until the filesystem is unmount or with DokanIsFileSystemRunning to check if the filesystem is still running. DokanCloseHandle will trigger an unmount and wait for it to be completed.

DOKAN_OPTIONS::Options with DOKAN_OPTION flags describe the behavior of the device.

Unmounting

A file system can be unmounted by calling the function DokanUnmount or DokanRemoveMountPoint. In most cases when the programs or shells using the file system hang, the unmount operation will solve the problem by bringing the system to a previous state when the file system was not mounted.

Users can use the command line to unmount file system like this:

dokanctl.exe /u DriveLetter

Network Provider

If mounting is done with DOKAN_OPTION_NETWORK, Dokan Network Provider must be used to ensure correct functionality. The files dokan2.dll & dokannp2.dll must be copied to WINDIR%\system32 and the provider can be registered on a system with dokanctl.exe /i n command.

Without this Network Provider, Windows Explorer will not properly handle virtual drives mounted as network shares and drives could appear disconnected.

If Network Redirector is setup using a UNC Name, Dokan Network Provider will assign a UNC Name to the drive label automatically.

Testing a File System

File systems can be tested using different tools. Microsoft has their own tools like Runkarr, IFSTest or Device Fundamentals.

There is also WinFSTest. Dokany is automatically running it on the sample mirror at every commit with appveyor.

For C# developers, there is DokanNet.Tests made by viciousviper that currently only test C# Mirror sample but can easily be changed to test a C# Dokan FS.

Misc

If there are bugs in the Dokan library or file system applications which use the library, the Windows blue screen will occur. Therefore, it is strongly recommended to use a Virtual Machine when developing file system applications.