GetTempFileNameA, fonction (fileapi.h)

Article
11/20/2024

Crée un nom pour un fichier temporaire. Si un nom de fichier unique est généré, un fichier vide est créé et le handle à celui-ci est libéré ; sinon, seul un nom de fichier est généré.

Syntaxe

UINT GetTempFileNameA(
  [in]  LPCSTR lpPathName,
  [in]  LPCSTR lpPrefixString,
  [in]  UINT   uUnique,
  [out] LPSTR  lpTempFileName
);

Paramètres

[in] lpPathName

Chemin d’accès au répertoire du nom de fichier. Les applications spécifient généralement un point (.) pour le répertoire actif ou le résultat de la fonction GetTempPath2. La chaîne ne peut pas dépasser MAX_PATH-14 caractères ou GetTempFileName échoue. Si ce paramètre est 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 Remarques.

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é par un et les fonctions testent si ce fichier existe déjà. Cela se poursuit jusqu’à ce qu’un nom de fichier unique soit trouvé ; la fonction crée un fichier par ce nom et le ferme. Notez que la fonction ne tente pas de vérifier l’unicité du nom de fichier lorsque uUnique n’est pas zéro.

[out] lpTempFileName

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

Valeur de retour

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 n’est pas égal à 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’erreur étendues, appelez GetLastError.

Voici une valeur de retour possible.

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

Remarques

La fonction GetTempFileName crée un nom de fichier temporaire du formulaire suivant :

<chemin d’accès>\<><>uu . TMP

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

Composant	Signification
<chemin d’accès>	Chemin d’accès spécifié par le paramètre lpPathName
<pré>	Les 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 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 identiques.

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 GUIDs.

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

Pour éviter les problèmes résultant 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	Supporté
Protocole SMB (Server Message Block) 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
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

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

Note

L’en-tête fileapi.h définit GetTempFileName comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	fileapi.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll