Функция InternetCanonicalizeUrlA (wininet.h)
Канонизирует 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.
[in] dwFlags
Управляет канонизацией. Если флаги не указаны, функция преобразует все небезопасные символы и мета последовательности (например, .,\ .., и ...) в escape-последовательности. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Не кодирует и не декодирует символы после "#" или "?", а также не удаляет пробелы в конце после "?". Если это значение не указано, кодируется весь URL-адрес и удаляется пробел в конце. |
|
Преобразует все последовательности %XX в символы, включая escape-последовательности, перед анализом URL-адреса. |
|
Кодирует любые знаки процента, которые были обнаружены. По умолчанию знаки процента не кодируются. Это значение доступно в Microsoft Internet Обозреватель 5 и более поздних версий. |
|
Кодирует только пробелы. |
|
Не преобразует небезопасные символы в escape-последовательности. |
|
Не удаляет мета-последовательности (например, "." и "..") из URL-адреса. |
Возвращаемое значение
Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError . Возможные ошибки:
| Код возврата | Описание |
|---|---|
|
Не удалось канонизировать URL-адрес. |
|
Канонический URL-адрес слишком велик, чтобы поместиться в предоставленный буфер. Параметру lpdwBufferLength присваивается размер в байтах буфера, необходимого для хранения канонизированного URL-адреса. |
|
Недопустимый формат URL-адреса. |
|
Имеется недопустимый параметр 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.h определяет InternetCanonicalizeUrl в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | wininet.h |
| Библиотека | Wininet.lib |
| DLL | Wininet.dll |