dokan.h
Go to the documentation of this file.
1 /*
2  Dokan : user-mode file system library for Windows
3 
4  Copyright (C) 2020 - 2023 Google, Inc.
5  Copyright (C) 2015 - 2019 Adrien J. <liryna.stark@gmail.com> and Maxime C. <maxime@islog.com>
6  Copyright (C) 2007 - 2011 Hiroki Asakawa <info@dokan-dev.net>
7 
8  http://dokan-dev.github.io
9 
10 This program is free software; you can redistribute it and/or modify it under
11 the terms of the GNU Lesser General Public License as published by the Free
12 Software Foundation; either version 3 of the License, or (at your option) any
13 later version.
14 
15 This program is distributed in the hope that it will be useful, but WITHOUT ANY
16 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
18 
19 You should have received a copy of the GNU Lesser General Public License along
20 with this program. If not, see <http://www.gnu.org/licenses/>.
21 */
22 
23 #ifndef DOKAN_H_
24 #define DOKAN_H_
25 
27 #define WIN32_NO_STATUS
28 #include <windows.h>
29 #undef WIN32_NO_STATUS
30 #include <ntstatus.h>
31 
32 #include "fileinfo.h"
33 #include "public.h"
34 
35 #ifdef _EXPORTING
36 
37 #define DOKANAPI __stdcall
38 #else
39 
40 #define DOKANAPI __declspec(dllimport) __stdcall
41 #endif
42 
44 #define DOKAN_CALLBACK __stdcall
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
59 #define DOKAN_VERSION 220
60 
61 #define DOKAN_MINIMUM_COMPATIBLE_VERSION 200
62 
63 #define DOKAN_DRIVER_NAME L"dokan" DOKAN_MAJOR_API_VERSION L".sys"
64 
65 #define DOKAN_NP_NAME L"Dokan" DOKAN_MAJOR_API_VERSION
66 
77 #define DOKAN_OPTION_DEBUG 1
78 
79 #define DOKAN_OPTION_STDERR (1 << 1)
80 
85 #define DOKAN_OPTION_ALT_STREAM (1 << 2)
86 
87 #define DOKAN_OPTION_WRITE_PROTECT (1 << 3)
88 
89 #define DOKAN_OPTION_NETWORK (1 << 4)
90 
96 #define DOKAN_OPTION_REMOVABLE (1 << 5)
97 
104 #define DOKAN_OPTION_MOUNT_MANAGER (1 << 6)
105 
111 #define DOKAN_OPTION_CURRENT_SESSION (1 << 7)
112 
113 #define DOKAN_OPTION_FILELOCK_USER_MODE (1 << 8)
114 
120 #define DOKAN_OPTION_CASE_SENSITIVE (1 << 9)
121 
122 #define DOKAN_OPTION_ENABLE_UNMOUNT_NETWORK_DRIVE (1 << 10)
123 
127 #define DOKAN_OPTION_DISPATCH_DRIVER_LOGS (1 << 11)
128 
133 #define DOKAN_OPTION_ALLOW_IPC_BATCHING (1 << 12)
134 
137 typedef VOID *DOKAN_HANDLE, **PDOKAN_HANDLE;
138 
144 typedef struct _DOKAN_OPTIONS {
146  USHORT Version;
148  BOOLEAN SingleThread;
150  ULONG Options;
152  ULONG64 GlobalContext;
154  LPCWSTR MountPoint;
159  LPCWSTR UNCName;
166  ULONG Timeout;
170  ULONG SectorSize;
174  CHAR VolumeSecurityDescriptor[VOLUME_SECURITY_DESCRIPTOR_MAX_SIZE];
175 } DOKAN_OPTIONS, *PDOKAN_OPTIONS;
176 
181 typedef struct _DOKAN_FILE_INFO {
187  ULONG64 Context;
189  ULONG64 DokanContext;
191  PDOKAN_OPTIONS DokanOptions;
201  ULONG ProcessId;
206  UCHAR IsDirectory;
210  UCHAR PagingIo;
214  UCHAR Nocache;
217 } DOKAN_FILE_INFO, *PDOKAN_FILE_INFO;
218 
219 #define DOKAN_EXCEPTION_NOT_INITIALIZED 0x0f0ff0ff
220 #define DOKAN_EXCEPTION_INITIALIZATION_FAILED 0x0fbadbad
221 #define DOKAN_EXCEPTION_SHUTDOWN_FAILED 0x0fbadf00
222 
227 typedef int(WINAPI *PFillFindData)(PWIN32_FIND_DATAW, PDOKAN_FILE_INFO);
228 
233 typedef BOOL(WINAPI *PFillFindStreamData)(PWIN32_FIND_STREAM_DATA, PVOID);
234 
235 // clang-format off
236 
251 typedef struct _DOKAN_OPERATIONS {
283  NTSTATUS(DOKAN_CALLBACK *ZwCreateFile)(LPCWSTR FileName,
284  PDOKAN_IO_SECURITY_CONTEXT SecurityContext,
285  ACCESS_MASK DesiredAccess,
286  ULONG FileAttributes,
287  ULONG ShareAccess,
288  ULONG CreateDisposition,
289  ULONG CreateOptions,
290  PDOKAN_FILE_INFO DokanFileInfo);
291 
307  void(DOKAN_CALLBACK *Cleanup)(LPCWSTR FileName,
308  PDOKAN_FILE_INFO DokanFileInfo);
309 
321  void(DOKAN_CALLBACK *CloseFile)(LPCWSTR FileName,
322  PDOKAN_FILE_INFO DokanFileInfo);
323 
343  NTSTATUS(DOKAN_CALLBACK *ReadFile)(LPCWSTR FileName,
344  LPVOID Buffer,
345  DWORD BufferLength,
346  LPDWORD ReadLength,
347  LONGLONG Offset,
348  PDOKAN_FILE_INFO DokanFileInfo);
349 
371  NTSTATUS(DOKAN_CALLBACK *WriteFile)(LPCWSTR FileName,
372  LPCVOID Buffer,
373  DWORD NumberOfBytesToWrite,
374  LPDWORD NumberOfBytesWritten,
375  LONGLONG Offset,
376  PDOKAN_FILE_INFO DokanFileInfo);
377 
387  NTSTATUS(DOKAN_CALLBACK *FlushFileBuffers)(LPCWSTR FileName,
388  PDOKAN_FILE_INFO DokanFileInfo);
389 
400  NTSTATUS(DOKAN_CALLBACK *GetFileInformation)(LPCWSTR FileName,
401  LPBY_HANDLE_FILE_INFORMATION Buffer,
402  PDOKAN_FILE_INFO DokanFileInfo);
403 
418  NTSTATUS(DOKAN_CALLBACK *FindFiles)(LPCWSTR FileName,
419  PFillFindData FillFindData,
420  PDOKAN_FILE_INFO DokanFileInfo);
421 
441  NTSTATUS(DOKAN_CALLBACK *FindFilesWithPattern)(LPCWSTR PathName,
442  LPCWSTR SearchPattern,
443  PFillFindData FillFindData,
444  PDOKAN_FILE_INFO DokanFileInfo);
445 
456  NTSTATUS(DOKAN_CALLBACK *SetFileAttributes)(LPCWSTR FileName,
457  DWORD FileAttributes,
458  PDOKAN_FILE_INFO DokanFileInfo);
459 
472  NTSTATUS(DOKAN_CALLBACK *SetFileTime)(LPCWSTR FileName,
473  CONST FILETIME *CreationTime,
474  CONST FILETIME *LastAccessTime,
475  CONST FILETIME *LastWriteTime,
476  PDOKAN_FILE_INFO DokanFileInfo);
477 
502  NTSTATUS(DOKAN_CALLBACK *DeleteFile)(LPCWSTR FileName,
503  PDOKAN_FILE_INFO DokanFileInfo);
504 
530  NTSTATUS(DOKAN_CALLBACK *DeleteDirectory)(LPCWSTR FileName,
531  PDOKAN_FILE_INFO DokanFileInfo);
532 
544  NTSTATUS(DOKAN_CALLBACK *MoveFile)(LPCWSTR FileName,
545  LPCWSTR NewFileName,
546  BOOL ReplaceIfExisting,
547  PDOKAN_FILE_INFO DokanFileInfo);
548 
560  NTSTATUS(DOKAN_CALLBACK *SetEndOfFile)(LPCWSTR FileName,
561  LONGLONG ByteOffset,
562  PDOKAN_FILE_INFO DokanFileInfo);
563 
575  NTSTATUS(DOKAN_CALLBACK *SetAllocationSize)(LPCWSTR FileName,
576  LONGLONG AllocSize,
577  PDOKAN_FILE_INFO DokanFileInfo);
578 
592  NTSTATUS(DOKAN_CALLBACK *LockFile)(LPCWSTR FileName,
593  LONGLONG ByteOffset,
594  LONGLONG Length,
595  PDOKAN_FILE_INFO DokanFileInfo);
596 
610  NTSTATUS(DOKAN_CALLBACK *UnlockFile)(LPCWSTR FileName,
611  LONGLONG ByteOffset,
612  LONGLONG Length,
613  PDOKAN_FILE_INFO DokanFileInfo);
614 
635  NTSTATUS(DOKAN_CALLBACK *GetDiskFreeSpace)(PULONGLONG FreeBytesAvailable,
636  PULONGLONG TotalNumberOfBytes,
637  PULONGLONG TotalNumberOfFreeBytes,
638  PDOKAN_FILE_INFO DokanFileInfo);
639 
674  NTSTATUS(DOKAN_CALLBACK *GetVolumeInformation)(LPWSTR VolumeNameBuffer,
675  DWORD VolumeNameSize,
676  LPDWORD VolumeSerialNumber,
677  LPDWORD MaximumComponentLength,
678  LPDWORD FileSystemFlags,
679  LPWSTR FileSystemNameBuffer,
680  DWORD FileSystemNameSize,
681  PDOKAN_FILE_INFO DokanFileInfo);
682 
696  NTSTATUS(DOKAN_CALLBACK *Mounted)(LPCWSTR MountPoint, PDOKAN_FILE_INFO DokanFileInfo);
697 
707  NTSTATUS(DOKAN_CALLBACK *Unmounted)(PDOKAN_FILE_INFO DokanFileInfo);
708 
728  NTSTATUS(DOKAN_CALLBACK *GetFileSecurity)(LPCWSTR FileName,
729  PSECURITY_INFORMATION SecurityInformation,
730  PSECURITY_DESCRIPTOR SecurityDescriptor,
731  ULONG BufferLength,
732  PULONG LengthNeeded,
733  PDOKAN_FILE_INFO DokanFileInfo);
734 
750  NTSTATUS(DOKAN_CALLBACK *SetFileSecurity)(LPCWSTR FileName,
751  PSECURITY_INFORMATION SecurityInformation,
752  PSECURITY_DESCRIPTOR SecurityDescriptor,
753  ULONG BufferLength,
754  PDOKAN_FILE_INFO DokanFileInfo);
755 
769  NTSTATUS(DOKAN_CALLBACK *FindStreams)(LPCWSTR FileName,
770  PFillFindStreamData FillFindStreamData,
771  PVOID FindStreamContext,
772  PDOKAN_FILE_INFO DokanFileInfo);
773 
774 } DOKAN_OPERATIONS, *PDOKAN_OPERATIONS;
775 
776 // clang-format on
777 
785 #define DOKAN_SUCCESS 0
786 
787 #define DOKAN_ERROR -1
788 
789 #define DOKAN_DRIVE_LETTER_ERROR -2
790 
791 #define DOKAN_DRIVER_INSTALL_ERROR -3
792 
793 #define DOKAN_START_ERROR -4
794 
799 #define DOKAN_MOUNT_ERROR -5
800 
804 #define DOKAN_MOUNT_POINT_ERROR -6
805 
809 #define DOKAN_VERSION_ERROR -7
810 
824 VOID DOKANAPI DokanInit();
825 
832 VOID DOKANAPI DokanShutdown();
833 
846 int DOKANAPI DokanMain(PDOKAN_OPTIONS DokanOptions,
847  PDOKAN_OPERATIONS DokanOperations);
848 
864 int DOKANAPI DokanCreateFileSystem(_In_ PDOKAN_OPTIONS DokanOptions,
865  _In_ PDOKAN_OPERATIONS DokanOperations,
866  _Out_ DOKAN_HANDLE *DokanInstance);
867 
874 BOOL DOKANAPI DokanIsFileSystemRunning(_In_ DOKAN_HANDLE DokanInstance);
875 
883 DWORD DOKANAPI DokanWaitForFileSystemClosed(_In_ DOKAN_HANDLE DokanInstance,
884  _In_ DWORD dwMilliseconds);
885 
897  _In_ DOKAN_HANDLE DokanInstance, _Out_ PHANDLE WaitHandle,
898  _In_ WAITORTIMERCALLBACKFUNC Callback, _In_ PVOID Context,
899  ULONG dwMilliseconds);
900 
908 BOOL DOKANAPI DokanUnregisterWaitForFileSystemClosed(_In_ HANDLE WaitHandle,
909  BOOL WaitForCallbacks);
910 
918 VOID DOKANAPI DokanCloseHandle(_In_ DOKAN_HANDLE DokanInstance);
919 
926 BOOL DOKANAPI DokanUnmount(WCHAR DriveLetter);
927 
934 BOOL DOKANAPI DokanRemoveMountPoint(LPCWSTR MountPoint);
935 
954 BOOL DOKANAPI DokanIsNameInExpression(LPCWSTR Expression, LPCWSTR Name,
955  BOOL IgnoreCase);
956 
962 ULONG DOKANAPI DokanVersion();
963 
970 
978 BOOL DOKANAPI DokanResetTimeout(ULONG Timeout, PDOKAN_FILE_INFO DokanFileInfo);
979 
990 HANDLE DOKANAPI DokanOpenRequestorToken(PDOKAN_FILE_INFO DokanFileInfo);
991 
1001 PDOKAN_MOUNT_POINT_INFO DOKANAPI DokanGetMountPointList(BOOL uncOnly, PULONG nbRead);
1002 
1012 VOID DOKANAPI DokanReleaseMountPointList(PDOKAN_MOUNT_POINT_INFO list);
1013 
1031  ACCESS_MASK DesiredAccess, ULONG FileAttributes, ULONG CreateOptions,
1032  ULONG CreateDisposition, ACCESS_MASK *outDesiredAccess,
1033  DWORD *outFileAttributesAndFlags, DWORD *outCreationDisposition);
1034 
1063 BOOL DOKANAPI DokanNotifyCreate(_In_ DOKAN_HANDLE DokanInstance,
1064  _In_ LPCWSTR FilePath, _In_ BOOL IsDirectory);
1065 
1074 BOOL DOKANAPI DokanNotifyDelete(_In_ DOKAN_HANDLE DokanInstance,
1075  _In_ LPCWSTR FilePath, _In_ BOOL IsDirectory);
1076 
1084 BOOL DOKANAPI DokanNotifyUpdate(_In_ DOKAN_HANDLE DokanInstance,
1085  _In_ LPCWSTR FilePath);
1086 
1094 BOOL DOKANAPI DokanNotifyXAttrUpdate(_In_ DOKAN_HANDLE DokanInstance,
1095  _In_ LPCWSTR FilePath);
1096 
1108 BOOL DOKANAPI DokanNotifyRename(_In_ DOKAN_HANDLE DokanInstance,
1109  _In_ LPCWSTR OldPath, _In_ LPCWSTR NewPath,
1110  _In_ BOOL IsDirectory,
1111  _In_ BOOL IsInSameDirectory);
1112 
1123 NTSTATUS DOKANAPI DokanNtStatusFromWin32(DWORD Error);
1124 
1127 #ifdef __cplusplus
1128 }
1129 #endif
1130 
1131 #endif // DOKAN_H_
#define DOKAN_CALLBACK
Definition: dokan.h:44
HANDLE DokanOpenRequestorToken(PDOKAN_FILE_INFO DokanFileInfo)
Get the handle to Access Token.
Definition: access.c:26
PDOKAN_OPTIONS DokanOptions
Definition: dokan.h:191
BOOL DokanIsFileSystemRunning(_In_ DOKAN_HANDLE DokanInstance)
Check if the FileSystem is still running or not.
Definition: dokan.c:605
VOID DokanShutdown()
Release all allocated resources by DokanInit when they are no longer needed.
Definition: dokan.c:1418
USHORT Version
Definition: dokan.h:146
PDOKAN_MOUNT_POINT_INFO DokanGetMountPointList(BOOL uncOnly, PULONG nbRead)
Get active Dokan mount points.
Definition: dokan.c:1232
LPCWSTR MountPoint
Definition: dokan.h:154
BOOL DokanUnregisterWaitForFileSystemClosed(_In_ HANDLE WaitHandle, BOOL WaitForCallbacks)
Unregister callback for FileSystem unmount.
Definition: dokan.c:636
ULONG64 GlobalContext
Definition: dokan.h:152
ULONG ProcessId
Definition: dokan.h:201
BOOL DokanRemoveMountPoint(LPCWSTR MountPoint)
Unmount a Dokan device from a mount point.
Definition: mount.c:649
BOOL DokanResetTimeout(ULONG Timeout, PDOKAN_FILE_INFO DokanFileInfo)
Extends the timeout of the current IO operation in driver.
Definition: timeout.c:26
#define DOKANAPI
Definition: dokan.h:40
UCHAR Nocache
Definition: dokan.h:214
ULONG Timeout
Definition: dokan.h:166
VOID DokanReleaseMountPointList(PDOKAN_MOUNT_POINT_INFO list)
Release Mount point list resources from DokanGetMountPointList.
Definition: dokan.c:1280
UCHAR WriteToEndOfFile
Definition: dokan.h:216
BOOL DokanNotifyXAttrUpdate(_In_ DOKAN_HANDLE DokanInstance, _In_ LPCWSTR FilePath)
Notify dokan that file or directory extended attributes have changed.
Definition: dokan.c:1502
DWORD DokanWaitForFileSystemClosed(_In_ DOKAN_HANDLE DokanInstance, _In_ DWORD dwMilliseconds)
Wait until the FileSystem is unmount.
Definition: dokan.c:614
UCHAR SynchronousIo
Definition: dokan.h:212
BOOL DokanNotifyDelete(_In_ DOKAN_HANDLE DokanInstance, _In_ LPCWSTR FilePath, _In_ BOOL IsDirectory)
Notify dokan that a file or a directory has been deleted.
Definition: dokan.c:1488
NTSTATUS DokanNtStatusFromWin32(DWORD Error)
Convert WIN32 error to NTSTATUS.
Definition: ntstatus.c:25
LPCWSTR UNCName
Definition: dokan.h:159
BOOL DokanRegisterWaitForFileSystemClosed(_In_ DOKAN_HANDLE DokanInstance, _Out_ PHANDLE WaitHandle, _In_ WAITORTIMERCALLBACKFUNC Callback, _In_ PVOID Context, ULONG dwMilliseconds)
Register callback for FileSystem unmount.
Definition: dokan.c:623
Dokan mount options used to describe Dokan device behavior.
Definition: dokan.h:144
BOOL DokanNotifyCreate(_In_ DOKAN_HANDLE DokanInstance, _In_ LPCWSTR FilePath, _In_ BOOL IsDirectory)
Notify dokan that a file or a directory has been created.
Definition: dokan.c:1480
int(WINAPI * PFillFindData)(PWIN32_FIND_DATAW, PDOKAN_FILE_INFO)
FillFindData Used to add an entry in FindFiles operation.
Definition: dokan.h:227
BOOL(WINAPI * PFillFindStreamData)(PWIN32_FIND_STREAM_DATA, PVOID)
FillFindStreamData Used to add an entry in FindStreams.
Definition: dokan.h:233
int DokanCreateFileSystem(_In_ PDOKAN_OPTIONS DokanOptions, _In_ PDOKAN_OPERATIONS DokanOperations, _Out_ DOKAN_HANDLE *DokanInstance)
Mount a new Dokan Volume.
Definition: dokan.c:670
ULONG DokanVersion()
Get the version of Dokan. The returned ULONG is the version number without the dots.
Definition: version.c:26
Dokan file information on the current operation.
Definition: dokan.h:181
ULONG SectorSize
Definition: dokan.h:170
BOOLEAN SingleThread
Definition: dokan.h:148
VOID DokanMapKernelToUserCreateFileFlags(ACCESS_MASK DesiredAccess, ULONG FileAttributes, ULONG CreateOptions, ULONG CreateDisposition, ACCESS_MASK *outDesiredAccess, DWORD *outFileAttributesAndFlags, DWORD *outCreationDisposition)
Convert DOKAN_OPERATIONS::ZwCreateFile parameters to CreateFile parameters.
Definition: dokan.c:1301
ULONG DokanDriverVersion()
Get the version of the Dokan driver. The returned ULONG is the version number without the dots...
Definition: version.c:28
ULONG64 Context
Definition: dokan.h:187
UCHAR DeleteOnClose
Definition: dokan.h:208
UCHAR PagingIo
Definition: dokan.h:210
UCHAR IsDirectory
Definition: dokan.h:206
BOOL DokanIsNameInExpression(LPCWSTR Expression, LPCWSTR Name, BOOL IgnoreCase)
Checks whether Name matches Expression.
Definition: directory.c:748
VOID DokanCloseHandle(_In_ DOKAN_HANDLE DokanInstance)
Unmount the Dokan instance.
Definition: dokan.c:642
ULONG AllocationUnitSize
Definition: dokan.h:168
BOOL DokanNotifyUpdate(_In_ DOKAN_HANDLE DokanInstance, _In_ LPCWSTR FilePath)
Notify dokan that file or directory attributes have changed.
Definition: dokan.c:1496
BOOL DokanUnmount(WCHAR DriveLetter)
Unmount a Dokan device from a driver letter.
Definition: mount.c:296
int DokanMain(PDOKAN_OPTIONS DokanOptions, PDOKAN_OPERATIONS DokanOperations)
Mount a new Dokan Volume.
Definition: dokan.c:656
Dokan API callbacks interface.
Definition: dokan.h:251
ULONG64 DokanContext
Definition: dokan.h:189
VOID DokanInit()
Initialize all required Dokan internal resources.
Definition: dokan.c:1393
BOOL DokanNotifyRename(_In_ DOKAN_HANDLE DokanInstance, _In_ LPCWSTR OldPath, _In_ LPCWSTR NewPath, _In_ BOOL IsDirectory, _In_ BOOL IsInSameDirectory)
Notify dokan that a file or a directory has been renamed. This method supports in-place rename for fi...
Definition: dokan.c:1508
ULONG VolumeSecurityDescriptorLength
Definition: dokan.h:172
PVOID ProcessingContext
Definition: dokan.h:197
ULONG Options
Definition: dokan.h:150