Поделиться через

Функция PathCchCanonicalizeEx (pathcch.h)

  • Статья

Упрощает путь, удаляя такие элементы навигации, как "." и ".", чтобы создать прямой, правильно сформированный путь.

Эта функция отличается от PathCchCanonicalize тем, что она позволяет создать более длинный конечный путь.

Эта функция отличается от PathAllocCanonicalize тем, что вызывающий объект должен объявить размер возвращаемой строки, которая хранится в стеке.

Эта функция отличается от PathCanonicalize тем, что она принимает пути с префиксами "\", "\?" и "\?\UNC".

Примечание Эту функцию PathCchCanonicalize или PathAllocCanonicalize следует использовать вместо PathCanonicalize , чтобы предотвратить возможность переполнения буфера.

Синтаксис

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

Параметры

[out] pszPathOut

Указатель на буфер, который при успешном возврате этой функции получает отредактированную строку пути.

[in] cchPathOut

Размер буфера, на который указывает pszPathOut, в символах.

[in] pszPathIn

Указатель на исходную строку пути. Если это значение равно NULL, указывает на пустую строку или приводит к пустой строке после удаления элементов "." и "..", одна обратная косая черта копируется в буфер, на который указывает pszPathOut.

[in] dwFlags

Один или несколько из следующих флагов:

Значение Значение
PATHCCH_NONE
0x0000000
 Не разрешайте построение путей \\?\ (т. е. длинных путей) длиннее MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 Разрешите построение путей \\?\ длиннее MAX_PATH . Обратите внимание, что значение cchPathOut должно быть больше MAX_PATH . Если это не так, этот флаг игнорируется.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 Заставляет API обрабатывать вызывающий объект как включенный длинный путь, независимо от состояния процесса с поддержкой длинного имени. Этот параметр можно использовать только при указании PATHCCH_ALLOW_LONG_PATHS и не может использоваться с PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS.

Примечание Это значение доступно начиная с Windows 10 версии 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 Заставляет API обрабатывать вызывающий объект как отключенный длинный путь, независимо от состояния процесса с поддержкой длинного имени. Этот параметр можно использовать только при указании PATHCCH_ALLOW_LONG_PATHS и не может использоваться с PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS.

Примечание Это значение доступно начиная с Windows 10 версии 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 Отключает нормализацию сегментов пути, включая удаление конечных точек и пробелов. Это обеспечивает доступ к путям, которые будут блокироваться нормализацией путей win32.

Примечание Это значение доступно начиная с Windows 10 версии 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 Преобразует входной путь в форму пути к устройству DOS расширенной длины (с префиксом \\?\), если он еще не в этой форме. Это обеспечивает доступ к путям, которые в противном случае недоступны из-за правил нормализации Win32 (которые могут удалять конечные точки и пробелы) и ограничений длины пути. Этот параметр подразумевает такое же поведение PATHCCH_DO_NOT_NORMALIZE_SEGMENTS.

Примечание Это значение доступно начиная с Windows 10 версии 1703.
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 При объединении или нормализации пути убедитесь, что есть обратная косая черта в конце.

Примечание Это значение доступно начиная с Windows 10 версии 1703.

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

Если эта функция завершается успешно, она возвращает S_OK. В противном случае он возвращает код HRESULT , включая, помимо прочего, следующее.

Код возврата Описание
E_INVALIDARG
 Значение cchPathOut больше PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 Сегмент пути содержит более PATHCCH_MAX_CCH символов или, если флаг PATHCCH_ALLOW_LONG_PATHS не задан, превышает стандартную длину сегмента пути в 256 символов.
E_OUTOFMEMORY
 Функции не удалось выделить буфер необходимого размера.

Комментарии

Эта функция отвечает на строки "." и "..", внедренные в путь. Строка ".." указывает на удаление непосредственно предшествующего сегмента пути. Строка "." указывает, что нужно пропустить следующий сегмент пути. Обратите внимание, что корневой сегмент пути не может быть удален. Если строк ".." больше, чем сегментов пути, функция возвращает S_OK а буфер, на который указывает pszPathOut , содержит одну обратную косую черту "\".

Все конечные точки удаляются из пути, за исключением случаев, когда предшествует символ "" дикого карта. В этом случае одна точка сохраняется после символа "", но все остальные конечные точки удаляются.

Если полученный путь является корневым диском ("x:"), добавляется обратная косая черта ("x:\").

Эта функция не преобразует косую черту (/) в обратную косую черту (\). При ненадежных входных данных эта функция сама по себе не может использоваться для преобразования путей в форму, которую можно сравнить с другими путями для вложенного пути или идентификатора. Вызывающие абоненты, которым требуется эта возможность, должны преобразовать косую черту вперед в обратную перед использованием этой функции.

В следующих примерах показан эффект этих строк.

Исходная строка Канонизированная строка
C:\name_1\.\name_2\.. \name_3 C:\name_1\name_3
C:\name_1\.. \name_2\.\name_3 C:\name_2\name_3
C:\name_1\name_2\.\name_3\.. \name_4 C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\.. \name_4\.. C:\name_1\name_2
C:\name_1\*... C:\name_1\*.
C:\.. C:\

Требования

Требование Значение
Минимальная версия клиента Windows 8 [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2012 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header pathcch.h
Библиотека Pathcch.lib

См. также раздел

PathCchCanonicalize