# Function Reference

# _WinAPI_FindFirstFile

Searches a directory for a file or subdirectory with a name that matches a specific name

#include <WinAPIFiles.au3>
_WinAPI_FindFirstFile ( $sFilePath, $tData )

## Parameters

$sFilePath | The directory or path, and the file name, which can include wildcard characters, for example, an asterisk "*" or a question mark "?". If the string ends with a wildcard, period ".", or directory name, the user must have access permissions to the root and all subdirectories on the path.
$tData | A $tagWIN32_FIND_DATA structure or a pointer to it that receives information about a found file or directory.

## Return Value

Success: | The search handle.
Failure: | 0 and sets the @error flag to non-zero, @extended flag may contain the system error code.

## Remarks

This function opens a search handle and returns information about the first file that the file system finds with a name that matches the specified pattern.
This may or may not be the first file or directory that appears in a directory-listing application when given the same file name string pattern.
After the search handle is established, you can use it to search for other files that match the same pattern by using the _WinAPI_FindNextFile() function.
If the function fails because no matching files can be found, the @extended flag will contain ERROR_FILE_NOT_FOUND (2) system error code.
When the search handle is no longer needed, close it by using the _WinAPI_FindClose() function.

## Related

_WinAPI_FindClose, _WinAPI_FindNextFile

## See Also

Search FindFirstFile in MSDN Library.

## Example

    #include <Array.au3>
    #include <FileConstants.au3>
    #include <MsgBoxConstants.au3>
    #include <StructureConstants.au3>
    #include <WinAPIConv.au3>
    #include <WinAPIError.au3>
    #include <WinAPIFiles.au3>

    Local $aList[101][2] = [[0]]

    Local $tData = DllStructCreate($tagWIN32_FIND_DATA)

    Local $sFile
    Local $hSearch = _WinAPI_FindFirstFile(@ScriptDir & '\*', $tData)
    While Not @error
        $sFile = DllStructGetData($tData, 'cFileName')
        Switch $sFile
            Case '.', '..'

            Case Else
                If Not BitAND(DllStructGetData($tData, 'dwFileAttributes'), $FILE_ATTRIBUTE_DIRECTORY) Then
                    $aList[0][0] += 1
                    If $aList[0][0] > UBound($aList) - 1 Then
                        ReDim $aList[UBound($aList) + 100][2]
                    EndIf
                    $aList[$aList[0][0]][0] = $sFile
                    $aList[$aList[0][0]][1] = _WinAPI_MakeQWord(DllStructGetData($tData, 'nFileSizeLow'), DllStructGetData($tData, 'nFileSizeHigh'))
                EndIf
        EndSwitch
        _WinAPI_FindNextFile($hSearch, $tData)
    WEnd

    Switch @extended
        Case 18 ; ERROR_NO_MORE_FILES

        Case Else
            Local $iError = @error
            Local $iExtended = @extended
            MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), "Error = " & $iError, _WinAPI_GetErrorMessage($iExtended))
            Exit
    EndSwitch

    _WinAPI_FindClose($hSearch)

    _ArrayDisplay($aList, '_WinAPI_Find...', $aList[0][0])