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

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

  • Статья

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

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

[out] ppszPathOut

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

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

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

Комментарии

Эта функция поддерживает следующие формы альтернативных путей:

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

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

Требования

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