;-- TIME_STAMP   2022-12-29 14:15:44   v 0.1

;===================================================================================================
; Function Name .: _DefineDosDevice($_sTargetPath='', $_sDeviceName='', $_iActionFlag=0)
; Description ...: Creates or removes a Virtual Drive or lists existing drives. The Drive will be romved automatically on shutdown.
; Parameter(s) ..: $_sTargetPath    Path to link the driveletter to
;                                       Create: with "" link to @MyDocumentsDir (default)
;                  $_sDeviceName    Driveletter of the Drive to create / delete,
;                                       Create: with "" the first free drive letter - starts with "E:" - is used (default)
;                                       Delete: pass "" - the path connected with the driveletter will be found automatically.
;                  $_iActionFlag    0 = Creation (default)
;                                   1 = Deletion of the Drive
;                                   2 = Return an array of dos drives, if available; [0][0]=counter, [['drive','path']]
; Return Value(s): Success          Driveletter of the created/deleted virtual Drive or array with found dos drives
;                  Failure          0   @error=1 wrong action flag
;                                       @error=2 wrong drive letter     @extended: 1=no free drive letter available; 2=drive letter already exists
;                                       @error=3 no valid path to link to
;                                       @error=4 action failed
;                                       @error=5 no valid drive to delete
; Author(s)      : BugFix (autoit@bug-fix.info)
; Note           : The function corrects incorrect entries for drive and path specifications.
;                  Thus "c:\folder1\folder2\" and "f" are evaluated as correct entries.
; Requires       : AutoIt stable min. 3.3.16.1
;===================================================================================================
Func _DefineDosDevice($_sTargetPath='', $_sDeviceName='', $_iActionFlag=0)
    If $_iActionFlag < 0 Or $_iActionFlag > 2 Then Return SetError(1,0,0)
    $_sTargetPath = $_sTargetPath = '' ? @MyDocumentsDir : StringRegExpReplace($_sTargetPath, '\\$', '')
    $_sDeviceName = $_sDeviceName <> '' ? (StringRegExpReplace(StringLower($_sDeviceName), ':*$', '') & ':') : ''
    Local $aDrives, $ret
    Switch $_iActionFlag
        Case 0                          ; create new dos device
            If $_sDeviceName = '' Then  ; get next free drive letter
                $aDrives = DriveGetDrive("ALL")
                Local $mDrives[]
                For $i = 1 To UBound($aDrives) -1
                    $mDrives[StringLeft($aDrives[$i],1)] = 1
                Next
                For $j = 101 To 122
                    If Not MapExists($mDrives, Chr($j)) Then
                        $_sDeviceName = Chr($j) & ':'
                        ExitLoop
                    EndIf
                Next
                If $_sDeviceName = '' Then Return SetError(2,1,0)
            Else                        ; check if passed drive letter exists
                If FileExists($_sDeviceName) Then Return SetError(2,2,0)
            EndIf
            If Not FileExists($_sTargetPath) Then Return SetError(3,0,0)
            $ret = DllCall('kernel32.dll', 'long', 'DefineDosDeviceA', _
                           'long', 0x0, 'str', $_sDeviceName, 'str', $_sTargetPath)
            Return SetError(($ret[0]=0?4:0), 0, ($ret[0]<>0?$_sDeviceName:0))

        Case 1                          ; determine the path associated with the drive to be deleted
            $ret = DllCall("kernel32.dll", "long", "QueryDosDeviceA", "str", $_sDeviceName, "str", "", "long", 260)
            If $ret[0] = 0 Then
                Return SetError(4,0,0)
            Else
                $_sTargetPath = StringRegExpReplace($ret[2], '(\W*)([a-zA-Z].*)', '$2')
                If Not FileExists($_sTargetPath) Then Return SetError(5,0,0)
                $ret = DllCall('kernel32.dll', 'long', 'DefineDosDeviceA', _
                               'long', 0x2, 'str', $_sDeviceName, 'str', $_sTargetPath)
                Return SetError(($ret[0]=0?4:0), 0, ($ret[0]<>0?$_sDeviceName:0))
            EndIf

        Case 2                          ; array of existing dos devices, [0][0]=counter, [['drive','path']]
            $aDrives = DriveGetDrive('FIXED')
            Local $aOut[27][2] = [[0]]
            For $i = 1 To UBound($aDrives) - 1
                $ret = DllCall("kernel32.dll", "long", "QueryDosDeviceA", "str", $aDrives[$i], "str", "", "long", 260)
                Local $path = StringRegExpReplace($ret[2], '(\W*)([a-zA-Z].*)', '$2')
                If StringRegExp($path, '[a-zA-Z]:.*') Then
                    $aOut[0][0] += 1
                    $aOut[$aOut[0][0]][0] = $aDrives[$i]
                    $aOut[$aOut[0][0]][1] = $path
                EndIf
            Next
            ReDim $aOut[$aOut[0][0]+1][2]
            Return $aOut
    EndSwitch
EndFunc