Função GetTempFileNameA (fileapi.h)
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 GetTempFileNameA(
[in] LPCSTR lpPathName,
[in] LPCSTR lpPrefixString,
[in] UINT uUnique,
[out] LPSTR lpTempFileName
);
Parâmetros
[in] lpPathName
O caminho do diretório para o nome do arquivo. Os aplicativos normalmente especificam um período (.) para o diretório atual ou o resultado da função GetTempPath2
[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 do 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 continua 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 do arquivo temporário. Esse buffer deve ser MAX_PATH caracteres para acomodar o caminho mais o caractere nulo de terminação.
Valor de retorno
Se a função for bem-sucedida, o valor retornado especifica o valor numérico exclusivo usado no nome do arquivo temporário. Se o parâmetro uUnique não for zero, o valor retornado especifica 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 de retorno | Descrição |
|---|---|
|
O comprimento da cadeia de caracteres apontado pelo parâmetro lpPathName é mais de MAX_PATH–14 caracteres. |
Observações
A função GetTempFileName
<caminho>\<pré-><uuuu>. TMP
A tabela a seguir descreve a sintaxe do nome do arquivo.
| Componente | Significado |
|---|---|
| <caminho> | Caminho especificado pelo parâmetro lpPathName |
| <pré-> | 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 na conversão de uma cadeia de caracteres ANSI, um aplicativo deve chamar a função CreateFile para criar um arquivo temporário.
No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Suportado |
|---|---|
| Protocolo SMB (Bloco de Mensagens do Servidor) 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 de Cluster (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Exemplos
Para obter um exemplo, consulte Criando e usando um arquivo temporário.
Nota
O cabeçalho fileapi.h define GetTempFileName como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | fileapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |