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

Статья
06/02/2023

Извлекает форму короткого пути указанного пути.

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

Синтаксис

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

Параметры

[in] lpszLongPath

Строка пути.

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

Совет

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

[out] lpszShortPath

Указатель на буфер для получения короткой формы пути, заданного lpszLongPath , завершаемой null.

Передача null для этого параметра и нуля для cchBuffer всегда возвращает требуемый размер буфера для указанного lpszLongPath.

[in] cchBuffer

Размер буфера, на который указывает lpszShortPath , в TCHAR.

Задайте для этого параметра нулевое значение, если lpszShortPath имеет значение NULL.

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

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

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

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

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

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

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

Для параметра lpszShortPath можно задать то же значение, что и для параметра lpszLongPath ; другими словами, можно задать выходной буфер для короткого пути к адресу строки входного пути. Всегда убедитесь, что параметр cchBuffer точно представляет общий размер этого буфера в TCHAR.

Вы можете получить длинное имя файла из короткого имени, вызвав функцию GetLongPathName . Кроме того, если GetLongPathName недоступен, можно вызвать Метод FindFirstFile для каждого компонента пути, чтобы получить соответствующее длинное имя.

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

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

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

SMB 3.0 не поддерживает короткие имена в общих папках с возможностью непрерывной доступности.

Устойчивая файловая система (ReFS) не поддерживает короткие имена. При вызове GetShortPathName по пути, который не имеет коротких имен на диске, вызов будет выполнен успешно, но вместо этого вернет путь с длинным именем. Этот результат также возможен для томов NTFS, так как нет никакой гарантии, что короткое имя будет существовать для заданного длинного имени.

Примеры

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

В следующем примере C++ показано, как использовать динамически выделенный выходной буфер.

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

Требования

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