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

Статья
03/14/2023

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

Синтаксис

UINT GetTempFileNameW(
  [in]  LPCWSTR lpPathName,
  [in]  LPCWSTR lpPrefixString,
  [in]  UINT    uUnique,
  [out] LPWSTR  lpTempFileName
);

Параметры

[in] lpPathName

Путь к каталогу для имени файла. Приложения обычно указывают точку (.) для текущего каталога или результата функции GetTempPath . Строка не может быть длиннее 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 символов.

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

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

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

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

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

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

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

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

Примеры

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

Примечание

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

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll