Struct dokany_sys::DOKAN_OPERATIONS

#[repr(C)]
pub struct DOKAN_OPERATIONS {

    pub ZwCreateFile: Option<ZwCreateFileCallback>,
    pub Cleanup: Option<CleanupCallback>,
    pub CloseFile: Option<CloseFileCallback>,
    pub ReadFile: Option<ReadFileCallback>,
    pub WriteFile: Option<WriteFileCallback>,
    pub FlushFileBuffers: Option<FlushFileBuffersCallback>,
    pub GetFileInformation: Option<GetFileInformationCallback>,
    pub FindFiles: Option<FindFilesCallback>,
    pub FindFilesWithPattern: Option<FindFilesWithPatternCallback>,
    pub SetFileAttributes: Option<SetFileAttributesCallback>,
    pub SetFileTime: Option<SetFileTimeCallback>,
    pub DeleteFile: Option<DeleteFileCallback>,
    pub DeleteDirectory: Option<DeleteDirectoryCallback>,
    pub MoveFile: Option<MoveFileCallback>,
    pub SetEndOfFile: Option<SetEndOfFileCallback>,
    pub SetAllocationSize: Option<SetAllocationSizeCallback>,
    pub LockFile: Option<LockFileCallback>,
    pub UnlockFile: Option<UnlockFileCallback>,
    pub GetDiskFreeSpace: Option<GetDiskFreeSpaceCallback>,
    pub GetVolumeInformation: Option<GetVolumeInformationCallback>,
    pub Mounted: Option<MountedCallback>,
    pub Unmounted: Option<Unmounted>,
    pub GetFileSecurity: Option<GetFileSecurityCallback>,
    pub SetFileSecurity: Option<SetFileSecurityCallback>,
    pub FindStreams: Option<FindStreamsCallback>,
}

Dokan API callbacks interface

DOKAN_OPERATIONS is a struct of callbacks that describe all Dokan API operations that will be called when Windows access to the filesystem.

If an error occurs, return NTSTATUS (https://support.microsoft.com/en-us/kb/113996). Win32 Error can be converted to NTSTATUS with [DokanNtStatusFromWin32]

All callbacks can be set to NULL or return STATUS_NOT_IMPLEMENTED such as DOKAN_OPERATIONS.ZwCreateFile / DOKAN_OPERATIONS.ReadFile / … would make the filesystem not work or become unstable.

Fields

ZwCreateFile: Option<ZwCreateFileCallback>

CreateFile Dokan API callback

CreateFile is called each time a request is made on a file system object.

In case OPEN_ALWAYS & CREATE_ALWAYS are successfully opening an existing file, STATUS_OBJECT_NAME_COLLISION should be returned instead of STATUS_SUCCESS. This will inform Dokan that the file has been opened and not created during the request.

If the file is a directory, CreateFile is also called. In this case, CreateFile should return STATUS_SUCCESS when that directory can be opened and DOKAN_FILE_INFO.IsDirectory has to be set to TRUE. On the other hand, if DOKAN_FILE_INFO.IsDirectory is set to TRUE but the path targets a file, STATUS_NOT_A_DIRECTORY must be returned.

DOKAN_FILE_INFO.Context can be used to store Data (like HANDLE) that can be retrieved in all other requests related to the Context. To avoid memory leak, Context needs to be released in DOKAN_OPERATIONS.Cleanup.

Arguments

FileName: File path requested by the Kernel on the FileSystem. SecurityContext: SecurityContext, see https://msdn.microsoft.com/en-us/library/windows/hardware/ff550613(v=vs.85).aspx DesiredAccess: Specifies an ACCESS_MASK value that determines the requested access to the object. FileAttributes: Specifies one or more FILE_ATTRIBUTE_XXX flags, which represent the file attributes to set if a file is created or overwritten. ShareAccess: Type of share access, which is specified as zero or any combination of FILE_SHARE_* flags. CreateDisposition: Specifies the action to perform if the file does or does not exist. CreateOptions: Specifies the options to apply when the driver creates or opens the file. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See See ZwCreateFile for more information about the parameters of this callback (MSDN). See DokanMapKernelToUserCreateFileFlags

Cleanup: Option<CleanupCallback>

Cleanup Dokan API callback

Cleanup request before CloseFile is called.

When DOKAN_FILE_INFO.DeleteOnClose is TRUE, the file in Cleanup must be deleted. The function cannot fail therefore the filesystem need to ensure ahead that a the delete can safely happen during Cleanup. See DeleteFile documentation for explanation.

Arguments

FileName: File path requested by the Kernel on the FileSystem. DokanFileInfo: Information about the file or directory.

References

See DeleteFile See DeleteDirectory

CloseFile: Option<CloseFileCallback>

CloseFile Dokan API callback

Clean remaining Context

CloseFile is called at the end of the life of the context. Anything remaining in DOKAN_FILE_INFO.Context must be cleared before returning.

Arguments

FileName: File path requested by the Kernel on the FileSystem. DokanFileInfo: Information about the file or directory.

ReadFile: Option<ReadFileCallback>

ReadFile Dokan API callback

ReadFile callback on the file previously opened in DOKAN_OPERATIONS.ZwCreateFile. It can be called by different threads at the same time, so the read/context has to be thread safe.

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

Arguments

FileName: File path requested by the Kernel on the FileSystem. Buffer: Read buffer that has to be filled with the read result. BufferLength: Buffer length and read size to continue with. ReadLength: Total data size that has been read. Offset: Offset from where the read has to be continued. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See WriteFile

WriteFile: Option<WriteFileCallback>

WriteFile Dokan API callback

WriteFile callback on the file previously opened in DOKAN_OPERATIONS.ZwCreateFile It can be called by different threads at the same time, sp the write/context has to be thread safe.

When apps make use of memory mapped files ( DOKAN_FILE_INFO.PagingIo ), DOKAN_OPERATIONS.WriteFile or DOKAN_OPERATIONS.ReadFile The file system application should also properly work in this case. This type of request should follow Windows rules like not extending the current file size.

Arguments

FileName: File path requested by the Kernel on the FileSystem. Buffer: Data that has to be written. NumberOfBytesToWrite: Buffer length and write size to continue with. NumberOfBytesWritten: Total number of bytes that have been written. Offset: Offset from where the write has to be continued. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References See ReadFile

FlushFileBuffers: Option<FlushFileBuffersCallback>

FlushFileBuffers Dokan API callback

Clears buffers for this context and causes any buffered data to be written to the file.

Arguments

FileName File path requested by the Kernel on the FileSystem. DokanFileInfo Information about the file or directory.

Returns

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

GetFileInformation: Option<GetFileInformationCallback>

GetFileInformation Dokan API callback

Get specific information on a file.

Arguments

FileName: File path requested by the Kernel on the FileSystem. Buffer: BY_HANDLE_FILE_INFORMATION struct to fill. DokanFileInfo: Information about the file or directory.

Returns

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

FindFiles: Option<FindFilesCallback>

FindFiles Dokan API callback

List all files in the requested path. DOKAN_OPERATIONS.FindFilesWithPattern is checked first. If it is not implemented or returns STATUS_NOT_IMPLEMENTED, then FindFiles is called, if assigned. It is recommended to have this implemented for performance reason.

Arguments

FileName: File path requested by the Kernel on the FileSystem. FillFindData: Callback that has to be called with PWIN32_FIND_DATAW that contain file information. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See FindFilesWithPattern

FindFilesWithPattern: Option<FindFilesWithPatternCallback>

FindFilesWithPattern Dokan API callback

Same as DOKAN_OPERATIONS.FindFiles but with a search pattern.\n The search pattern is a Windows MS-DOS-style expression. It can contain wild cards and extended characters or none of them. See DokanIsNameInExpression.

If the function is not implemented, DOKAN_OPERATIONS.FindFiles will be called instead and the result will be filtered internally by the library. It is recommended to have this implemented for performance reason.

Arguments

PathName: Path requested by the Kernel on the FileSystem. SearchPattern: Search pattern. FillFindData: Callback that has to be called with PWIN32_FIND_DATAW that contains file information. DokanFileInfo: Information about the file or directory.

Returns

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See FindFiles See DokanIsNameInExpression

SetFileAttributes: Option<SetFileAttributesCallback>

SetFileAttributes Dokan API callback

Set file attributes on a specific file

Arguments

FileName File path requested by the Kernel on the FileSystem. FileAttributes FileAttributes to set on file. DokanFileInfo Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

SetFileTime: Option<SetFileTimeCallback>

SetFileTime Dokan API callback

Set file attributes on a specific file

Arguments

FileName: File path requested by the Kernel on the FileSystem. CreationTime: Creation FILETIME. LastAccessTime: LastAccess FILETIME. LastWriteTime: LastWrite FILETIME. DokanFileInfo: Information about the file or directory.

Returns

STATUS_SUCCESS: on success or NTSTATUS appropriate to the request result.

DeleteFile: Option<DeleteFileCallback>

DeleteFile Dokan API callback

Check if it is possible to delete a file.

DeleteFile will also be called with DOKAN_FILE_INFO.DeleteOnClose set to FALSE to notify the driver when the file is no longer requested to be deleted.

The file in DeleteFile should not be deleted, but instead the file must be checked as to whether or not it can be deleted, and STATUS_SUCCESS should be returned (when it can be deleted) or appropriate error codes, such as STATUS_ACCESS_DENIED or STATUS_OBJECT_NAME_NOT_FOUND, should be returned.

When STATUS_SUCCESS is returned, a Cleanup call is received afterwards with DOKAN_FILE_INFO.DeleteOnClose set to TRUE. Only then must the closing file be deleted.

Arguments

FileName: File path requested by the Kernel on the FileSystem. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS: on success or NTSTATUS appropriate to the request result.

References

See DeleteDirectory See Cleanup

DeleteDirectory: Option<DeleteDirectoryCallback>

Check if it is possible to delete a directory.

DeleteDirectory will also be called with DOKAN_FILE_INFO.DeleteOnClose set to FALSE to notify the driver when the file is no longer requested to be deleted.

The Directory in DeleteDirectory should not be deleted, but instead must be checked as to whether or not it can be deleted, and STATUS_SUCCESS should be returned (when it can be deleted) or appropriate error codes, such as STATUS_ACCESS_DENIED, STATUS_OBJECT_PATH_NOT_FOUND, or STATUS_DIRECTORY_NOT_EMPTY, should be returned.

When STATUS_SUCCESS is returned, a Cleanup call is received afterwards with DOKAN_FILE_INFO.DeleteOnClose set to TRUE. Only then must the closing file be deleted.

Arguments

FileName: File path requested by the Kernel on the FileSystem. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

[DeleteFile] [Cleanup]

MoveFile: Option<MoveFileCallback>

MoveFile Dokan API callback

Move a file or directory to a new destination

Arguments

FileName: Path for the file to be moved. NewFileName: Path for the new location of the file. ReplaceIfExisting: If destination already exists, can it be replaced? DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

SetEndOfFile: Option<SetEndOfFileCallback>

SetEndOfFile Dokan API callback

SetEndOfFile is used to truncate or extend a file (physical file size).

Arguments

FileName: File path requested by the Kernel on the FileSystem. ByteOffset: File length to set. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

SetAllocationSize: Option<SetAllocationSizeCallback>

SetAllocationSize Dokan API callback

SetAllocationSize is used to truncate or extend a file.

Arguments

FileName: File path requested by the Kernel on the FileSystem. AllocSize: File length to set. DokanFileInfo: Information about the file or directory.

Returns

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

LockFile: Option<LockFileCallback>

LockFile Dokan API callback

Lock file at a specific offset and data length. This is only used if DOKAN_OPTION_FILELOCK_USER_MODE is enabled.

Arguments

FileName: File path requested by the Kernel on the FileSystem. ByteOffset: Offset from where the lock has to be continued. Length: Data length to lock. DokanFileInfo: Information about the file or directory.

Returns

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See UnlockFile

UnlockFile: Option<UnlockFileCallback>

UnlockFile Dokan API callback

Unlock file at a specific offset and data length. This is only used if DOKAN_OPTION_FILELOCK_USER_MODE is enabled.

Arguments

FileName: File path requested by the Kernel on the FileSystem. ByteOffset: Offset from where the lock has to be continued. Length: Data length to lock. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

Return

See LockFile

GetDiskFreeSpace: Option<GetDiskFreeSpaceCallback>

GetDiskFreeSpace Dokan API callback

Retrieves information about the amount of space that is available on a disk volume. It consits of the total amount of space, the total amount of free space, and

Neither GetDiskFreeSpace nor GetVolumeInformation save the DOKAN_FILE_INFO.Context. Before these methods are called, \ref ZwCreateFile may not be called. (ditto [CloseFile] and [Cleanup])

Arguments

FreeBytesAvailable Amount of available space. TotalNumberOfBytes: Total size of storage space TotalNumberOfFreeBytes: Amount of free space DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or \c NTSTATUS appropriate to the request result.

References

See GetDiskFreeSpaceEx function (MSDN) See GetVolumeInformation

GetVolumeInformation: Option<GetVolumeInformationCallback>

GetVolumeInformation Dokan API callback

Retrieves information about the file system and volume associated with the specified root directory.

Neither GetVolumeInformation nor GetDiskFreeSpace save the DOKAN_FILE_INFO#Context. Before these methods are called, [ZwCreateFile] may not be called. (ditto [CloseFile] and [Cleanup])

VolumeName length can be anything that fit in the provided buffer. But some Windows component expect it to be no longer than 32 characters that why it is recommended to set a value under this limit.

FileSystemName could be anything up to 10 characters. But Windows check few feature availability based on file system name. For this, it is recommended to set NTFS or FAT here.

FILE_READ_ONLY_VOLUME is automatically added to the FileSystemFlags if DOKAN_OPTION_WRITE_PROTECT was specified in DOKAN_OPTIONS when the volume was mounted.

Arguments

VolumeNameBuffer: A pointer to a buffer that receives the name of a specified volume. VolumeNameSize: The length of a volume name buffer. VolumeSerialNumber: A pointer to a variable that receives the volume serial number. MaximumComponentLength: A pointer to a variable that receives the maximum length. FileSystemFlags: A pointer to a variable that receives flags associated with the specified file system. FileSystemNameBuffer: A pointer to a buffer that receives the name of the file system. FileSystemNameSize: The length of the file system name buffer. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See GetVolumeInformation function (MSDN) See GetDiskFreeSpace

Mounted: Option<MountedCallback>

Mounted Dokan API callback

Called when Dokan successfully mounts the volume.

If DOKAN_OPTION_MOUNT_MANAGER is enabled and the drive letter requested is busy, the MountPoint can contain a different drive letter that the mount manager assigned us.

Arguments

MountPoint: The mount point assign to the instance. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result. The value is currently not used by the library.

References

See Unmounted

Unmounted: Option<Unmounted>

Unmounted Dokan API callback

Called when Dokan is unmounting the volume.

References

DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result. The value is currently not used by the library.

References

See Mounted

GetFileSecurity: Option<GetFileSecurityCallback>

GetFileSecurity Dokan API callback

Get specified information about the security of a file or directory.

Return STATUS_NOT_IMPLEMENTED to let dokan library build a sddl of the current process user with authenticate user rights for context menu. Return STATUS_BUFFER_OVERFLOW if buffer size is too small.

Supported since version 0.6.0. The version must be specified in DOKAN_OPTIONS.Version.

Parameters

FileName: File path requested by the Kernel on the FileSystem. SecurityInformation: A SECURITY_INFORMATION value that identifies the security information being requested. SecurityDescriptor: A pointer to a buffer that receives a copy of the security descriptor of the requested file. BufferLength: Specifies the size, in bytes, of the buffer. LengthNeeded: A pointer to the variable that receives the number of bytes necessary to store the complete security descriptor. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

References

See SetFileSecurity See GetFileSecurity function (MSDN)

SetFileSecurity: Option<SetFileSecurityCallback>

SetFileSecurity Dokan API callback

Sets the security of a file or directory object.

Supported since version 0.6.0. The version must be specified in DOKAN_OPTIONS.Version.

Arguments

FileName: File path requested by the Kernel on the FileSystem. SecurityInformation: Structure that identifies the contents of the security descriptor pointed by \a SecurityDescriptor param. SecurityDescriptor: A pointer to a SECURITY_DESCRIPTOR structure. BufferLength: Specifies the size, in bytes, of the buffer. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result. References See GetFileSecurity See SetFileSecurity function (MSDN)

FindStreams: Option<FindStreamsCallback>

FindStreams Dokan API callback

Retrieve all NTFS Streams informations on the file. This is only called if DOKAN_OPTION_ALT_STREAM is enabled.

Supported since version 0.8.0. The version must be specified in \ref DOKAN_OPTIONS.Version.

Arguments

FileName: File path requested by the Kernel on the FileSystem. FillFindStreamData: Callback that has to be called with PWIN32_FIND_STREAM_DATA that contain stream information. FindStreamContext: Context for the event to pass to the callback FillFindStreamData. DokanFileInfo: Information about the file or directory.

Return

STATUS_SUCCESS on success or NTSTATUS appropriate to the request result.

Implementations

impl DOKAN_OPERATIONS

pub const fn new() -> Self

Make a new empty DOKAN_OPERATIONS.

Trait Implementations

impl Default for DOKAN_OPERATIONS

fn default() -> Self

Returns the “default value” for a type.