Функция UrlCanonicalizeA (shlwapi.h)

Статья
08/26/2023

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

Синтаксис

LWSTDAPI UrlCanonicalizeA(
  [in]      PCSTR pszUrl,
  [out]     PSTR  pszCanonicalized,
  [in, out] DWORD *pcchCanonicalized,
            DWORD dwFlags
);

Параметры

[in] pszUrl

Тип: PCTSTR

Указатель на строку максимальной длины, заканчивающуюся значением NULL, INTERNET_MAX_URL_LENGTH, содержащую строку URL-адреса. Если строка не ссылается на файл, она должна содержать допустимую схему, например http://.

[out] pszCanonicalized

Тип: PTSTR

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

[in, out] pcchCanonicalized

Тип: DWORD*

Указатель на значение, которое при входе задается на количество символов в буфере pszCanonicalized .

dwFlags

Тип: DWORD

Флаги, указывающие способ преобразования URL-адреса в каноническую форму. Можно объединить следующие флаги.

URL_UNESCAPE (0x10000000)

Отмена экранирования всех escape-последовательностей, содержащихся в URL-адресах, с двумя исключениями. Escape-последовательности для "?" и "#" не отменяются. Если также задан один из флагов URL_ESCAPE_XXX, два URL-адреса сначала отменяются, затем объединяются, а затем экранируются.

URL_ESCAPE_UNSAFE (0x20000000)

заменяют небезопасные символы на escape-последовательности. Небезопасные символы — это символы, которые могут быть изменены во время передачи через Интернет и включают символы (<, >", ", #, {, }, |, , ^, [, ], и '). Этот флаг применяется ко всем URL-адресам, включая непрозрачные URL-адреса.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Объединение URL-адресов с подключаемыми протоколами, определяемыми клиентом, в соответствии со спецификацией W3C. Этот флаг не применяется к стандартным протоколам, таким как FTP, HTTP, Gopher и т. д. Если этот флаг установлен, UrlCombine не упрощает URL-адреса, поэтому нет необходимости также задавать URL_DONT_SIMPLIFY.

URL_ESCAPE_SPACES_ONLY (0x04000000)

заменяют только пробелы на escape-последовательности. Этот флаг имеет приоритет над URL_ESCAPE_UNSAFE, но не применяется к непрозрачным URL-адресам.

URL_DONT_SIMPLIFY (0x08000000)

обрабатывают "/./" и "/../" в строке URL-адреса как символы-литералы, а не сокращение для навигации. Дополнительные сведения см. в разделе Примечания.

URL_NO_META (0x08000000)

Определяется как то же, что и URL_DONT_SIMPLIFY.

URL_ESCAPE_PERCENT (0x00001000)

преобразуют все вхождения "%" в escape-последовательность.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 и более поздних версий. Процент кодирования всех символов, отличных от ASCII, в качестве эквивалентов UTF-8.

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

Тип: HRESULT

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

Если строка URL-адреса содержит "/.. /" или "/./" UrlCanonicalize обрабатывает символы как указывающие на навигацию в иерархии URL-адресов. Функция упрощает URL-адреса перед их объединением. Например, "/hello/cruel/.. /world" упрощен до "/hello/world". Исключения из этого поведения по умолчанию возникают в следующих случаях:

Если флаг URL_DONT_SIMPLIFY установлен в dwFlags, функция не упрощает URL-адреса. В данном случае : "/hello/cruel/.. /world" остается как есть.
Если "/.. /" или "/./" является первым сегментом в пути (например, "http://domain/../path1/path2/file.htm"), UrlCanonicalize выводит путь точно так же, как входные данные.

Примечание

Заголовок shlwapi.h определяет UrlCanonicalize в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows 2000 Professional, Windows XP [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	shlwapi.h
Библиотека	Shlwapi.lib
DLL	Shlwapi.dll (версия 5.0 или более поздняя)

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

Обработка универсальных указателей ресурсов

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