FindFirstFileExA-Funktion (fileapi.h)

Artikel
11/20/2024

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.

Verwenden Sie die FindFirstFileTransacted-Funktion, um diesen Vorgang als transacted-Vorgang auszuführen.

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 der Pfad und der Dateiname. Der Dateiname kann Platzhalterzeichen enthalten, z. B. ein Sternchen (*) oder ein Fragezeichen (?).

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

Wenn die Zeichenfolge mit einem Wildcard-, 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 diesen Grenzwert auf 32.767 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade und Namespaces.

Trinkgeld

Ab Windows 10, Version 1607, können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.

[in] fInfoLevelId

Die Informationsstufe 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 Filterung, die sich von dem Abgleich von Wildcard unterscheidet.

Dieser Parameter ist einer der FINDEX_SEARCH_OPS Enumerationswerte.

lpSearchFilter

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

Derzeit benötigen keine 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, wodurch die Leistung des Suchvorgangs erhöht werden 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	Beschränkt die Ergebnisse auf Dateien, die physisch auf dem Datenträger gespeichert sind. 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 zur ersten gefundenen Datei oder dem ersten gefundenen Verzeichnis.

Wenn die Funktion fehlschlägt oder keine Dateien aus der Suchzeichenfolge im parameter lpFileName findet, wird der Rückgabewert INVALID_HANDLE_VALUE und der Inhalt lpFindFileData- unbestimmt. Rufen Sie zum Abrufen erweiterter Fehlerinformationen die GetLastError--Funktion auf.

Bemerkungen

Die FindFirstFileEx--Funktion öffnet ein Suchhandle und gibt Informationen über die erste 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, die in einer Verzeichnisauflistungsanwendung (z. B. dem Dir-Befehl) angezeigt wird, wenn dasselbe Dateinamen-Zeichenfolgenmuster angegeben ist. 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 streng auf den Namen der Datei, nicht auf Attribute wie ein Datum oder einen Dateityp.
Die Suche enthält die langen und kurzen Dateinamen.
Ein Versuch, eine Suche mit einem nachgestellten umgekehrten Schrägstrich zu öffnen, schlägt immer fehl.
Das Übergeben einer ungültigen Zeichenfolge, NULL-oder einer leeren Zeichenfolge für den parameter lpFileName ist keine gültige Verwendung dieser Funktion. Die Ergebnisse in diesem Fall sind nicht definiert.

Hinweis In seltenen Fällen oder in einem stark geladenen System sind Dateiattributeinformationen auf NTFS-Dateisystemen möglicherweise nicht aktuell, wenn diese Funktion aufgerufen wird. Um sicherzustellen, dass die aktuellen NTFS-Dateisystemattribute abgerufen werden, rufen Sie die GetFileInformationByHandle--Funktion auf.

Wenn das zugrunde liegende Dateisystem den angegebenen Filtertyp nicht unterstützt, außer verzeichnisfiltern, schlägt FindFirstFileEx mit dem Fehler ERROR_NOT_SUPPORTEDfehl. Die Anwendung muss FINDEX_SEARCH_OPS Typ FileExSearchNameMatch verwenden und eine eigene Filterung durchführen.

Nachdem der Suchhandle eingerichtet wurde, verwenden Sie es in der FindNextFile--Funktion, um nach anderen Dateien zu suchen, die mit demselben Muster übereinstimmen, mit dem gleichen Filter, das ausgeführt wird. Wenn der 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 FindFirstFileExverwenden. 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 durchgehen, indem Sie FindNextFile-verwenden.
Verwenden Sie zum Abrufen der Attribute eines Stammverzeichnisses die GetFileAttributes--Funktion.

Hinweis Vor dem Ausstehen der Zeichenfolge "\\?\" keinen Zugriff auf das Stammverzeichnis zulässt.

In Netzwerkfreigaben können Sie eine lpFileName- in Form der folgenden Datei verwenden: "\\server\service\*". Sie können jedoch keine lpFileName- verwenden, die 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 nachgestellten umgekehrten Schrägstrich. Beispielsweise gibt ein Argument von "C:\Windows" Informationen zum 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 eine Datei mit diesem Namen zwischen dem Zeitpunkt, zu dem Sie das Ergebnis abfragen, und dem Zeitpunkt, zu dem Sie auf die Informationen reagieren, erstellen oder löschen könnte. Wenn dies ein potenzielles Problem für Ihre Anwendung ist, besteht eine mögliche Lösung darin, die CreateFile--Funktion mit CREATE_NEW zu verwenden (was 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 kann auf einem 64-Bit-Computer ausgeführt werden, Sie sollten Wow64DisableWow64FsRedirection aufrufen, bevor Sie FindFirstFileEx aufrufen und Wow64RevertWow64FsRedirection nach dem letzten Aufruf von FindNextFileaufrufen. Weitere Informationen finden Sie unter Dateisystemumleitung.

Wenn der Pfad auf eine symbolische Verknüpfung zeigt, enthält der WIN32_FIND_DATA Puffer Informationen über die symbolische Verknüpfung, nicht das Ziel.

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

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
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);
   }
}

Anmerkung

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

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll