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

Статья
11/20/2024

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

Чтобы выполнить эту операцию как транзакцию, используйте функцию 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 указывает на TCHARs.

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

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

Если буфер lpBuffer слишком мал, чтобы содержать путь, возвращаемое значение — это размер TCHARs, буфера, который требуется для хранения пути и конца null-символа.

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

Замечания

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

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

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

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

Доступ к файлу или каталогу можно получить, но у него нет доступа к некоторым родительским каталогам этого файла или каталога. В результате GetLongPathName может завершиться ошибкой, если не удается запросить родительский каталог компонента пути, чтобы определить длинное имя этого компонента. Этот флажок можно пропустить для компонентов каталога, имеющих расширения файлов более 3 символов или общих длин более 12 символов. Дополнительные сведения см. в разделе Short vs. Long Names раздела Именование файлов, путей и пространств имен.

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

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

Примеры

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

Заметка

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

Требования

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