Функция GetTempFileNameA (fileapi.h)

Статья
11/20/2024

Создает имя временного файла. Если создается уникальное имя файла, создается пустой файл, а дескриптор освобождается; в противном случае создается только имя файла.

Синтаксис

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

Параметры

[in] lpPathName

Путь к каталогу для имени файла. Приложения обычно указывают период (.) для текущего каталога или результат функции GetTempPath2. Строка не может быть длиннее MAX_PATH–14 символов или GetTempFileName завершится ошибкой. Если этот параметр null, функция завершается ошибкой.

[in] lpPrefixString

Строка префикса, завершаемая значением NULL. Функция использует до первых трех символов этой строки в качестве префикса имени файла. Эта строка должна состоять из символов в определяемом ИЗГОТОВИТЕЛЕМ наборе символов.

[in] uUnique

Целое число без знака, используемое при создании временного имени файла. Дополнительные сведения см. в разделе "Примечания".

Если uUnique равно нулю, функция пытается сформировать уникальное имя файла с использованием текущего системного времени. Если файл уже существует, число увеличивается на один, а функции проверяют, уже существует ли этот файл. Это продолжается до тех пор, пока не будет найдено уникальное имя файла; Функция создает файл по имени и закрывает его. Обратите внимание, что функция не пытается проверить уникальность имени файла, если uUnique ненулевое значение.

[out] lpTempFileName

Указатель на буфер, получающий временное имя файла. Этот буфер должен быть MAX_PATH символов, чтобы разместить путь, а также завершающий символ NULL.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение указывает уникальное числовое значение, используемое во временном имени файла. Если параметр uUnique ненулево, возвращаемое значение указывает то же число.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Ниже приведено возможное возвращаемое значение.

Возвращаемое значение	Описание
ERROR_BUFFER_OVERFLOW	Длина строки, на которую указывает параметр lpPathName, превышает MAX_PATH–14 символов.

Замечания

Функция getTempFileName создает временное имя файла следующей формы:

<пути>\<><>uuuu. TMP

В следующей таблице описан синтаксис имени файла.

Компонент	Значение
<пути>	Путь, указанный параметром lpPathName
< >	Первые три буквы строки lpPrefixString
<uuuu>	Шестнадцатеричное значение uUnique

Если uUnique равно нулю, GetTempFileName создает пустой файл и закрывает его. Если uUnique не равно нулю, необходимо создать файл самостоятельно. Создается только имя файла, так как GetTempFileName не может гарантировать уникальность имени файла.

Используются только более низкие 16 битов параметра uUnique. Это ограничивает GetTempFileName не более 655 535 уникальных имен файлов, если параметры lpPathName и lpPrefixString остаются неизменными.

Из-за алгоритма, используемого для создания имен файлов, GetTempFileName могут плохо выполняться при создании большого количества файлов с одинаковым префиксом. В таких случаях рекомендуется создавать уникальные имена файлов на основе GUID.

Временные файлы, имена которых были созданы этой функцией, не удаляются автоматически. Чтобы удалить эти файлы, вызовите DeleteFile.

Чтобы избежать проблем, возникающих при преобразовании строки ANSI, приложение должно вызвать функцию createFile CreateFile, чтобы создать временный файл.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технологии	Поддержанный
Протокол SMB 3.0	Да
Отработка отказа SMB 3.0 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

Примеры

Пример см. в статье Создание и использование временного файла.

Заметка

Заголовок fileapi.h определяет GetTempFileName как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll