DOKAN ADA BINDINGS
version 2.0
by Dmitry A. Kazakov
(mailbox@dmitry-kazakov.de)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

As a special exception, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.

Dokan is a user-space file system for Windows 32- and 64-bit. It consists of a driver and a library. The driver routes the I/O requests to the file system device to the library callback.

The software provided here is Ada bindings to the Dokan library. The bindings consist of thin and thick parts. The thin bindings closely follow the Dokan library entry points. As such they are very uncomfortable. The thick binding provide a higher-level access to the Dokan library. It is kept conform to the Ada 95, Ada 2005, Ada 2012 language standards.

Source distribution

dokan_2_0.tgz (tar + gzip)

See also changes log.

1. Thick bindings

The thick bindings are provided by the package Dokan.File_System.

1.1. File system

The type Abstract_File_System declared in Dokan.File_System represents a mounted instance of a file system, e.g. a volume:

type Abstract_File_System is
   abstract new Ada.Finalization.Limited_Controlled with private;
type Abstract_File_System_Ptr is access Abstract_File_System'Class;

The following operations are defined on it:

procedure Create_Directory
          (  System    : in out Abstract_File_System;
             Name      : LPCWSTR;
             Caller    : HANDLE;
             Directory : out Abstract_Directory_Ptr;
             Error     : out Error_Code
          )  is abstract;

This procedure is called to create a directory. When the directory already exists ERROR_ALREADY_EXISTS is returned, which is not a fault. Name is the directory path (UTF-16). Caller is an  access token of the process creating the directory. Directory is the directory object created. It is not null if the operation was successful. Error is the result Windows error code. Successful completion may return ERROR_SUCCESS or ERROR_ALREADY_EXISTS. When the file exists and is not a directory ERROR_DIRECTORY is returned.

procedure Create_File
          (  System         : in out Abstract_File_System;
             Name           : LPCWSTR;
             Caller         : HANDLE;
             Desired_Access : NT_Access;
             Sharing        : File_Sharing_Mode;
             Disposition    : File_Open_Mode;
             Options        : File_Options;
             File           : out Abstract_Node_Ptr;
             Error          : out Error_Code
          )  is abstract;

This procedure is called to create a new file or open and an existing one. Name is the file path (UTF-16). Caller is an  access token of the process creating the file. Desired_Access is the file access mode containing Windows access mask with bits like FILE_READ_DATA or FILE_READ_ATTRIBUTES. The parameter Sharing of Create_File specifies the file sharing mode. It can be an or-combination of sharing modes. It has the type:

type File_Sharing_Mode is mod 2**3;
Shared_Read   : constant File_Sharing_Mode := 2**0;
Shared_Write  : constant File_Sharing_Mode := 2**1;
Shared_Delete : constant File_Sharing_Mode := 2**2;

The function Image:

function Image (Mode : File_Sharing_Mode) return String;

returns textual representation of Mode. The parameter Disposition the file disposition. It is an enumeration type:

type File_Open_Mode is
     (  Overwrite,
        Create_New,
        Open_Or_Create,
        Open_Existing,
        Truncate
     );

The function Image:

function Image (Mode : File_Open_Mode) return String;

The following table specifies the behavior of Create_File depending on whether the file exists:

The parameter Options specifies file opening options. It has the type:

type File_Options is mod 2**5;
Delete_On_Close   : constant File_Options := 2**0;
Write_Trough      : constant File_Options := 2**1;
Sequential_Scan   : constant File_Options := 2**2;
Random_Access     : constant File_Options := 2**3;
Overlapped_Access : constant File_Options := 2**4;

File is a pointer the newly created file object. When the operation fails it should be null. Otherwise it will be freed. The returned object is owned by the bindings. It will be freed when the file is closed. Error is the result Windows error code. The error code is negative when the operation has failed. It is zero on success and positive on warnings or additional information. When the path specifies a directory the implementation should fail with, e.g. with ERROR_INVALID_ACCESS.

procedure Do_Unmount
          (  System : in out Abstract_File_System
          )  is abstract;

This procedure is called when file system is being dismounted.

procedure Enable_Tracing
          (  System : in out Abstract_File_System;
             On     : Boolean
          );

This is used to enable or disable tracing in the bindings. Errors are always traced. When enabled by this procedure more tracing is done. Note that the Dokan library has tracing of its own. Dokan tracing is enabled when the volume is mounted. See also Get_Tracing.

procedure Finalize (System : in out Abstract_File_System);

This procedure is called upon object finalization. It dismounts the file system instance. Note that any derived type shall call this procedure from its implementation of Finalize when it overrides Finalize.

function Get_File_System_Flags
         (  System : Abstract_File_System
         )  return File_System_Flags is abstract;

This function returns the file system flags of the type File_System_Flags. See description of the Windows function GetVolumeInformation for further information.

function Get_File_System_Name
         (  System : Abstract_File_System
         )  return String is abstract;

This function returns the file system name in UTF-8 encoding. It can be any descriptive name.

function Get_Maximal_File_Length
         (  System : Abstract_File_System
         )  return Natural is abstract;

The function returns the maximal number of characters supported for a file name. Note that the value is in characters, not in bytes. The default implementation returns the value MAX_PATH.

function Get_Tracing (System : Abstract_File_System) return Boolean;

This function returns true if tracing is enabled. See also Enable_Tracing.

function Get_Volume_Name
         (  System : Abstract_File_System
         )  return String is abstract;

This function returns the file system volume name in UTF-8 encoding.

function Get_Volume_Serial_Number
         (  System : Abstract_File_System
         )  return String is abstract;

This function returns the volume serial number.

procedure Get_Volume_Space
          (  System    : in out Abstract_File_System;
             Caller    : HANDLE;
             Total     : out Byte_Count;
             Free      : out Byte_Count;
             Available : out Byte_Count
          );

This procedure is called to get file system statistics. Caller is an  access token of the process requesting the file system space. The result may depend on the process if quotas are active, e.g. Available which is the number of bytes available for the user.

procedure Open_Directory
          (  System     : in out Abstract_File_System;
             Name       : LPCWSTR;
             Caller     : HANDLE;
             Directory  : out Abstract_Directory_Ptr;
             Error      : out Error_Code
          );

This procedure is called to open a directory. Caller is an  access token of the process opening the directory. Directory points to the newly created object of the type Abstract_Directory, or null upon failure. The directories are opened in order to list files in. Error is the result Windows error code. The default implementation sets ERROR_ACCESS_DENIED in Error and null in Directory.

procedure Move
          (  System     : in out Abstract_File_System;
             Process_ID : ULONG;
             Old_Name   : LPCWSTR;
             New_Name   : LPCWSTR;
             Replace    : Boolean;
             Error      : out Error_Code
          );

This procedure is called to rename a file or directory. Old_Name is the path of the file or directory to rename (UTF-16). New_Name is the new path (UTF-16). Replace is true if the operation is allowed to replace any existing files or directories. When Replace is false, then an attempt to replace an existing file must fail with ERROR_FILE_EXISTS. Error is the result Windows error code. The default implementation fails with ERROR_INVALID_NAME.

procedure Mount
          (  System      : in out Abstract_File_System;
             Mount_Point : String;
             Options     : Option_Type := 0;
             Threads     : Boolean     := True;
             Timeout     : Duration    := 2.0
          );

The file system is initially not mounted. In order to mount it this procedure must be called. Mount_Point is the mounting point of the file system, e.g. a device letter like L:. Options is a combination of the Dokan library options defined in the package Dokan.Thin:

• Debug enables Dokan debugging messages;
• Stderr  does output onto standard error;
• Alt_Stream uses alternate stream;
• Keep_Alive uses auto unmount;
• Network uses network drive, requires Dokan network provider;
• Removable the drive is removable.

When Threads is true, the file system operations are called concurrently from several system threads. In that case the implementation must protect the internal data from corruption. Additionally each instance of the file system runs a task that dispatches requests to the system. The task and threads are completed when the object is finalized. Timeout is the time to wait until the system becomes mounted, if less or equal to zero the procedure ends without waiting. Use_Error is propagated when the file system is already mounted. Status_Error is propagated when there is no response from the dispatcher task.

procedure Trace
          (  System : in out Abstract_File_System;
             Text   : String
          );
procedure Trace
          (  System : in out Abstract_File_System;
             Text   : String;
             Error  : Exception_Occurrence
          );
procedure Trace
          (  System : in out Abstract_File_System;
             Text   : String;
             Name   : LPCWSTR
          );
procedure Trace
          (  System : in out Abstract_File_System;
             Text   : String;
             Name   : LPCWSTR;
             Error  : Exception_Occurrence
          );

This procedures are used to trace actions and errors. The default implementations do nothing.

procedure Unmount (System : in out Abstract_File_System);

This procedure is called to explicitly dismount the file system. Ultimately it calls to the abstract procedure Do_Unmount which actually does the work. The operation may take considerable time depending on the circumstances.

1.2. Abstract node

Abstract node represents an open file or directory of the file system. It is the abstract parent type for both files and directories:

type Abstract_Node is abstract
   new Ada.Finalization.Limited_Controlled with private;
type Abstract_Node_Ptr is access Abstract_Node'Class;

There is no need to check access rights in the implementations of the operation defined on the type and its descendants because normally access rights are checked before the file or directory is opened. The following operations are defined on the type:

procedure Check_Delete
          (  File   : in out Abstract_Node;
             Name   : LPCWSTR;
             System : in out Abstract_File_System;
             Error  : out Error_Code
          )  is abstract;

This procedure is called to verify if a file or directory can be deleted. When it is a non-empty directory is not empty the operation fails with ERROR_DIR_NOT_EMPTY. Name is the file or directory path (UTF-16). Error is the result Windows error code. The result is ERROR_SUCCESS when the file or directory can be deleted. The operation does not delete anything the file or directory will be actually deleted upon a call to Delete when the file or directory is closed.

procedure Delete
          (  File   : in out Abstract_Node;
             Name   : LPCWSTR;
             System : in out Abstract_File_System
          )  is abstract;

This procedure is called to actually delete a file or directory after it was checked by a call to Check_Delete. Normally the operation should not fail because it was already checked. Name is the directory path (UTF-16).

procedure Close
          (  File   : in out Abstract_Node;
             Name   : LPCWSTR;
             System : in out Abstract_File_System'Class;
             Delete : Boolean;
             Error  : out Error_Code
          )  is abstract;

This procedure is called when an open file or directory is closed. Name is the file or directory path (UTF-16). System is the file system the file or directory is located on. Delete is true if the file or directory is must be deleted. Typically it would call Delete. Error is the result Windows error code.

procedure Close
          (  File   : in out Abstract_Node;
             System : in out Abstract_File_System'Class;
             Error  : out Error_Code
          )  is abstract;

This variant of the procedure Close is called when the file remains open until dismounting the file system. In this case the file must be closed unconditionally. Error is the result Windows error code. The error code is ignored because there is no way to handle it.

procedure Finalize (File : in out Abstract_Node);

This procedure is called upon finalization of the object. If overridden the new implementation must call to the parent's one.

procedure Get_Information
          (  File       : in out Abstract_Node;
             Name       : LPCWSTR;
             System     : in out Abstract_File_System'Class;
             Attributes : out DWORD;
             Created    : out FILETIME;
             Accessed   : out FILETIME;
             Written    : out FILETIME;
             Size       : out Byte_Count;
             Links      : out DWORD;
             Index      : out File_Index;
             Error      : out Error_Code
          )  is abstract;

This procedure is called to obtain information about a file or directory. Name is the file or directory path (UTF-16). System is the file system the file or directory is located on. Error is the result Windows error code. For time conversions see From_Time and To_Time.

procedure Get_Security
          (  File       : in out Abstract_Node;
             Name       : LPCWSTR;
             System     : in out Abstract_File_System;
             Security   : SECURITY_INFORMATION;
             Descriptor : PSECURITY_DESCRIPTOR;
             Length     : in out ULONG;
             Error      : out Error_Code
          );

This procedure is called to obtain file or directory security descriptor. Name is the file or directory path (UTF-16). System is the file system the file or directory is located on. Security specifies the parts of the security descriptor requests. Descriptor is a pointer to the buffer to receive the descriptor. Note that its actual length is specified by the parameter Length. It can be different from the nominal length of the type SECURITY_DESCRIPTOR as declared in Dokan.Win32API. When Descriptor is null or is too small, the procedure fails with one of ERROR_NOT_ENOUGH_MEMORY,  ERROR_INSUFFICIENT_BUFFER, ERROR_MORE_DATA and sets the number of required bytes into Length. Upon success it must fill the buffer with the requested information in the so-called self-relative format and set Length to the actual length. Error is the result Windows error code.The package Dokan.Win32API provides a helper function CreateSecurity to ease creation of a security descriptor for newly created files and directories. The default implementation fails with ERROR_INVALID_FUNCTION in which case Dokan would use a default descriptor. See also Set_Security.

procedure Set_Attributes
          (  File       : in out Abstract_Node;
             Name       : LPCWSTR;
             System     : in out Abstract_File_System;
             Attributes : DWORD;
             Error      : out Error_Code
          );

This procedure is called to change file or directory attributes. The attribute values are combinations of constants starting with FILE_ATTRIBUTE_*. The bit FILE_ATTRIBUTE_NORMAL is ignored when used with other bits. Name is the file or directory path (UTF-16). System is the file system the file or directory is located on. Attributes is the file attributes to set. Error is the result Windows error code. The default implementation fails with ERROR_INVALID_DATA.

procedure Set_File_Time
          (  File       : in out Abstract_Node;
             Name       : LPCWSTR;
             System     : in out Abstract_File_System;
             Created    : FILETIME;
             Accessed   : FILETIME;
             Written    : FILETIME;
             Error      : out Error_Code
          );

This procedure sets the file or directory times. Name is the file or directory path (UTF-16). System is the file system the file or directory is located on. Attributes is the file attributes to set. File times must be ignored if they have values (0, 0). Error is the result Windows error code. The default implementation fails with ERROR_ACCESS_DENIED. For time conversions see From_Time and To_Time.

procedure Set_Security
          (  File       : in out Abstract_Node;
             Name       : LPCWSTR;
             System     : in out Abstract_File_System;
             Security   : SECURITY_INFORMATION;
             Descriptor : SECURITY_DESCRIPTOR;
             Error      : out Error_Code
          );

This procedure modifies the file or directory security. Name is the file or directory path (UTF-16). System is the file system the file or directory is located on. Security specifies the contents of the security descriptor specified by the parameter Descriptor. Typically an implementation would modify the file security using these parameters. Error is the result Windows error code. The default implementation fails with ERROR_INVALID_FUNCTION. See also Get_Security.

1.3. Abstract directory

Abstract directory represents an open directory on the file system:

type Abstract_Directory is abstract
   new Abstract_Node with private;
type Abstract_Directory_Ptr is access Abstract_Directory'Class;

The following operations are defined on the type:

procedure Finalize (Directory : in out Abstract_Directory);

This procedure is called upon finalization of the object. If overridden the new implementation must call to the parent's one.

procedure Find
          (  Directory : in out Abstract_Directory;
             Name      : LPCWSTR;
             System    : in out Abstract_File_System'Class;
             Fill      : FillFileData_Ptr;
             Info      : File_Info_Ptr;
             Error     : out Error_Code
          )  is abstract;

This procedure is called to enumerate files in the directory. Name is the directory path (UTF-16). System is the file system the file or directory is located on. Fill is the procedure to call for each file found in the directory.  Fill is declared as follows:

type FillFileData_Ptr is access function
     (  Data : WIN32_FIND_DATAW;
        Info : File_Info_Ptr
     )  return int;
pragma Convention (Stdcall, FillFileData_Ptr);

Info is the value to pass to Fill. Its type is declared in Dokan.Thin. Here Data is the Windows data structure to filled with the file data. Info is the corresponding parameter passed to Find. The result is non-zero if the enumeration of files must be stopped. Error is the result Windows error code.

1.4. Abstract file

Abstract file represents an open file on the file system:

type Abstract_File is abstract
   new Abstract_Node with private;
type Abstract_File_Ptr is access Abstract_File'Class;

The following operations are defined on the type:

procedure Finalize (File : in out Abstract_File);

This procedure is called upon finalization of the object. If overridden the new implementation must call to the parent's one.

procedure Flush
          (  File   : in out Abstract_File;
             Name   : LPCWSTR;
             System : in out Abstract_File_System'Class;
             Error  : out Error_Code
          );

This procedure is called to flush all file buffers. Name is the file path (UTF-16). System is the file system the file or directory is located on. Error is the result Windows error code. The default implementation fails with ERROR_WRITE_FAULT.

procedure Lock
          (  File        : in out Abstract_File;
             Name        : LPCWSTR;
             System      : in out Abstract_File_System'Class;
             Byte_Offset : Byte_Count;
             Length      : Byte_Count;
             Error       : out Error_Code
          );

This procedure is called to lock a portion of the file. Name is the file path (UTF-16). System is the file system the file or directory is located on. Byte_Offset is the first byte to lock (zero-based). Length is the number of bytes to lock. Error is the result Windows error code. The default implementation fails with ERROR_INVALID_FUNCTION.

procedure Read
          (  File   : in out Abstract_File;
             Name   : LPCWSTR;
             System : in out Abstract_File_System'Class;
             Buffer : Storage_Pointers.Pointer;
             Length : in out Storage_Count;
             Offset : Byte_Count;
             Error  : out Error_Code
          );

This procedure is called to read a portion of the file. Name is the file path (UTF-16). System is the file system the file or directory is located on. Buffer is the read buffer pointer. The buffer is a C-compatible pointer to array of Storage_Elements:

package Storage_Pointers is
   new Interfaces.C.Pointers
       (  Index              => Storage_Offset,
          Element            => Storage_Element,
          Element_Array      => Storage_Array,
          Default_Terminator => 0
       );

Length is the buffer length in storage elements. After successful read it is set to the number of actually read elements. Offset is the first byte to read (zero-based). Error is the result Windows error code. The default implementation fails with ERROR_READ_FAULT.

procedure Write
          (  File   : in out Abstract_File;
             Name   : LPCWSTR;
             System : in out Abstract_File_System'Class;
             Buffer : Storage_Pointers.Pointer;
             Length : in out Storage_Count;
           [ Offset : Byte_Count; ]
             Error  : out Error_Code
          );

This procedure is called to write a portion of the file. Name is the file path (UTF-16). System is the file system the file or directory is located on. Buffer is the write buffer pointer. Length is the buffer length in storage elements. After successful read it is set to the number of actually written elements. Offset is the first byte to write (zero-based). When omitted, the file is written starting at the file end. Error is the result Windows error code. The default implementation fails with ERROR_WRITE_FAULT.

procedure Set_Allocation_Size
          (  File   : in out Abstract_File;
             Name   : LPCWSTR;
             System : in out Abstract_File_System'Class;
             Size   : Byte_Count;
             Error  : out Error_Code
          );

This procedure truncates or extends space used by the file. Name is the file path (UTF-16). System is the file system the file or directory is located on. Size is the new file size in bytes. Error is the result Windows error code. The default implementation fails with ERROR_WRITE_FAULT.

procedure Set_End_Of
          (  File   : in out Abstract_Directory;
             Name   : LPCWSTR;
             System : in out Abstract_File_System'Class;
             Length : Byte_Count;
             Error  : out Error_Code
          );

This procedure is called to set the file end. Name is the file path (UTF-16). System is the file system the file or directory is located on. Length is the new file length in bytes. Error is the result Windows error code. The default implementation fails with ERROR_WRITE_FAULT.

procedure Unlock
          (  File        : in out Abstract_Directory;
             Name        : LPCWSTR;
             System      : in out Abstract_File_System'Class;
             Byte_Offset : Byte_Count;
             Length      : Byte_Count;
             Error       : out Error_Code
          );

This procedure is called to unlock a portion of the file. Name is the file path (UTF-16). System is the file system the file or directory is located on. Byte_Offset is the first byte to unlock (zero-based). Length is the number of bytes to unlock. Error is the result Windows error code. The default implementation fails with ERROR_INVALID_FUNCTION.

1.5. Utility operations

The package Dokan.File_System provides the following utility operations:

function Create_Default_Security_Descriptor
         (  Caller       : HANDLE;
            Is_Directory : Boolean;
            Parent       : access SECURITY_DESCRIPTOR := null;
            Descriptor   : out PSECURITY_DESCRIPTOR;
            Error        : out Error_Code
         );

This function creates a security descriptor for a newly created file or directory. Caller is access token of the process creating the file or directory. This is the parameter Caller of Create_File, for example. Is_Directory is true for a new directory. Parent is the security descriptor of the container directory. It is optional. Descriptor is a new descriptor allocated on successful completion. It must be freed using LocalFree if no more needed. Note that operations modifying descriptors reallocate them in the local heap. Error is the result. Descriptor is allocated only if Error is set to ERROR_SUCCESS.

function From_Time (Stamp : Time) return FILETIME;

This function converts Ada calendar's time to Windows' FILETIME. Time_Error is propagated on conversion errors.

function From_UTF8_String (Text : String) return Wide_String;

This function converts an UTF-8 encoded string to UTF-16 equivalent.

function Get_Error_Text (Code : Error_Code) return String;

This function gets Windows' error message text corresponding to Code.

function To_Time (Stamp : FILETIME) return Time;

This function converts Windows' FILETIME to Ada calendar's time. Time_Error is propagated on conversion errors.

function To_UTF8_String
         (  Text      : LPCWSTR;
            Normalize := True
         )  return String;
function To_UTF8_String
         (  Text      : Wide_String;
            Normalize := True
         )  return String;

These functions convert an UTF-16 encoded string to UTF-8 equivalent. It also normalizes Text by replacing '/' with '\' when Normalize is true.

type File_System_Lock (System : access Abstract_File_System'Class) is
   new Ada.Finalization.Limited_Controlled with private;
procedure Finalize   (Lock : in out File_System_Lock);
procedure Initialize (Lock : in out File_System_Lock);

An object of this type is created in a context where the file system must be locked for exclusive access. The locking is reentrant. The same task can create several such objects. Initialization of the object is blocked if another task has already created its own object. Finalization of the object releases other task if it was the last object created by the task.

1.6. Windows API

The package Dokan.Win32API defines a portion of Windows API. The following important data types are used throughout of bindings:

type Error_Code is new DWORD;

The type Error_Code is used in all operations implementing the file system to report the outcome. The child package Dokan.Win32API.Error_Codes defines major Windows error code constants.

type File_System_Flags is new DWORD;

Values of the type File_System_Flags describe properties of a file system.

type FILETIME is record
   LowDateTime  : DWORD;
   HighDateTime : DWORD;
end record;

Values of the type FILETIME describe Windows UTC file time stamp.

function Image
         (  Date         : FILETIME;
            Milliseconds : Boolean := False;
            UTC          : Boolean := False
         )  return String;

This function returns time stamp representation in the format YYYY-MM-DD HH:MM:SS.mmm. When Milliseconds is false, no seconds fraction appear. When UTC is true the output is the Coordinated Universal Time.

type LPCWSTR is access constant Wide_Character;
type LPWSTR  is access all Wide_Character;

The operations use the types LPCWSTR and LPWSTR for the file names. File names are NUL-terminated  UTF-16 encoded when communicating with the Dokan library. Everywhere outside that more convenient UTF-8 is used. The names are not converted from UTF-16 to UTF-8 to avoid unnecessary overhead. The implementation may choose the encoding it suits best. The utility operations To_UTF8_String and From_UTF8_String are provided for conversions between these encodings.

type NTSTATUS is new DWORD;

The type NTSTATUS is used when communicating with the kernel operations. The child packages Dokan.Win32API.NTSTATUS_Codes defines kernel status codes.

type NT_Access is new DWORD;

The type NT_Access corresponds to the Windows access mask with bits like FILE_READ_DATA or FILE_READ_ATTRIBUTES.

function Image (Access_Mask : NT_Access) return String;

This function is used to convert a mask into a human-readable form.

function DestroyPrivateObjectSecurity
         (  Object : access PSECURITY_DESCRIPTOR
         )  return BOOL;

This function frees security descriptor object and zeroes its pointer.

function Check
         (  Token          : HANDLE;
            Descriptor     : PSECURITY_DESCRIPTOR;
            Desired_Access : NT_Access;
            Mapping        : GENERIC_MAPPING := File_Access_Mapping
         )  return Error_Code;

This function checks if the process access token Token has access specified in Desired_Access according to the security descriptor Descriptor. When Descriptor is null access is granted. The result is ERROR_SUCCESS if the access is granted. Mapping specifies mapping of generic access modes to the specific file access modes.

type HANDLE_Holder is
   new Ada.Finalization.Limited_Controlled with
record
   Resource : aliased HANDLE := HANDLE (System.Null_Address);
end record;

The type HANDLE_Holder is used to hold an open HANDLE. Its finalization closes the handle.

2. Samples

2.1. Memory-resident file system

The package Memory_FS provides a simplified sample implementation of a memory-resident file system. The implementation uses Simple Components for Ada, which is required for building the sample.

The package Memory_FS is located in the subdirectory example/memory-fs:

The Memory_File_System type is derived from Abstract_File_System.

Here a two utility operations are defined for debugging purpose. The procedure Set_Trace_File redirects trace output to a specific file when the parameter File_Name is present or to the standard output, if omitted.

This procedure is used to redirect tracing to the standard error. It can be useful in combination with the Dokan debug standard error output.

In the private part of the package the abstract base type of the file system nodes is defined. A node is either a file or a directory. The type Node is abstract and derived from Object.Enity in order to provide reference counting collection. The fields of Node are access times, attributes and the security descriptor to handle file access checks.

 The abstract operation Create_Security is used to create security descriptor for a file or directory.

 The abstract operation Get_Size_Unlocked is defined to return the file system space allocated for a node.

 The initialization and finalization operations common for all nodes.

Here the generic package Object.Handle is instantiated to provide handles to the node objects. When the last handle to a node disappears the node is deleted.

 Here case-insensitive tables of handles to the files system nodes is defined through instantiation of the generic package Tables.UTF8_Names. The package requires two subroutines:

• Check_Spelling in order to check name legality;
• Check_Matched to check the name end in a stream of characters.

The implementation of Check_Spelling checks if its string parameter is a valid Windows file name. Check_Matched verifies if name is not followed by a letter, digit or any other legal file name character.

The type Folder_Node represents a file system directory. It is derived from Node and contains a table of files from the directory. The table type is defined by the instance of Tables.UTF8_Names.

Here we override operations for the type Folder_Node.

An instance of Generic_Unbounded_Array serves as a container of file contents. The array is indexed by Storage_Offset and contains Storage_Elements. A more sophisticated implementation could use non-contiguous storage allocation schema.

Here a file system plain file node is defined. The node has current file length (Length component) and file contents (Data of Unbounded_Array).

Here we override operations for the type Folder_Node.

Now the file system itself is defined. It has the components:

• Root is a handle to the root directory of the file system;
• Into_File is true when tracing is done into a file;
• Trace_File is the trace file.

Here some of the abstract operations of the base type are overridden.

This utility function is used internally to decompose a file path into a handle to the parent's directory and simple file name. Name is the file path UTF-16 encoded. Parent is the output handle for the directory part. Check is true when the file simple name must be checked. The function returns the simple name. Constraint_Error is propagated when the name is illegal. End_Error is propagated when a parent directory does not exist. Name_Error is propagated when a parent is not a directory.

This is a simplified version of find used when an existing file should be searched for. Name is the file path UTF-16 encoded. File is a handle to the file specified. Error is the Windows error code set according to the search outcome.

Here is another portion of primitive operations gets overridden.

Memory_File is an implementation of Abstract_File which serves as a proxy to an open file system file. An object has the components:

• Reference is a handle to the file object;
• Mode is the file access mode.

The primitive operations of Abstract_File are overridden here.

Memory_Folder is an implementation of Abstract_Directory which serves as a proxy to an open file system directory. An object keeps a handle to the file system directory object.

This overrides operations of Abstract_Directory.

The implementation of the package Memory_FS follows.

The constant Supported_Attributes defines the file attributes we allow to set.

This function is used to output node address when tracing it done.

This function checks of a directory can be deleted. First the file system is locked. Then function Find is called to split the file name into its name Simple and a handle to the directory node Parent. which is then dereferenced as This. If there is no parent End_Error is propagated.

The parent directory is searched for the file name and checks if that is indeed the directory. If there is no such file ERROR_FILE_NOT_FOUND is the result.

When the file is found, its handle is dereferenced. If it is a plain file its access is checked using the procedure Check for having full access.

When it is a directory and it is temporary or else empty the result is ERROR_SUCCESS. Otherwise the result is ERROR_DIR_NOT_EMPTY.

Finally, exceptions are converted into the corresponding error codes.

The implementation checks if the file indeed exist.

The completion is same as in Check_Delete for a directory.

The implementation checks if any of the forbidden characters follows the name, this is Source (Pointer). In this case the name can ends at Pointer and the returned value is true. Otherwise, the result is false.

The implementation of Check_Spelling raises Contraint_Error if the name contains a control character or else one of <, >, :, ", /, \, |, ?, *.

The implementation of closing file starts with casting the file system to Volume, accessing the file object as This  and finally locking the file system.

When the parameter Delete is true the file is deleted.

When the file is to stay the time stamp Accessed is set to the current time. The utility function From_Time is used to convert Ada.Calendar.Time to Windows' FILETIME. If the file was open for writing the time stamp Written is also set.

This variant of closing is called when the file system is dismounted. There is nothing to do because all file system will be destroyed anyway.

The implementation of closing directory is same as for a file.

This variant of closing is called when the file system is dismounted. It is same as for closing file.

The implementation of directory creation starts with searching for the directory parent using the function Find and getting the directory name. After that the directory name is checked using Check_Spelling.

Here we get the parent node object and locate the specified name in the table of its children (the component Data). The result is zero if there is no child with this name.

The procedure Set_Directory is a helper program that sets the result Directory. It creates an instance of Memory_Folder and initializes its member Reference to the directory object. That will hold the directory until it stays open.

Since there is no child with the specified name. In order to create a new directory node we check if we have write rights on the parent directory using the procedure Check. If not we return with the reported access error.

After successful checking access rights, we create directory node and add it into the parent's table of children.

Here we create the security descriptor for the newly created directory.

Finally, some tracing is done and the helper procedure Set_Directory defined previously is called to set the result Directory.

A child with this name indeed exists so we check if it is a directory.

The file is a directory, so we check if we have read access to it with the procedure Check. Without read access we immediately return.

Then we trace opening directory, call the helper procedure Set_Directory defined previously is called to set the result Directory and return ERROR_ALREADY_EXISTS which is not error.

There is already a child with this name which is not a directory so we return ERROR_DIRECTORY.

Finally we catch exceptions propagating on invalid name, non-existing parent, wrong parent name and return corresponding error codes.

The implementation of file creation must be able both to create a new file or to open an existing file. It starts with finding the file parent directory and getting the file name.

Sometimes Windows uses file names containing wild-cards * and ?. Here we check if the name contains any of them and set the variable Pattern to true.

 Here we get the parent directory node. Item is a handle to the result.

When Find returns an empty file name we are in the root directory. We set the directory flag and check the directory disposition:

Here is the case when the root directory is to be opened or created when does not exist. The root directory access is checked with the procedure Check. ERROR_ALREADY_EXISTS will be returned later to indicate that an existing file is opened.

Here the root directory is opened only if exists. The access is checked with Check and ERROR_SUCCESS is set for later.

Opening to overwrite is rejected with ERROR_ACCESS_DENIED.

Creating new is rejected with ERROR_ALREADY_EXISTS. Note that since the parameter File is null, it is treated as error.

Finally Item is set to the root directory.

When the name contains wild-cards we go through all children and look for the first child which name is matched by the pattern. For matching the function IsNameInExpression from the thin Dokan bindings is used. Dokan uses UTF-16 encoding. Note how the name is converted to UTF-16 using From_UTF8_String. Note also that NUL must be added to the name to make it working. When a child is found Offset is the child's position in the children table of the parent directory node. When no child is found Offset is zero.

When the name contains no wild-cards we search the children table for the name. Again Offset is the child position in the table or zero.

When there is no child with the name, so we are to create the file. First we check the Disposition parameter.

When Disposition is Overwrite or Create_New, Create_New or Open_Or_Create, we will create file.

When Disposition is Open_Existing or Truncate, the implementation faults with code ERROR_FILE_NOT_FOUND.

Here we check the parent directory with Check for write access.

Now we create the new file, insert it into the parent directory This and create its security descriptor. Item is a handle to the new file handle. Finally some tracing is done.

When there is a child with the name Item set to point to the child's node. The node is checked for being a directory and Directory is set. Then the Disposition parameter is checked:

When Disposition is Open_Or_Create the result will be ERROR_ALREADY_EXISTS.

When Disposition is Open_Existing the result on success will be ERROR_SUCCESS.

When Disposition is Open_Truncate or Overwrite the result is set to ERROR_ALREADY_EXIST. Since the file is overwritten its length is set to zero, which is equivalent to truncation and overwriting.

When Disposition is Create_New the implementation fails with ERROR_ALREADY_EXISTS.

The access to the file is checked with Check against its security descriptor.

When a directory is opened an new instance of Memory_Folder is allocated.

The component Reference of Memory_Folder is set to the file system node from the variable Item and tracing is performed.

When a file is opened or create an new instance of Memory_File is allocated.

The component Reference of Memory_File is set to the file system node from the variable Item. The component Mode is set to the required access mode and tracing is performed.

Here we catch exceptions propagating on invalid name, non-existing parent, wrong parent name and return corresponding error codes.

The implementation Create_Security for a directory creates a new security descriptor by calling CreateSecurity.

The implementation Create_Security for a file creates a new security descriptor by calling CreateSecurity.

The implementation of directory deletion starts with finding the parent directory and getting the directory name.

Here the parent directory is searched for the specified directory name. Offset is zero when nothing found. Otherwise it is the position of the directory in the table of children.

When file exists and same it is deleted and the parent directory access times are modified.

Upon error nothing useful can be done.

The implementation of directory deletion starts with finding the parent directory and getting the directory name.

Here the parent directory is searched for the specified directory name. Offset is zero when nothing found. Otherwise it is the position of the directory in the table of children.

When the node is a plain file it is deleted from the table of the parent's children. The access and write times of the parent directory are updated and tracing is done.

Here we catch exceptions propagating on errors, but cannot do anything beyond tracing.

The implementation file deletion is similar to directory deletion. It starts with finding the parent directory and getting the directory name.

Here the parent directory is searched for the specified file name. Offset is zero when nothing found. Otherwise it is the position of the file in the table of children.

When no file exists the implementation fails with the code ERROR_FILE_NOT_FOUND.

When there is a file its node is accessed as File.

When the node is a plain file it is deleted by removing it from the parent's children table. The access and write times of the parent are updated.

Otherwise, when the node is a directory, the implementation fails with ERROR_ACCESS_DENIED.

Here we catch exceptions propagating on invalid name, non-existing parent, wrong parent name and return corresponding error codes.

The implementation of Do_Unmount does not requires any specific actions. The only thing it does is tracing.

Finalization of a file system node deletes it security descriptor if any.

Finalization does tracing and then calls to the parent's type implementation.

The implementation of function Find locks file system first.

The local subprogram Add is called for each found file. It returns true to indicate end of search. Size is set to calculated length of the file.

Here the file information is stored into the file search data structure.

Finally the Fill callback is called to store the file information.

The implementation of file search walks the directory files and calls Add for each of them until it returns true or there is no more files.

Here we catch exceptions propagating and return corresponding error codes.

The utility function starts with conversion UTF-16 encoded Name to UTF-8. Current is renamed handle to the parent (parameter Parent).

Parent is set to the file system root and tracing is done.

When the path is empty the parent remains root directory and file name is returned empty.

When the path starts with a slash, the slash is skipped. Start points to the beginning of a directory name. Pointer does to the current character to process. UTF-8 issues can be safely ignored because ASCII-7 characters are encoded in UTF-8 as is.

Here we are looking for the next slash indicating end of the parent directory name.

When the handle to the current node is not a directory the directory name just found cannot be its child. The implementation does tracing and raises Name_Error to indicate wrong path.

When the node is a directory, the directory name Path (Start..Pointer - 1) is searched for amount its children. Offset is zero when no child is found.

When no child exists Offset is 0 and the path is wrong and End_Error is propagated.

Otherwise, the child becomes current node. Pointer and Start are advanced behind the slash.

Characters different from slash are skipped. When the loop is existed Path (Start..Path'Last) is the file name.

If Check is true, the file name is checked.

Empty file name corresponds to the root directory.

Otherwise, Path (Start..Path'Last) is the file name.

This variant of Find searches for the specified name as a whole. It calls to Find splitting the path Name into a handle to the parent directory node and simple file name.

When file name is empty the result is the root directory.

When file name is not empty the parent's children table is searched for it. When the search was unsuccessful is fault with ERROR_FILE_NOT_FOUND. Otherwise, File is set to the child found.

Here we catch exceptions propagating on invalid name, non-existing parent, wrong parent name and return corresponding error codes.

Flush is always successful.

The implementation of Get_File_System_Flags returns flags indicating support of preserved case of file names, Unicode and then access control lists are kept by the file system.

The file system name is returned as Memory file system.

File memory_fs.adb (continuation):

 The implementation of Get_Information takes file times from the file system node. The file size is returned by the primitive operation Get_Size.

The implementation for a directory is similar. The size is zero.

The implementations call to the file system implementation that is same for files and directories.

When the security descriptor is absent, which should not happen the implementation returns ERROR_INVALID_FUNCTION to fall back to Dokan.

In case of success we use Windows' operation GetPrivateObjectSecurity to copy the descriptor into the user buffer. When it fails with ERROR_INSUFFICIENT_BUFFER we return ERROR_MORE_DATA with Length set to the required space.

The implementation of Get_Size of File_Node returns the actual size of the file.

The implementation of Get_Size of File_Folder returns recursively calculated size of all files in the directory.

The implementation of Get_Volume_Name returns RAM DISK.

 The file system serial number is 1.

The implementation of Get_Volume_Space calculates used space and returns it as total volume space. Free and available space are returned zero.

Initialization of the file system creates the root directory node and then calls to the parent type initialization.

The last step is to create the security descriptor of the root directory. For the access token the one of the calling process is used. The type HANDLE_Holder is declared to keep a handle to the process. Then the process is opened for TOKEN_QUERY access. If this fails we stop. Note that there is no error processing as it is not possible to anything reasonable in Initialize anyway.

Initialization of a file system node calls to the parent type initialization and sets file or directory times to the current time.

Initialization of a file system directory sets the directory attribute and calls to the parent's Initialize.

Initialization of a file system file sets the directory attribute to zero and calls to the parent's Initialize.

The implementation of Move renames a file. It starts with converting the old and the new file paths to UTF-8.

Both paths are split into parent and simple file name. The parents are then accessed as Old_Folder and New_Folder.

The old file is searched in its parent directory. When not found (Old_Offset is zero) the implementation fails with ERROR_FILE_NOT_FOUND.

When the old path is contained by the new path (ignoring the case) the renaming fails with ERROR_IS_SUBST_PATH as an attempt to rename directory into its own descendant.

The new file is located in its parent directory. When no such file exists (New_Offset is zero), a handle to the file system node is stored.

Then the file is removed from its parent directory and put into the new parent's directory under new name.

When there is a file with the same name and Replace is true, the old file can be replaced. The handle to the renamed file replaces the handle to the existing file in the new parent directory. This has the effect of removing the existing file or directory.

When Replace is false, the implementation fails with ERROR_FILE_EXISTS.

Exceptions propagating on invalid name, non-existing parent, wrong parent name are converted into the corresponding error codes.

The implementation of Open_Directory searches for the file specified.

When search was successful the corresponding file system node is accessed and checked for being a directory node.

When the node is a directory we access rights to traverse and read attributes.

When the node is a directory an instance of Memory_Folder is created and a reference to the directory is stored in it. Finally, some tracing is done.

When the node is a plain file, the implementation fails with the code ERROR_DIRECTORY.

The implementation of Read checks if the access mode allows Read_Access. If not the implementation fails with ERROR_ACCESS_DENIED.

If the Offset points beyond the file end the implementation fails with ERROR_HANDLE_EOF.

When the offset is within the file Count is the number of bytes available to read.

When number of available bytes is less than the buffer length we reduce Length to the number of available bytes.

Then we copy Length bytes into the buffer using standard operation from the instance of Interfaces.C.Pointers.

The implementation of Set_Allocation_Size checks if the allocated space is less than the requested size. If so expands the files by putting a zero at the index of the requested size. That will cause it to expand the container Self.Data.

The new size is set unless a memory allocation occur. In which case the result is ERROR_FILE_TOO_LARGE.

The implementation of Set_Attributes for a file when Attributes is FILE_ATTRIBUTE_NORMAL sets attributes to zero.

Otherwise if no unsupported attributs are used, the attributes are set. Note that FILE_ATTRIBUTE_NORMAL is cleaned because it is not a proper attribute.

When unsupported attributes are used, the implementation fails with ERROR_INVALID_DATA.

The implementation of Set_Attributes for a directory  when Attributes is FILE_ATTRIBUTE_NORMAL fails with ERROR_INVALID_DATA.

When no unsupported attributes are used the result is ERROR_SUCCESS unless FILE_ATTRIBUTE_DIRECTORY  is cleared.

When unsupported attributes are used, the implementation fails with ERROR_INVALID_DATA.

The implementation of Set_End_Of accesses the file node.

File memory_fs.adb (continuation):

When check was successful and the set length is larger than the file we put that last byte to extend it. If extending the unbounded array fails ERROR_FILE_TO_LARGE is returned. Finally the file length is set to Length.

The implementation of Set_File_Time for a file first locks the file system.

The file times are set unless the time stamp is not (0, 0).

The implementation of Set_File_Time for a directory is similar to the implementation for a file.

The file times are set unless the time stamp is not (0, 0).

The implementation Set_Security calls to the generic implementation of the memory file system.

The implementation Set_Security calls to the generic implementation of the memory file system.

The implementation Set_Security simply call windows SetPrivateObjectSecurity which modifies the descriptor and reallocates it if neceassry.

When a trace file is set the old trace file is closed if open. Then the new file is created.

When no trace file path is given, the existing trace file is closed if any.

When no trace file path is given, the existing trace file is closed if any.

The implementation of Trace writes into the trace file or else to the standard or error output.

This variant of trace adds file name to the trace message.

This is a variant of tracing that adds exception occurrence to the trace message.

This trace that adds file name and exception occurrence to the trace message.

The implementation of Write access the file node and checks of the write-access was granted. If not the implementation fails with ERROR_ACCESS_DENIED.

The contents of the buffer is appended to file starting from Length.

On storage error the implementation fails with ERROR_HANDLE_DISK_FULL.

This variant of Write is different that it starts at the middle of the file. The file length is set to the maximum of the old length and the end of the overwritten file part.

The test application in the subdirectory example/memory-fs/test illustrates usage of the virtual file system:

The object FS is an instance of the virtual file system. The file system is not visible until it gets mounted. Mount_Point is where the file system must be mounted at.

This activates tracing into the file trace.txt.

Here the file system is mounted, Debug and Stderr options are passed to the Dokan library.

 This awaits user input to complete test. When user hits enter the application exists and finalization of the file system object automatically dismounts the file system.

This prints unanticipated exceptions.

3. Packages

The root directory contains only the packages required for software use. The examples are located in the subdirectory example/memory_fs. The Dokan distribution is contained in the subdirectory dokan-1.1.0.

3.1. Source packages

The following table describes the packages and other compilation units provided by the software.

3.2. Tests and examples

The subdirectory example/memory_fs contains a sample of virtual memory-resident file system. The subdirectory example/memory_fs/test has the test for the memory-resident system. It mounts the system on the letter R.

4. Installation

The software provides gpr project files, which can be used in the Gnat Programming Studio (GPS):

The Dokan driver must be installed to be able to run applications using the library. The driver marshals I/O requests from the Windows kernel to the user-space library and ultimately to the application. The installation executable is DokanSetup.exe in the subdirectory dokany-2.0.0.2000.

5. Changes log

The following versions were tested with the compilers:

• GNAT Community 2018 (20180523-73)
• Dokan library 1.1.0

Changes (16 January 2022) to the version 1.5.0:

• The code and the API were reworked to accommodate the Dokan major version 2.

Changes (20 November 2021) to the version 1.1:

• The code was revised to comply with version 1.5.0.

Changes (5 Aug 2018) to the version 1.0:

• The code is completely rewritten to migrate to Dokan 1.1;
• Windows examples changed to 64-bit;
• The dependency from win32ada was removed, since it is no more included in GNAT Community. This version is  fully self-sufficient;
• The example of memory-resident file system now supports file security descriptors and performs access checks.

The following versions were tested with the compilers:

• GNAT GPL 2014 (20140331)
• Dokan library 0.6.0

First version released.

6. Table of Contents

1. Thick bindings
    1.1. File system
    1.2. Abstract node
    1.3. Abstract directory
    1.4. Abstract file
    1.5. Utility operations
    1.6. Windows API
2. Samples
    2.1. Memory-resident file system
3. Packages
    3.1. Source packages
    3.2. Test and examples
4. Installation
5. Changes log
6. Table of contents