FindFirstFileExA-Funktion (fileapi.h)

Durchsucht ein Verzeichnis nach einer Datei oder einem Unterverzeichnis mit einem Namen und Attributen, die den angegebenen Attributen entsprechen.

Die grundlegendste Version dieser Funktion finden Sie unter FindFirstFile.

Um diesen Vorgang als transaktionierten Vorgang auszuführen, verwenden Sie die FindFirstFileTransacted-Funktion .

Syntax

HANDLE FindFirstFileExA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

Parameter

[in] lpFileName

Das Verzeichnis oder den Pfad und der Dateiname. Der Dateiname kann Platzhalterzeichen enthalten, z. B. ein Sternchen (*) oder ein Fragezeichen (?).

Dieser Parameter darf nicht NULL sein, keine ungültige Zeichenfolge (z. B. eine leere Zeichenfolge oder eine Zeichenfolge, der das beendende NULL-Zeichen fehlt) oder in einem nachfolgenden umgekehrten Schrägstrich (\) enden.

Wenn die Zeichenfolge mit einem Feldhalter, Punkt oder Verzeichnisnamen endet, muss der Benutzer Zugriff auf den Stamm und alle Unterverzeichnisse im Pfad haben.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

[in] fInfoLevelId

Die Informationsebene der zurückgegebenen Daten.

Dieser Parameter ist einer der FINDEX_INFO_LEVELS Enumerationswerte.

[out] lpFindFileData

Ein Zeiger auf den Puffer, der die Dateidaten empfängt.

Der Zeigertyp wird durch die Informationsebene bestimmt, die im fInfoLevelId-Parameter angegeben ist.

[in] fSearchOp

Der Typ der auszuführenden Filterung, die sich von der Abgleichung des Feldhalters unterscheidet.

Dieser Parameter ist einer der FINDEX_SEARCH_OPS Enumerationswerte.

lpSearchFilter

Ein Zeiger auf die Suchkriterien, wenn der angegebene fSearchOp strukturierte Suchinformationen benötigt.

Derzeit erfordert keiner der unterstützten fSearchOp-Werte erweiterte Suchinformationen. Daher muss dieser Zeiger NULL sein.

[in] dwAdditionalFlags

Gibt zusätzliche Flags an, die die Suche steuern.

Wert Bedeutung
FIND_FIRST_EX_CASE_SENSITIVE
1
Bei Suchvorgängen wird die Groß-/Kleinschreibung beachtet.
FIND_FIRST_EX_LARGE_FETCH
2
Verwendet einen größeren Puffer für Verzeichnisabfragen, der die Leistung des Suchvorgangs erhöhen kann.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird erst unter Windows Server 2008 R2 und Windows 7 unterstützt.

FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY
4
Schränkt die Ergebnisse auf Dateien ein, die sich physisch auf dem Datenträger befinden. Dieses Flag ist nur relevant, wenn ein Dateivirtualisierungsfilter vorhanden ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Suchhandle, das in einem nachfolgenden Aufruf von FindNextFile oder FindClose verwendet wird, und der lpFindFileData-Parameter enthält Informationen über die erste Gefundene Datei oder das erste gefundene Verzeichnis.

Wenn die Funktion dateien aus der Suchzeichenfolge im lpFileName-Parameter nicht finden kann, ist der Rückgabewert INVALID_HANDLE_VALUE , und der Inhalt von lpFindFileData ist unbestimmt. Rufen Sie die GetLastError-Funktion auf, um erweiterte Fehlerinformationen abzurufen.

Bemerkungen

Die FindFirstFileEx-Funktion öffnet ein Suchhandle und gibt Informationen zur ersten Datei zurück, die das Dateisystem mit einem Namen findet, der dem angegebenen Muster entspricht. Dies kann die erste Datei oder das erste Verzeichnis sein, das in einer Verzeichnisauflistungsanwendung (z. B. dem Befehl dir) angezeigt wird, wenn dasselbe Dateinamenzeichenfolgenmuster angegeben wird. Dies liegt daran, dass FindFirstFileEx keine Sortierung der Suchergebnisse durchführt. Weitere Informationen finden Sie unter FindNextFile.

In der folgenden Liste werden einige andere Suchmerkmale identifiziert:

  • Die Suche erfolgt ausschließlich nach dem Namen der Datei, nicht nach Attributen wie einem Datum oder einem Dateityp.
  • Die Suche umfasst die langen und kurzen Dateinamen.
  • Ein Versuch, eine Suche mit einem nachfolgenden umgekehrten Schrägstrich zu öffnen, schlägt immer fehl.
  • Das Übergeben einer ungültigen Zeichenfolge, NULL oder leeren Zeichenfolge für den lpFileName-Parameter ist keine gültige Verwendung dieser Funktion. Die Ergebnisse sind in diesem Fall nicht definiert.
Hinweis In seltenen Fällen oder auf einem stark geladenen System sind Dateiattributeinformationen auf NTFS-Dateisystemen zum Zeitpunkt des Aufrufs dieser Funktion möglicherweise nicht aktuell. Rufen Sie die GetFileInformationByHandle-Funktion auf, um die aktuellen NTFS-Dateisystemdateiattribute zu erhalten.
 
Wenn das zugrunde liegende Dateisystem den angegebenen Filtertyp außer der Verzeichnisfilterung nicht unterstützt, schlägt FindFirstFileEx mit dem fehler ERROR_NOT_SUPPORTED fehl. Die Anwendung muss FINDEX_SEARCH_OPS Typ FileExSearchNameMatch verwenden und eine eigene Filterung durchführen.

Nachdem das Suchhandle eingerichtet wurde, verwenden Sie es in der FindNextFile-Funktion , um nach anderen Dateien zu suchen, die dem gleichen Muster mit der gleichen Filterung entsprechen, die ausgeführt wird. Wenn das Suchhandle nicht benötigt wird, sollte es mithilfe der Funktion FindClose geschlossen werden.

Wie bereits erwähnt, können Sie keinen nachfolgenden umgekehrten Schrägstrich (\) in der LpFileName-Eingabezeichenfolge für FindFirstFileEx verwenden, daher ist es möglicherweise nicht offensichtlich, wie Stammverzeichnisse durchsucht werden. Wenn Sie Dateien anzeigen oder die Attribute eines Stammverzeichnisses abrufen möchten, gelten die folgenden Optionen:

  • Um Dateien in einem Stammverzeichnis zu untersuchen, können Sie "C:\*" verwenden und das Verzeichnis mithilfe von FindNextFile schrittweise durchlaufen.
  • Um die Attribute eines Stammverzeichnisses abzurufen, verwenden Sie die GetFileAttributes-Funktion .
Hinweis Die Zeichenfolge "\\?\" lässt keinen Zugriff auf das Stammverzeichnis zu.
 

Auf Netzwerkfreigaben können Sie einen lpFileName in der Form "\\server\service\*" verwenden. Sie können jedoch keinen lpFileName verwenden, der auf die Freigabe selbst verweist. beispielsweise ist "\\server\service" ungültig.

Um ein Verzeichnis zu untersuchen, das kein Stammverzeichnis ist, verwenden Sie den Pfad zu diesem Verzeichnis, ohne einen nachfolgenden umgekehrten Schrägstrich. Beispielsweise gibt ein Argument von "C:\Windows" Informationen über das Verzeichnis "C:\Windows" zurück, nicht über ein Verzeichnis oder eine Datei in "C:\Windows". Um die Dateien und Verzeichnisse in "C:\Windows" zu untersuchen, verwenden Sie einen lpFileName von "C:\Windows\*".

Der folgende Aufruf:

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

Entspricht dem folgenden Aufruf:

FindFirstFile( lpFileName, lpFindData );

Beachten Sie, dass ein anderer Thread oder Prozess zwischen dem Zeitpunkt, zu dem Sie das Ergebnis abfragen, und dem Zeitpunkt, zu dem Sie auf die Informationen reagieren, eine Datei mit diesem Namen erstellen oder löschen kann. Wenn dies ein potenzielles Problem für Ihre Anwendung ist, besteht eine mögliche Lösung darin, die CreateFile-Funktion mit CREATE_NEW (die fehlschlägt, wenn die Datei vorhanden ist) oder OPEN_EXISTING (was fehlschlägt, wenn die Datei nicht vorhanden ist).

Wenn Sie eine 32-Bit-Anwendung schreiben, um alle Dateien in einem Verzeichnis aufzulisten und die Anwendung möglicherweise auf einem 64-Bit-Computer ausgeführt wird, sollten Sie Wow64DisableWow64FsRedirection aufrufen, bevor Sie FindFirstFileEx aufrufen, und wow64RevertWow64FsRedirection nach dem letzten Aufruf von FindNextFile aufrufen. Weitere Informationen finden Sie unter Dateisystemumleitung.

Wenn der Pfad auf einen symbolischen Link verweist, enthält der WIN32_FIND_DATA Puffer Informationen zum symbolischen Link, nicht zum Ziel.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie Unterstützt
Server Message Block (SMB) 3.0-Protokoll Ja
SMB 3.0 Transparent Failover (TFO) Ja
SMB 3.0 mit Horizontalskalieren von Dateifreigaben (SO) Ja
Freigegebenes Clustervolume-Dateisystem (CsvFS) Ja
Robustes Dateisystem (Resilient File System, ReFS) Ja
 

Beispiele

Der folgende Code zeigt eine minimale Verwendung von FindFirstFileEx. Dieses Programm entspricht dem Beispiel im Thema FindFirstFile .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
             FindExSearchNameMatch, NULL, 0);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFileEx failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Hinweis

Der fileapi.h-Header definiert FindFirstFileEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile fileapi.h (Einschließen von Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

FINDEX_INFO_LEVELS

FINDEX_SEARCH_OPS

Dateiverwaltungsfunktionen

FindClose

FindFirstFile

FindFirstFileTransacted

FindNextFile

GetFileAttributes

Benennen einer Datei

Symbolische Links

Verwenden der Windows-Header

WIN32_FIND_DATA