FindFirstFileTransactedA-Funktion (winbase.h)

Artikel
03/06/2024

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu verwenden, um die Anforderungen Ihrer Anwendung zu erfüllen. Viele Szenarios, für die TxF entwickelt wurde, können mit einfacheren und leichter verfügbaren Techniken erreicht werden. Darüber hinaus ist TxF in zukünftigen Versionen von Microsoft Windows möglicherweise nicht verfügbar. Weitere Informationen und Alternativen zu TxF finden Sie unter Alternativen zur Verwendung von transaktionalem NTFS.]

Durchsucht ein Verzeichnis nach einer Datei oder einem Unterverzeichnis mit einem Namen, der einem bestimmten Namen entspricht, als Transaktionsvorgang.

Diese Funktion ist die transaktionierte Form der FindFirstFileEx-Funktion .

Die grundlegendste Version dieser Funktion finden Sie unter FindFirstFile.

Syntax

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

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 darf nicht NULL sein, keine ungültige Zeichenfolge (z. B. eine leere Zeichenfolge oder eine Zeichenfolge, bei der das abschließende NULL-Zeichen fehlt) oder in einem nachfolgenden umgekehrten Schrägstrich (\) enden.

Wenn die Zeichenfolge mit einem Feldhalter, einem Punkt (.) oder einem 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 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. 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 aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces .

Die Datei muss sich auf dem lokalen Computer befinden. Andernfalls schlägt die Funktion fehl, und der letzte Fehlercode ist auf ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE festgelegt.

[in] fInfoLevelId

Die Informationsebene der zurückgegebenen Daten.

Dieser Parameter ist einer der FINDEX_INFO_LEVELS Enumerationswerte.

[out] lpFindFileData

Ein Zeiger auf die WIN32_FIND_DATA-Struktur , die Informationen zu einer gefundenen Datei oder einem gefundenen Unterverzeichnis empfängt.

[in] fSearchOp

Der Typ der auszuführenden Filterung, die sich vom Abgleich mit Wildcards 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.

[in] hTransaction

Ein Handle für die Transaktion. Dieses Handle wird von der CreateTransaction-Funktion zurückgegeben.

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 parameter lpFindFileData enthält Informationen über die erste gefundene Datei oder das erste gefundene Verzeichnis.

Wenn die Funktion nicht nach Dateien aus der Suchzeichenfolge im parameter lpFileName sucht, ist der Rückgabewert INVALID_HANDLE_VALUE , und der Inhalt von lpFindFileData ist unbestimmt. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie die GetLastError-Funktion auf.

Hinweise

Die FindFirstFileTransacted-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 verwendet wird. Dies liegt daran, dass FindFirstFileTransacted die Suchergebnisse nicht sortiert. Weitere Informationen finden Sie unter FindNextFile.

In der folgenden Liste sind einige weitere Suchmerkmale aufgeführt:

Die Suche erfolgt ausschließlich nach dem Namen der Datei, nicht nach Attributen wie einem Datum oder einem Dateityp.
Die Suche enthält 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 einer leeren Zeichenfolge für den lpFileName-Parameter ist keine gültige Verwendung dieser Funktion. Ergebnisse sind in diesem Fall undefiniert.

Hinweis In seltenen Fällen sind Dateiinformationen auf NTFS-Dateisystemen zum Zeitpunkt des Aufrufs dieser Funktion möglicherweise nicht aktuell. Rufen Sie die GetFileInformationByHandle-Funktion auf, um die aktuellen Dateiinformationen abzurufen.

Wenn das zugrunde liegende Dateisystem den angegebenen Filtertyp außer der Verzeichnisfilterung nicht unterstützt, schlägt FindFirstFileTransacted 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 demselben Muster entsprechen, und zwar mit der gleichen Filterung, die ausgeführt wird. Wenn das Suchhandle nicht benötigt wird, sollte es mithilfe der FindClose-Funktion geschlossen werden.

Wie bereits erwähnt, können Sie keinen nachfolgenden umgekehrten Schrägstrich (\) in der lpFileName-Eingabezeichenfolge für FindFirstFileTransacted 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 durchlaufen.
Verwenden Sie die GetFileAttributes-Funktion , um die Attribute eines Stammverzeichnisses abzurufen.

Hinweis Die ausstehende Zeichenfolge "\\?\" lässt keinen Zugriff auf das Stammverzeichnis zu.

Auf Netzwerkfreigaben können Sie einen lpFileName in folgender Form verwenden: "\\server\service*". 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 nachgestellten 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 den lpFileName-Wert "C:\Windows\*".

Beachten Sie, dass ein anderer Thread oder Prozess zwischen dem Zeitpunkt, zu dem Sie das Ergebnis abfragen, und dem Zeitpunkt, zu dem Sie mit den Informationen handeln, 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 (die fehlschlägt, wenn die Datei nicht vorhanden ist).

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

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

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

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	No
SMB 3.0 Transparent Failover (TFO)	No
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	No
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	No
Robustes Dateisystem (Resilient File System, ReFS)	No

SMB 3.0 unterstützt TxF nicht.

Hinweis

Der winbase.h-Header definiert FindFirstFileTransacted 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 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
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll