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

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

  • Статья

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

Эта функция отличается от PathCchCanonicalizeEx тем, что вы ограничены конечным путем длины MAX_PATH.

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

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

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

Синтаксис

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

Параметры

[out] pszPathOut

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

[in] cchPathOut

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

[in] pszPathIn

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

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

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

Код возврата Описание
E_INVALIDARG
 Значение cchPathOut больше PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 Сегмент пути превышает стандартную длину сегмента пути в 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

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

PathCchCanonicalizeEx