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

Статья
03/15/2023

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

Эта функция отличается от 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

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