Opis funkcji API FindFirstFile (...)
Funkcja FindFirstFile(...) wyszukuje pliki i foldery po nazwie pliku, lub wzorcu z użyciem symboli wieloznacznych "?" oraz "*". W wyszukiwaniu nie można określić żadnych atrybutów, takich jak data lub typ pliku. Wyszukiwanie obejmuje długie i krótkie nazwy plików. Próba otwarcia wyszukiwania, gdy podana nazwa pliku zawiera na końcu znak backslash (\), zawsze kończy się niepowodzeniem.
Public Declare Function FindFirstFile _ Lib "kernel32" Alias "FindFirstFileW" _ (ByVal lpFileName As String, _ lpFindFileData As WIN32_FIND_DATA) As Long
- argumenty:
- lpFileName
-
Nazwa katalogu lub ścieżka i nazwa pliku, która może zawierać symbole wieloznaczne, np. gwiazdkę (*)
lub znak zapytania (?). Argument ten nie może być ciągiem zerowej długości, ani zawierać
na końcu znaku backslash (\). Jeśli ciąg kończy się symbolem wieloznacznym, kropką (.) lub jest
nazwą katalogu, użytkownik musi mieć uprawnienia dostępu do katalogu głównego i wszystkich podkatalogów
w określonej ścieżce. Argument ten musi być przekazany w formacie Unicode.
Uwaga. Próba otwarcia wyszukiwania, gdy podana nazwa pliku (lpFileName) zawiera na końcu znak backslash (\), zawsze kończy się niepowodzeniem. - lpFindFileData
- Wskaźnik do struktury WIN32_FIND_DATA, zawierającej informacje o znalezionym pliku lub katalogu.
- zwraca:
-
Przy powodzeniu, (gdy zostanie znaleziony plik lub folder pasujący do wzorca), zwraca uchwyt wyszukiwania, a w strukturze WIN32_FIND_DATA informacje o znalezionym pliku lub folderze. Zwrócony uchwyt wyszukiwania możemy użyć w celu wyszukania kolejnego pliku (folderu) za pomocą funkcji FindNextFile(...) lub przekazać uchwyt wyszukiwania do funkcji FindClose(...) w przypadku zakończenia wyszukiwania.
Przy niepowodzeniu, lub gdy nie został znaleziony plik lub folder odpowiadający wzorcowi przekazanemu w argumencie lpFileName, funkcja zwraca wartość INVALID_HANDLE_VALUE = -1 i nieokreśloną wartość lpFindFileData (struktura WIN32_FIND_DATA). Możemy wtedy sprawdzić właściwość LastDllError obiektu Err. Jeżeli zwrócona wartość równa jest stałej ERROR_FILE_NOT_FOUND = &2 oznacza to, że plik lub folder nie został znaleziony.
Uwagi.
- Dokładniejszy opis struktury WIN32_FIND_DATA można znaleźć na stronie Struktura WIN32_FIND_DATA
- Wyszukiwanie odbywa się wyłącznie w oparciu o nazwę pliku. Nie są uwzględniane żadne atrybuty pliku np. takie jak data lub typ pliku. By wyszukiwać pliki z uwzględnieniem tych takich atrybutów, należy użyć funkcji FindFirstFileEx(...).
- W wyszukiwaniu uwzględniane są długie i krótkie nazwy plików lub folderów.
- Próba wyszukiwania wzorca zawierającego backslash (\) na końcu, zawsze kończy się niepowodzeniem.
- W celu wylistowania, lub uzyskania atrybutów, plików i folderów w katalogu głównym należy użyć wzorca "C: \ *" i przeszukiwać katalog krok po kroku za pomocą funkcji FindNextFile.
- Nie można przekazać ciągu zerowej długości w argumencie lpFileName. Dla takiej wartości zwracane wyniki są niezdefiniowane.
- Jeżeli funkcja zwróci uchwyt wyszukiwania, można go używać do wyszukiwania innych plików, które pasują do tego samego wzoru za pomocą funkcji FindNextFile(...).
- By zakończyć wyszukiwanie należy zamknąć niepotrzebny już uchwyt wyszukiwania za pomocą funkcji FindClose(...). Nie należy do tego celu stosować funkcji CloseHandle(...).