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

Статья
2025-02-20

Преобразует строку пути в каноническую форму.

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

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

Примечание Этой функции, PathCchCanonicalizeили PathCchCanonicalizeEx, следует использовать вместо PathCanonicalize.

Синтаксис

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

Параметры

[in] pszPathIn

Указатель на буфер, содержащий исходную строку. Это значение не может быть NULL.

[in] dwFlags

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

Ценность	Значение
PATHCCH_NONE 0x0000000	Не разрешать построение путей \\?\ (т. е. длинных путей) дольше, чем MAX_PATH.
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Разрешить сборку путей \\?\ дольше, чем 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.
PATHCCH_CANONICALIZE_SLASHES 0x00000040	Преобразуйте косую черту вперед в косую черту и свернуть несколько косой черты. Примечание Это значение доступно начиная с Windows 11 (пакет SDK версии 10.0.22000.194).

[out] ppszPathOut

Адрес указателя на буфер, который, когда эта функция возвращается успешно, получает каноническую строку пути. Вызывающий объект несет ответственность за освобождение этого ресурса, если он больше не нужен, вызывая функцию LocalFree. Это значение не может быть NULL.

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

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

Замечания

Эта функция поддерживает эти альтернативные формы пути:

\\?\
\\?\\UNC\
\\?\Volume{guid}\

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 8 [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2012 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	pathcch.h
библиотеки	Pathcch.lib