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

Статья
11/20/2024

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

Синтаксис

BOOL InternetCanonicalizeUrlA(
  [in]      LPCSTR  lpszUrl,
  [out]     LPSTR   lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

Параметры

[in] lpszUrl

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

[out] lpszBuffer

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

[in, out] lpdwBufferLength

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

[in] dwFlags

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

Ценность	Значение
ICU_BROWSER_MODE	Не кодирует или декодирует символы после "#" или "?", и не удаляет конечный пробел после "?". Если это значение не указано, весь URL-адрес закодирован и удаляется конечный пробел.
ICU_DECODE	Преобразует все %XX последовательности в символы, включая escape-последовательности, перед анализом URL-адреса.
ICU_ENCODE_PERCENT	Кодирует любые признаки процента, возникшие. По умолчанию знаки процента не кодируются. Это значение доступно в Microsoft Internet Explorer 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	Существует недопустимый параметр строки, буфера, размера буфера или флагов.

Замечания

В Internet Explorer 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 Explorer 3.0 (или при настройке флага ICU_ENCODE_PERCENT для Internet Explorer 5 и более поздних версий) должны отслеживать использование этой функции в определенном URL-адресе. Если небезопасные символы в URL-адресе были преобразованы в escape-последовательности, при использовании InternetCanonicalizeUrl снова на URL-адресе (без флагов) происходит преобразование escape-последовательностей в другую escape-последовательность. Например, пустое пространство в URL-адресе будет преобразовано в escape-последовательность %20. Вызов InternetCanonicalizeUrl еще раз на URL-адресе приведет к преобразованию последовательности escape-%20 в %2520escape-последовательности, так как знак % является небезопасным символом, зарезервированным для escape-последовательностей и заменен функцией на escape-последовательность %25.

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	wininet.h
библиотеки	Wininet.lib
DLL	Wininet.dll

См. также

обработка единого указателя ресурсов

функций WinINet

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