GetTempFileNameA-Funktion (fileapi.h)

Artikel
08/23/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 GetTempFileNameA(
  [in]  LPCSTR lpPathName,
  [in]  LPCSTR lpPrefixString,
  [in]  UINT   uUnique,
  [out] LPSTR  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 vom 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 erstellen. 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 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 nonzero ist.

[out] lpTempFileName

Ein Zeiger auf den Puffer, der den temporären Dateinamen empfängt. Dieser Puffer sollte MAX_PATH Zeichen sein, um den Pfad und das endende 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 nichtzero 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, beträgt mehr als MAX_PATH–14 Zeichen.

Hinweise

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

<pfad>\<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 identisch 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 erbringen. In solchen Fällen wird empfohlen, eindeutige Dateinamen basierend auf GUIDs zu 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.

Hinweis

Der fileapi.h-Header definiert GetTempFileName 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 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


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