GetFullPathNameTransactedA-Funktion (winbase.h)

Artikel
03/03/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.]

Ruft den vollständigen Pfad und Dateinamen der angegebenen Datei als Transaktionsvorgang ab.

Um diesen Vorgang ohne Transaktionen auszuführen, verwenden Sie die GetFullPathName-Funktion .

Weitere Informationen zu Datei- und Pfadnamen finden Sie unter Dateinamen, Pfade und Namespaces.

Syntax

DWORD GetFullPathNameTransactedA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart,
  [in]  HANDLE hTransaction
);

Parameter

[in] lpFileName

Der Name der Datei.

Diese Zeichenfolge kann kurze (das Formular 8.3) oder lange Dateinamen verwenden. Diese Zeichenfolge kann ein Freigabe- oder Volumename sein.

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

[in] nBufferLength

Die Größe des Puffers, um die NULL-beendete Zeichenfolge für das Laufwerk und den Pfad in TCHARs zu empfangen.

[out] lpBuffer

Ein Zeiger auf einen Puffer, der die NULL-beendete Zeichenfolge für das Laufwerk und den Pfad empfängt.

[out] lpFilePart

Ein Zeiger auf einen Puffer, der die Adresse (in lpBuffer) der endgültigen Dateinamenkomponente im Pfad empfängt. Geben Sie NULL an, wenn Sie diese Informationen nicht erhalten müssen.

Wenn lpBuffer auf ein Verzeichnis und nicht auf eine Datei verweist, erhält lpFilePart 0 (null).

[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 die Länge der in lpBuffer kopierten Zeichenfolge in TCHARs, ohne das beendende NULL-Zeichen.

Wenn der lpBuffer-Puffer zu klein ist, um den Pfad zu enthalten, ist der Rückgabewert die Größe des Puffers in TCHARs, der erforderlich ist, um den Pfad und das beendende NULL-Zeichen zu enthalten.

Wenn die Funktion aus einem anderen Grund fehlschlägt, ist der Rückgabewert 0. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

GetFullPathNameTransacted führt den Namen des aktuellen Laufwerks und Verzeichnisses mit einem angegebenen Dateinamen zusammen, um den vollständigen Pfad und Dateinamen einer angegebenen Datei zu ermitteln. Außerdem wird die Adresse des Dateinamenteils des vollständigen Pfads und des Dateinamens berechnet. Diese Funktion überprüft nicht, ob der resultierende Pfad und der Dateiname gültig sind, oder dass eine vorhandene Datei auf dem zugeordneten Volume angezeigt wird.

Freigabe- und Volumenamen sind gültige Eingaben für lpFileName. Die folgende Liste weist beispielsweise die zurückgegebenen Pfad- und Dateinamen auf, wenn test-2 ein Remotecomputer und U: ein netzwerkzuordnungsfähiges Laufwerk ist:

Wenn Sie "\\test-2\q$\lh" angeben, lautet der zurückgegebene Pfad "\\test-2\q$\lh".
Wenn Sie "\\?\UNC\test-2\q$\lh" angeben, lautet der zurückgegebene Pfad "\\?\UNC\test-2\q$\lh".
Wenn Sie "U:" angeben, lautet der zurückgegebene Pfad "U:\"

GetFullPathNameTransacted konvertiert den angegebenen Dateinamen lpFileName nicht. Wenn der angegebene Dateiname vorhanden ist, können Sie GetLongPathNameTransacted, GetLongPathName oder GetShortPathName verwenden, um in lange oder kurze Pfadnamen zu konvertieren.

Wenn der Rückgabewert größer als der in nBufferLength angegebene Wert ist, können Sie die Funktion erneut mit einem Puffer aufrufen, der groß genug ist, um den Pfad zu speichern. Ein Beispiel für diesen Fall sowie die Verwendung eines Puffers der Länge null für die dynamische Zuordnung finden Sie im Abschnitt Beispielcode.

Hinweis Obwohl der Rückgabewert in diesem Fall eine Länge hat, die das beendende NULL-Zeichen enthält, enthält der Rückgabewert bei Erfolg nicht das beendende NULL-Zeichen in der Anzahl.

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 GetFullPathNameTransacted 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 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

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