Función GetTempFileNameA (fileapi.h)

Artículo
08/23/2023

Crea un nombre para un archivo temporal. Si se genera un nombre de archivo único, se crea un archivo vacío y se libera el identificador para él; de lo contrario, solo se genera un nombre de archivo.

Sintaxis

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

Parámetros

[in] lpPathName

Ruta de acceso del directorio para el nombre de archivo. Las aplicaciones suelen especificar un punto (.) para el directorio actual o el resultado de la función GetTempPath . La cadena no puede tener más de MAX_PATH–14 caracteres o Se producirá un error en GetTempFileName . Si este parámetro es NULL, se produce un error en la función.

[in] lpPrefixString

Cadena de prefijo terminada en null. La función usa hasta los tres primeros caracteres de esta cadena como prefijo del nombre de archivo. Esta cadena debe constar de caracteres en el juego de caracteres definido por OEM.

[in] uUnique

Entero sin signo que se va a usar para crear el nombre de archivo temporal. Para obtener más información, vea la sección Comentarios.

Si uUnique es cero, la función intenta formar un nombre de archivo único mediante la hora actual del sistema. Si el archivo ya existe, el número se incrementa en uno y las funciones comprueban si este archivo ya existe. Esto continúa hasta que se encuentra un nombre de archivo único; la función crea un archivo por ese nombre y lo cierra. Tenga en cuenta que la función no intenta comprobar la unicidad del nombre de archivo cuando uUnique no es cero.

[out] lpTempFileName

Puntero al búfer que recibe el nombre de archivo temporal. Este búfer debe ser MAX_PATH caracteres para acomodar la ruta de acceso más el carácter nulo de terminación.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto especifica el valor numérico único usado en el nombre de archivo temporal. Si el parámetro uUnique es distinto de cero, el valor devuelto especifica ese mismo número.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

A continuación se muestra un valor devuelto posible.

Valor devuelto	Descripción
ERROR_BUFFER_OVERFLOW	La longitud de la cadena a la que apunta el parámetro lpPathName es superior a MAX_PATH-14 caracteres.

Comentarios

La función GetTempFileName crea un nombre de archivo temporal con el siguiente formato:

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

En la tabla siguiente se describe la sintaxis del nombre de archivo.

Componente	Significado
<path>	Ruta de acceso especificada por el parámetro lpPathName
<pre>	Tres primeras letras de la cadena lpPrefixString
<uuuu>	Valor hexadecimal de uUnique

Si uUnique es cero, GetTempFileName crea un archivo vacío y lo cierra. Si uUnique no es cero, debe crear el archivo usted mismo. Solo se crea un nombre de archivo, ya que GetTempFileName no puede garantizar que el nombre de archivo sea único.

Solo se usan los 16 bits inferiores del parámetro uUnique . Esto limita GetTempFileName a un máximo de 65 535 nombres de archivo únicos si los parámetros lpPathName y lpPrefixString siguen siendo los mismos.

Debido al algoritmo usado para generar nombres de archivo, GetTempFileName puede funcionar mal al crear un gran número de archivos con el mismo prefijo. En tales casos, se recomienda crear nombres de archivo únicos basados en GUID.

Los archivos temporales cuyos nombres han sido creados por esta función no se eliminan automáticamente. Para eliminar estos archivos, llame a DeleteFile.

Para evitar problemas resultantes al convertir una cadena ANSI, una aplicación debe llamar a la función CreateFile para crear un archivo temporal.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Ejemplos

Para obtener un ejemplo, vea Crear y usar un archivo temporal.

Nota

El encabezado fileapi.h define GetTempFileName como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll