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

Статья
06/02/2023

Преобразует указанный путь в длинную форму.

Чтобы выполнить эту операцию как транзакцию, используйте функцию GetLongPathNameTransacted .

Дополнительные сведения об именах файлов и путей см. в разделе Именование файлов, путей и пространств имен.

Важно!

Чтобы использовать эту функцию, вызывающий объект должен иметь следующие разрешения на указанный путь и родительские каталоги:

Папка списка
Чтение данных
Чтение атрибутов

Синтаксис

DWORD GetLongPathNameW(
  [in]  LPCWSTR lpszShortPath,
  [out] LPWSTR  lpszLongPath,
  [in]  DWORD   cchBuffer
);

Параметры

[in] lpszShortPath

Путь для преобразования.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

[out] lpszLongPath

Указатель на буфер для получения длинного пути.

Можно использовать тот же буфер, который использовался для параметра lpszShortPath .

[in] cchBuffer

Размер буфера lpszLongPath указывает на в TCHAR.

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

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

Если буфер lpBuffer слишком мал, чтобы содержать путь, возвращаемым значением в TCHAR является размер буфера, необходимого для хранения пути, и завершающего символа NULL.

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

Во многих файловых системах короткое имя файла содержит символ тильды (~). Однако не все файловые системы следуют этому соглашению. Поэтому не следует предполагать, что можно пропустить вызов GetLongPathName , если путь не содержит символ тильды (~).

Если файл или каталог существует, но длинный путь не найден, getLongPathName успешно скопировать строку, на которую ссылается параметр lpszShortPath , в буфер, на который ссылается параметр lpszLongPath .

Если возвращаемое значение больше значения, указанного в cchBuffer, можно снова вызвать функцию с буфером, достаточно большим для хранения пути. Пример этого случая см. в разделе Пример кода для GetFullPathName.

Примечание Хотя возвращаемое значение в данном случае является длиной, которая включает завершающий символ NULL, возвращаемое значение при успешном выполнении не включает завершающий символ NULL в счетчике.

Можно иметь доступ к файлу или каталогу, но не иметь доступа к некоторым родительским каталогам этого файла или каталога. В результате getLongPathName может завершиться ошибкой, если не удается запросить родительский каталог компонента пути для определения длинного имени этого компонента. Этот проверка можно пропустить для компонентов каталога с расширениями файлов длиной более 3 символов или общей длиной более 12 символов. Дополнительные сведения см. в разделе Короткие и длинные имена статьи Именование файлов, путей и пространств имен.

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

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

Примеры

Пример использования GetLongPathName см. в разделе Пример кода для GetFullPathName.

Примечание

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

Требования


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