GetFullPathNameTransactedA-Funktion (winbase.h)

Artikel
11/20/2024

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu nutzen, um die Anforderungen Ihrer Anwendung zu erreichen. Viele Szenarien, für die TxF entwickelt wurde, können durch einfachere und leichter verfügbare 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 Transactional NTFS.]

Ruft den vollständigen Pfad und Dateinamen der angegebenen Datei als transacted-Vorgang 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 8.3-Formular) 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_REMOTEfestgelegt.

[in] nBufferLength

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

[out] lpBuffer

Ein Zeiger auf einen Puffer, der die mit 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, empfängt 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 in TCHARsder Zeichenfolge, die in lpBuffer-kopiert wurde, nicht einschließlich des endenden NULL-Zeichens.

Wenn der lpBuffer- Puffer zu klein ist, um den Pfad zu enthalten, ist der Rückgabewert die Größe in TCHARsdes Puffers, der zum Speichern des Pfads und des endenden Nullzeichens erforderlich ist.

Wenn die Funktion aus einem anderen Grund fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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 dateinamens berechnet. Diese Funktion überprüft nicht, ob der resultierende Pfad und der Dateiname gültig sind oder ob eine vorhandene Datei auf dem zugeordneten Volume angezeigt wird.

Freigabe- und Volumenamen sind gültige Eingaben für lpFileName. Die folgende Liste identitätiert beispielsweise den zurückgegebenen Pfad und Dateinamen, wenn test-2 ein Remotecomputer und U ist: ein zugeordnetes Netzlaufwerk:

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 den angegebenen Dateinamen nicht konvertiert, lpFileName. 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 nBufferLengthangegebene 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 des 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 ist, die das beendende NULL-Zeichen enthält, enthält der Rückgabewert für Erfolg nicht das endende Nullzeichen in der Anzahl.

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	Nein
SMB 3.0 Transparent Failover (TFO)	Nein
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Nein
Freigegebenes Clustervolumedateisystem (CsvFS)	Nein
Resilient File System (ReFS)	Nein

SMB 3.0 unterstützt TxF nicht.

Anmerkung

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 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 Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll