GetTempFileName-Funktion (winbase.h)

Artikel
08/27/2023

Erstellt einen Namen für eine temporäre Datei. Beim Generieren eines eindeutigen Dateinamens wird eine leere Datei erstellt, und das zugehörige Handle wird freigegeben. Andernfalls wird nur ein Dateiname generiert.

Syntax

UINT GetTempFileName(
  [in]  LPCTSTR lpPathName,
  [in]  LPCTSTR lpPrefixString,
  [in]  UINT    uUnique,
  [out] LPTSTR  lpTempFileName
);

Parameter

[in] lpPathName

Der Verzeichnispfad für den Dateinamen. Anwendungen geben in der Regel einen Punkt (.) für das aktuelle Verzeichnis oder das Ergebnis der GetTempPath-Funktion an. Die Zeichenfolge darf nicht länger als MAX_PATH bis 14 Zeichen sein, oder GetTempFileName schlägt fehl. Wenn dieser Parameter NULL ist, schlägt die Funktion fehl.

[in] lpPrefixString

Die Null-endende Präfixzeichenfolge. Die Funktion verwendet bis zu den ersten drei Zeichen dieser Zeichenfolge als Präfix des Dateinamens. Diese Zeichenfolge muss aus Zeichen im OEM-definierten Zeichensatz bestehen.

[in] uUnique

Eine ganze Zahl ohne Vorzeichen, die beim Erstellen des temporären Dateinamens verwendet werden soll. Weitere Informationen finden Sie in den Hinweisen.

Wenn uUnique null ist, versucht die Funktion, mithilfe der aktuellen Systemzeit einen eindeutigen Dateinamen zu bilden. Wenn die Datei bereits vorhanden ist, wird die Anzahl um eins erhöht, und die Funktionen testen, ob diese Datei bereits vorhanden ist. Dies wird so lange fortgesetzt, bis ein eindeutiger Dateiname gefunden wird. Die Funktion erstellt eine Datei mit diesem Namen und schließt sie. Beachten Sie, dass die Funktion nicht versucht, die Eindeutigkeit des Dateinamens zu überprüfen, wenn uUnique ungleich null ist.

[out] lpTempFileName

Ein Zeiger auf den Puffer, der den temporären Dateinamen empfängt. Dieser Puffer sollte MAX_PATH Zeichen enthalten, um den Pfad und das abschließende NULL-Zeichen aufzunehmen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt der Rückgabewert den eindeutigen numerischen Wert an, der im temporären Dateinamen verwendet wird. Wenn der uUnique-Parameter ungleich null ist, gibt der Rückgabewert dieselbe Zahl an.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Im Folgenden ist ein möglicher Rückgabewert aufgeführt.

Rückgabewert	BESCHREIBUNG
ERROR_BUFFER_OVERFLOW	Die Länge der Zeichenfolge, auf die der lpPathName-Parameter verweist, ist mehr als MAX_PATH bis 14 Zeichen.

Hinweise

Die GetTempFileName-Funktion erstellt einen temporären Dateinamen in der folgenden Form:

<path>\<pre><uuuu>. TMP

In der folgenden Tabelle wird die Dateinamensyntax beschrieben.

Komponente	Bedeutung
<Pfad>	Pfad, der durch den lpPathName-Parameter angegeben wird
<pre>	Erste drei Buchstaben der lpPrefixString-Zeichenfolge
<uuuu>	Hexadezimalwert von uUnique

Wenn uUnique null ist, erstellt GetTempFileName eine leere Datei und schließt sie. Wenn uUnique nicht null ist, müssen Sie die Datei selbst erstellen. Es wird nur ein Dateiname erstellt, da GetTempFileName nicht garantieren kann, dass der Dateiname eindeutig ist.

Es werden nur die unteren 16 Bits des uUnique-Parameters verwendet. Dadurch wird GetTempFileName auf maximal 65.535 eindeutige Dateinamen beschränkt, wenn die Parameter lpPathName und lpPrefixString gleich bleiben.

Aufgrund des Algorithmus, der zum Generieren von Dateinamen verwendet wird, kann GetTempFileName beim Erstellen einer großen Anzahl von Dateien mit demselben Präfix eine schlechte Leistung erzielen. In solchen Fällen wird empfohlen, eindeutige Dateinamen basierend auf GUIDszu erstellen.

Temporäre Dateien, deren Namen von dieser Funktion erstellt wurden, werden nicht automatisch gelöscht. Um diese Dateien zu löschen, rufen Sie DeleteFile auf.

Um Probleme beim Konvertieren einer ANSI-Zeichenfolge zu vermeiden, sollte eine Anwendung die CreateFile-Funktion aufrufen, um eine temporäre Datei zu erstellen.

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)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Beispiele

Ein Beispiel finden Sie unter Erstellen und Verwenden einer temporären Datei.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll