Dokan official documentation

Dokan Library
Copyright (c) Hiroki Asakawa http://dokan-dev.net/en

What is the Dokan library
=====================================================================
When you want to create a new file system under Windows, for example, to improve FAT or NTFS, you need to develop a file system driver. Developing a device driver in kernel mode is a very tricky issue. By using the Dokan library, you can easily create a file system that belongs to you without having to write a device driver. Dokan Library is very acacia rain fuse (file system under Linux users), but works in a Windows environment.

License Statement
===================================================================
The Dokan library includes the LGPL (loose GPL license statement, which indicates that open source code can be used for non-open source proprietary programs, the translator notes), the MIT Licensing Program (and LGPL somewhat similar, editor's note)

-User Mode library (dokan.dll) LGPL
-Drive (Dokan.sys) LGPL
-Control Program (Dokanctl.exe) MIT
-Mount Service (Mounter.exe) MIT
-Sample program (MIRROR.C) MIT

For further details, please review the license file.
LGPL License.lgpl.txt
GPL License.gpl.txt
MIT License.mit.txt

You can get the source code through the following URL Http://dokan-dev.net/en/download

Environment
====================================================================
The Dokan library runs in Windowx xp,2003,vista,2008,7 x86 and Windows 2003,vista,2008,7 x64.

How does it work?
====================================================================
The Dokan library includes a user-state DLL (Dokan.dll) and a kernel-mode file system driver (Dokan.sys). Once the Dokan file system driver is installed, you can create the same file system as the normal file system you can see under Windows. This application, which we call file system level, can use the Dokan library to create file systems.
User-state program file operation requests (such as creating files, reading files, writing files ...) ) will be sent to the Windows I/O subsystem (running in the kernel state), followed by the Dokan file system driver (Dokan.sys).
By using the functions provided by the Dokan User-State Library (Dokan.dll), the file system program can register the callback function into the file system driver.
The file system driver will call these callback routines (routines) in order to be able to respond to requests it receives. The result of the callback routine is sent back to the user-state program.
For example, when the Windows browser requests that a directory be opened, the Opendirectory request is sent to the Dokan file system driver and the driver invokes the Opendirectory callback function provided by the file system program. The results of this routine will be sent to the Windows browser as a response to the opendirectory request. Therefore, the Dokan file system driver plays a role based on a proxy between the user program and the file system program.
The advantage of this approach is that it allows developers to develop file systems in a user state, which is safe and easy to debug.

Component and installation of the library
=======================================================================
When we run the Setup program, it installs the Dokan file system driver (Dokan.sys), registers the Dokan Mount Service (Mounter.exe), and a series of libraries. The detailed list of installed files is as follows:

System Folder/dokan.dll Dokan User State Library
System Folder/drivers/dokan.sys Dokan mount Service
ProgramFiles folder/dokan/dokanlibrary/mounter.exe Dokan mount Service
ProgramFiles folder/dokan/dokanlibrary/dokanctl.exe Dokan control Program
ProgramFiles folder/dokan/dokanlibrary/dokan.lib Dokan import Library
ProgramFiles folder \dokan\dokanlibrary\dokan.h Dokan Library header file
ProgramFiles folder \dokan\dokanlibrary\readme.txt This file (which you are reading, the translator notes)

You can use the Add/remove program in the Control Panel to uninstall Dokan. After uninstalling, you need to restart your computer.

How to create your file system
======================================================================
To create a file system, an application needs to implement functions in the dokan_operations structure (declared in dokan.h). Once the function is implemented, you can call the Dokanmain function as a dokan_operrations parameter.
In order to mount the file system, the function semantics and windowsapi semantics in dokan_operations are similar and have the same name. The parameters of these functions are the same as the corresponding WINDOWSAPI. These functions are called by many threads, so they need to ensure thread safety, or many problems may arise.

These functions are typically called in the following order:
1. Create file Creatfile (open file)
2. Other functions
3, clear cleanup
4. Close File CloseFile

File access operation (show directory, read file properties ...) Before, you often need to call the file creation function (Open directory, create file ...) ）。 On the other hand, when the CloseFile Windows API closes the file, the Dokan file system driver calls the Purge function cleanup. When the operation completes successfully, each function should return 0, otherwise a negative number is returned to indicate the error code. The error code is the opposite of the Windows system error code. For example, when Creatfile cannot open a file, you should return -2 ( -1*error_file_not_found).

The last parameter of each function is a DOKAN_FILE_INFO structure:
typedef struct _DOKAN_FILE_INFO {

ULONG64 Context;
ULONG64 Dokancontext;
ULONG ProcessId;
BOOL isdirectory;

} dokan_file_info, *pdokan_file_info;

The

file handle for each user state is related to the dokan_file_info structure. Therefore, if the same file handle is already in use, the structure content will not change. The DOKAN_FILE_INFO structure is created when the Creatfile system calls to open the file, and the structure is destroyed when the CloseFile system calls to close the file.
Each member of this structure has the following meanings:
Context: A specified value that is specified by the file system application. File system programs are free to use this variable to store fixed values in the file access phase (from creating files to closing files) such as file handles and so on.
Dokancontext: Reserved, used by the Dokan library.
ProcessId: The process ID of the open file process.
Isdirectory: Determines whether the open file is a directory.

The others are as follows
Int (*createfile) (
LPCWSTR,//filename, file name
DWORD,//desiredaccess, requires access
DWORD,//ShareMode, Shared mode
DWORD,//creationdisposition, creating intent
DWORD,//Flagsandattributes, Identity and attributes
Pdokan_file_info);

Int (*opendirectory) (
LPCWSTR,//FileName
Pdokan_file_info);

Int (*createdirectory) (
LPCWSTR,//FileName
Pdokan_file_info);

When the variable isdirectory is set to True, the action file is the directory. When isdirectory false, if the current operation is a directory operation, the programmer writing the file system program needs to set it to true. If the value of Isdirectory is false, but the current operation is not a directory operation, the programmer does not need to notconsistent the value. It is important to note that when accessing a directory, setting the value of Isdirectory to true is critical for the Dokan library. If it is not correctly set, then the Dokan library will not know that this operation is working on the directory, which can cause a lot of problems. If Creationdisposition is set to Create_always or Open_always and the current file already exists, then the Creatfile function needs to return error_aleady_exists (183)

Int (*cleanup) (
LPCWSTR,//FileName
Pdokan_file_info);

Int (*closefile) (
LPCWSTR,//FileName
Pdokan_file_info);

When the CloseHandle function provided by the Windows API is executed, the cleanup function is called. When the function CreateFile is called, if the file system program holds the file handle in the context variable, this will be closed in the cleanup function instead of the CloseFile function.
If the user program calls CloseHandle and opens the same file immediately, the file system program CloseFile function may not be called until the Creatfile API is called. This may cause a sharing issue.

It is important to note that when a user uses a memory-mapped file, the WriteFile or ReadFile function may be called after cleanup, in order to complete the I/O operation. File system applications should also work properly in this case.

Int (*findfiles) (
LPCWSTR,//PathName, path name
Pfillfinddata,//when calling this function, use Pwin32_find_dataw as the parameter
Pdokan_file_info); (see Pfillfinddata definition)

  //You should implement FindFiles or Findfileswithpattern
   int (*findfileswithpattern) (
        lpcwstr,          //PathName, Path name
       lpcwstr,           //Searchpattern, enquiry Method
       pfillfinddata,    //Call This function with Pwin32_find_dataw
       pdokan_file_info);

Call the FindFiles or Findfileswithpattern function for the corresponding directory list request. You should implement FindFiles or Findfileswithpattern (one of them, the translator's note). For each directory entry (entry), the file system program should call the Fillfinddata function (as a function parameter for findfiles, Findfileswithpattern call), Fillfinddata uses the WIN32_FIND_DATAW structure that contains directory information:
Fillfinddata (&win32finddataw, Dokanfileinfo).
Handling wildcard patterns (wildcard patterns) is the responsibility of the file system because the Windows command Terminal (shells) does not handle pattern matching well. When the file system program provides findfiles, the wildcard pattern is automatically processed through the Dokan library. You can control the process of wildcard matching by implementing a Findfileswithpattern function. The Dokan Library (Dokan.dll) provides a dokanisnameinexpression function interface that can be used to handle wildcard matches.

Mount
====================================================================
#define Dokan_option_debug        1//Output debug information
   #define dokan_option_stderr       2//output debug information to standard error output
   #define dokan_option_alt_stream  4//Use alternate STREAM
   #define dokan_option_keep_alive  8//Use auto-uninstall
   #define dokan_option_network     16//Using the network driver
                               // You need to install Dokan network provider (provider)
   #define dokan_option_removable  32//Use removable drive

   typedef struct _DOKAN_OPTIONS {
       ushort  version; / /supported version of Dokan, for example. "530" (Dokan ver 0.5.3)
       ulong   threadcount; //number of threads used
       ulong   options; //combination of dokan_options_*
        ULONG64 globalcontext; //FileSystem can use this
        LPCWSTR mountpoint; //mount point "m:\" (drive character) or
                            //"C:\mount\dokan" (path name in NTFS)
   } dokan_options, *pdokan_options;

int Dokanapi Dokanmain (
Pdokan_options Dokanoptions,
Pdokan_operations dokanoperations);

As mentioned above, the file system can be mounted via the Dokanmain function. The function blocks until the file system unloads. Before passing these parameters to the Dokanmain function, the file system program should fill the Dokan runtime with the options in full dokanoptions and fill in the function pointers in full dokanoperations for the file system operation (for example, CreateFile, ReadFile, CloseHandle, ... ）。 The functions in the dokanoperations structure need to be thread-safe, because they are all multithreaded calls (not threads that call Dokanmain) that perform different contexts (contexts).

The Dokan options are as follows:
Version: The version number of the Dokan library. You need a supported version. Dokan libraries may change some behavior (behavior) because of different version numbers. such as ie.530 (Dokan 0.5.3)
Number of threads: the number of threads inside the Dokan library. If this value is set to 0, the default value is used. When we debug the file system, the file system program should be set to avoid multi-threaded concurrency conflicts.
Options: Dokan_option_* constants.
Global domain: Your file system can use this variable to hold a specific structure attached to a mount.
Mount point: A mount point mount point "m:\" (drive character) or "C:\mount\dokan" (needs to be empty) path name in NTFS.

If the mount succeeds, the return value is dokan_success, otherwise the return value is as follows.
#define DOKAN_SUCCESS 0
#define DOKAN_ERROR-1/* Common error */
#define DOKAN_DRIVE_LETTER_ERROR-2/* Bad driver characters */
#define DOKAN_DRIVER_INSTALL_ERROR-3/* Cannot install driver */
#define DOKAN_START_ERROR-4/* Driver has a problem */
#define DOKAN_MOUNT_ERROR-5/* Cannot assign driver characters or mount points */
#define DOKAN_MOUNT_POINT_ERROR-6/* mount point is invalid */

Unloading
=======================================================================
The file system can be unloaded by calling the Dokanunmount function. In most cases, the program or shell uses a file system hang and uninstall operation to resolve the problem. Because when the file system is unloaded, we can restore the system to its original state.
Users may use Dokanctl to uninstall the file system:
> dokanctl.exe/u driveletter

Miscellaneous:
======================================================================
If there is a bug in the Dokan library or in the file system program that uses the library, your Windows system will be blue screen. Therefore, we strongly recommend that you use virtual machines to develop file system applications.

Dokan official documentation