Função GetTempFileName (winbase.h)

Artigo
03/03/2024

Cria um nome para um arquivo temporário. Se um nome de arquivo exclusivo for gerado, um arquivo vazio será criado e o identificador para ele será liberado; caso contrário, somente um nome de arquivo será gerado.

Sintaxe

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

Parâmetros

[in] lpPathName

O caminho do diretório para o nome do arquivo. Os aplicativos normalmente especificam um ponto (.) para o diretório atual ou o resultado da função GetTempPath . A cadeia de caracteres não pode ter mais de MAX_PATH a 14 caracteres ou GetTempFileName falhará. Se esse parâmetro for NULL, a função falhará.

[in] lpPrefixString

A cadeia de caracteres de prefixo terminada em nulo. A função usa até os três primeiros caracteres dessa cadeia de caracteres como o prefixo do nome do arquivo. Essa cadeia de caracteres deve consistir em caracteres no conjunto de caracteres definido por OEM.

[in] uUnique

Um inteiro sem sinal a ser usado na criação do nome de arquivo temporário. Para obter mais informações, consulte Comentários.

Se uUnique for zero, a função tentará formar um nome de arquivo exclusivo usando a hora atual do sistema. Se o arquivo já existir, o número será aumentado em um e as funções testarão se esse arquivo já existir. Isso continuará até que um nome de arquivo exclusivo seja encontrado; a função cria um arquivo com esse nome e o fecha. Observe que a função não tenta verificar a exclusividade do nome do arquivo quando uUnique não é zero.

[out] lpTempFileName

Um ponteiro para o buffer que recebe o nome de arquivo temporário. Esse buffer deve ser MAX_PATH caracteres para acomodar o caminho mais o caractere nulo de terminação.

Retornar valor

Se a função for bem-sucedida, o valor retornado especificará o valor numérico exclusivo usado no nome do arquivo temporário. Se o parâmetro uUnique não for zero, o valor retornado especificará esse mesmo número.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Veja a seguir um possível valor retornado.

Valor retornado	Descrição
ERROR_BUFFER_OVERFLOW	O comprimento da cadeia de caracteres apontada pelo parâmetro lpPathName é de mais de MAX_PATH a 14 caracteres.

Comentários

A função GetTempFileName cria um nome de arquivo temporário do seguinte formulário:

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

A tabela a seguir descreve a sintaxe do nome do arquivo.

Componente	Significado
<caminho>	Caminho especificado pelo parâmetro lpPathName
<pre>	Primeiras três letras da cadeia de caracteres lpPrefixString
<Uuuu>	Valor hexadecimal de uUnique

Se uUnique for zero, GetTempFileName criará um arquivo vazio e o fechará. Se uUnique não for zero, você deverá criar o arquivo por conta própria. Somente um nome de arquivo é criado, pois GetTempFileName não é capaz de garantir que o nome do arquivo seja exclusivo.

Somente os 16 bits inferiores do parâmetro uUnique são usados. Isso limita GetTempFileName a um máximo de 65.535 nomes de arquivo exclusivos se os parâmetros lpPathName e lpPrefixString permanecerem os mesmos.

Devido ao algoritmo usado para gerar nomes de arquivo, GetTempFileName pode ter um desempenho ruim ao criar um grande número de arquivos com o mesmo prefixo. Nesses casos, é recomendável que você construa nomes de arquivo exclusivos com base em GUIDs.

Arquivos temporários cujos nomes foram criados por essa função não são excluídos automaticamente. Para excluir esses arquivos, chame DeleteFile.

Para evitar problemas resultantes ao converter uma cadeia de caracteres ANSI, um aplicativo deve chamar a função CreateFile para criar um arquivo temporário.

No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (SMB) 3.0	Sim
TFO (Failover transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo, consulte Criando e usando um arquivo temporário.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll