GetTempFileName, fonction (winbase.h)

Article
08/27/2023

Crée un nom pour le fichier temporaire. Si un nom de fichier unique est généré, un fichier vide est créé et le gestionnaire de ce fichier est libéré ; dans le cas contraire, seul un nom de fichier est généré.

Syntaxe

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

Paramètres

[in] lpPathName

Chemin d’accès du répertoire pour le nom de fichier. Les applications spécifient généralement un point (.) pour le répertoire actif ou le résultat de la fonction GetTempPath . La chaîne ne peut pas comporter plus de MAX_PATH à 14 caractères, ou GetTempFileName échoue. Si ce paramètre a la valeur NULL, la fonction échoue.

[in] lpPrefixString

Chaîne de préfixe terminée par null. La fonction utilise jusqu’aux trois premiers caractères de cette chaîne comme préfixe du nom de fichier. Cette chaîne doit se composer de caractères dans le jeu de caractères défini par l’OEM.

[in] uUnique

Entier non signé à utiliser pour créer le nom de fichier temporaire. Pour plus d'informations, consultez la section Notes.

Si uUnique est égal à zéro, la fonction tente de former un nom de fichier unique à l’aide de l’heure système actuelle. Si le fichier existe déjà, le nombre est augmenté d’un et les fonctions testent si ce fichier existe déjà. Cela continue jusqu’à ce qu’un nom de fichier unique soit trouvé ; la fonction crée un fichier portant ce nom et le ferme. Notez que la fonction ne tente pas de vérifier l’unicité du nom de fichier lorsque uUnique est différent de zéro.

[out] lpTempFileName

Pointeur vers la mémoire tampon qui reçoit le nom du fichier temporaire. Cette mémoire tampon doit être MAX_PATH caractères pour prendre en charge le chemin d’accès et le caractère null de fin.

Valeur retournée

Si la fonction réussit, la valeur de retour spécifie la valeur numérique unique utilisée dans le nom de fichier temporaire. Si le paramètre uUnique est différent de zéro, la valeur de retour spécifie ce même nombre.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Voici une valeur de retour possible.

Valeur retournée	Description
ERROR_BUFFER_OVERFLOW	La longueur de la chaîne pointée par le paramètre lpPathName est de plus de MAX_PATH à 14 caractères.

Remarques

La fonction GetTempFileName crée un nom de fichier temporaire au format suivant :

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

Le tableau suivant décrit la syntaxe du nom de fichier.

Composant	Signification
<path>	Chemin spécifié par le paramètre lpPathName
<pre>	Trois premières lettres de la chaîne lpPrefixString
<Uuuu>	Valeur hexadécimale de uUnique

Si uUnique est égal à zéro, GetTempFileName crée un fichier vide et le ferme. Si uUnique n’est pas égal à zéro, vous devez créer le fichier vous-même. Seul un nom de fichier est créé, car GetTempFileName n’est pas en mesure de garantir que le nom de fichier est unique.

Seuls les 16 bits inférieurs du paramètre uUnique sont utilisés. Cela limite GetTempFileName à un maximum de 65 535 noms de fichiers uniques si les paramètres lpPathName et lpPrefixString restent les mêmes.

En raison de l’algorithme utilisé pour générer des noms de fichiers, GetTempFileName peut fonctionner mal lors de la création d’un grand nombre de fichiers avec le même préfixe. Dans ce cas, il est recommandé de construire des noms de fichiers uniques basés sur des GUID.

Les fichiers temporaires dont les noms ont été créés par cette fonction ne sont pas automatiquement supprimés. Pour supprimer ces fichiers, appelez DeleteFile.

Pour éviter les problèmes qui se posent lors de la conversion d’une chaîne ANSI, une application doit appeler la fonction CreateFile pour créer un fichier temporaire.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

Pour obtenir un exemple, consultez Création et utilisation d’un fichier temporaire.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll