Функция InternetCanonicalizeUrlW (wininet.h)

Статья
08/27/2023

Канонизирует URL-адрес, который включает преобразование небезопасных символов и пробелов в escape-последовательности.

Синтаксис

BOOL InternetCanonicalizeUrlW(
  [in]      LPCWSTR lpszUrl,
  [out]     LPWSTR  lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

Параметры

[in] lpszUrl

Указатель на строку, содержащую URL-адрес для канонизации.

[out] lpszBuffer

Указатель на буфер, который получает полученный канонический URL-адрес.

[in, out] lpdwBufferLength

Указатель на переменную, содержащую размер буфера lpszBuffer в символах. Если функция выполняется успешно, этот параметр получает количество символов, фактически скопированных в буфер lpszBuffer , который не включает завершающий пустой символ. Если функция завершается сбоем, этот параметр получает требуемый размер буфера в символах, включая завершающий символ NULL.

[in] dwFlags

Управляет канонизацией. Если флаги не указаны, функция преобразует все небезопасные символы и мета последовательности (например, .,\ .., и ...) в escape-последовательности. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
ICU_BROWSER_MODE	Не кодирует и не декодирует символы после "#" или "?", а также не удаляет пробелы в конце после "?". Если это значение не указано, кодируется весь URL-адрес и удаляется пробел в конце.
ICU_DECODE	Преобразует все последовательности %XX в символы, включая escape-последовательности, перед анализом URL-адреса.
ICU_ENCODE_PERCENT	Кодирует любые знаки процента, которые были обнаружены. По умолчанию знаки процента не кодируются. Это значение доступно в Microsoft Internet Обозреватель 5 и более поздних версий.
ICU_ENCODE_SPACES_ONLY	Кодирует только пробелы.
ICU_NO_ENCODE	Не преобразует небезопасные символы в escape-последовательности.
ICU_NO_META	Не удаляет мета-последовательности (например, "." и "..") из URL-адреса.

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

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError . Возможные ошибки:

Код возврата	Описание
ERROR_BAD_PATHNAME	Не удалось канонизировать URL-адрес.
ERROR_INSUFFICIENT_BUFFER	Канонический URL-адрес слишком велик, чтобы поместиться в предоставленный буфер. Параметру lpdwBufferLength присваивается размер в байтах буфера, необходимого для хранения канонизированного URL-адреса.
ERROR_INTERNET_INVALID_URL	Недопустимый формат URL-адреса.
ERROR_INVALID_PARAMETER	Имеется недопустимый параметр string, buffer, buffer size или flags.

В Internet Обозреватель 4.0 и более поздних версиях InternetCanonicalizeUrl всегда работает так, как если бы установлен флаг ICU_BROWSER_MODE. Клиентские приложения, которые должны канонизировать весь URL-адрес, должны использовать CoInternetParseUrl (с PARSE_CANONICALIZE действия и флагом URL_ESCAPE_UNSAFE) или UrlCanonicalize.

InternetCanonicalizeUrl всегда кодирует кодирование по умолчанию, даже если был указан флаг ICU_DECODE . Чтобы декодировать без повторного кодирования, используйте ICU_DECODE | ICU_NO_ENCODE. Если флаг ICU_DECODE используется без ICU_NO_ENCODE, перед анализом URL-адрес декодируется; После анализа небезопасные символы повторно кодируются. Эта функция обрабатывает произвольные схемы протоколов, но для этого она должна делать выводы из небезопасной кодировки.

Приложения, вызывающие InternetCanonicalizeUrl при использовании Internet Обозреватель 3.0 (или при установке флага ICU_ENCODE_PERCENT для Internet Обозреватель 5 и более поздних версий), должны отслеживать использование этой функции по определенному URL-адресу. Если небезопасные символы в URL-адресе были преобразованы в escape-последовательности, повторное использование InternetCanonicalizeUrl в URL-адресе (без флагов) приводит к тому, что escape-последовательности будут преобразованы в другую escape-последовательность. Например, пустой пробел в URL-адресе будет преобразован в escape-последовательность %20. Повторный вызов InternetCanonicalizeUrl по URL-адресу приведет к тому, что escape-последовательность %20 будет преобразована в escape-последовательность %2520, так как знак %является небезопасным символом, зарезервированным для escape-последовательностей и замененным функцией escape-последовательностью %25.

Как и все другие аспекты API WinINet, эту функцию нельзя безопасно вызывать из библиотеки DllMain или из конструкторов и деструкторов глобальных объектов.

Примечание WinINet не поддерживает реализации сервера. Кроме того, его не следует использовать из службы. Для серверных реализаций или служб используйте службы Microsoft Windows HTTP (WinHTTP).

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wininet.h
Библиотека	Wininet.lib
DLL	Wininet.dll

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

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

Функции WinINet

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