Функция UrlEscapeA (shlwapi.h)
Преобразует символы или суррогатные пары в URL-адресе, которые могут быть изменены во время передачи через Интернет ("небезопасные" символы) в соответствующие escape-последовательности. Суррогатные пары — это символы от U+10000 до U+10FFFF (в UTF-32) или от DC00 до DFFF (в UTF-16).
Синтаксис
LWSTDAPI UrlEscapeA(
[in] PCSTR pszUrl,
[out] PSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
Параметры
[in] pszUrl
Тип: PCTSTR
Строка, заканчивающаяся значением NULL, максимальная длина INTERNET_MAX_URL_LENGTH , которая содержит полный или частичный URL-адрес в соответствии со значением в dwFlags.
[out] pszEscaped
Тип: PTSTR
Буфер, получающий преобразованную строку, с небезопасными символами, преобразованными в escape-последовательности.
[in, out] pcchEscaped
Тип: DWORD*
Указатель на значение DWORD , которое при записи содержит количество символов в буфере pszEscaped . Перед вызовом UrlEscape вызывающее приложение должно задать значение, на которое ссылается pcchEscaped , размер буфера. При успешном возврате этой функции значение получает количество символов, записанных в буфер, не включая завершающий символ NULL .
Если возвращается код ошибки E_POINTER, буфер был слишком мал для хранения результата, а для значения, на которое ссылается pcchEscaped , устанавливается требуемое количество символов в буфере. Если возвращаются другие ошибки, значение, на которое ссылается pcchEscaped , не определено.
dwFlags
Тип: DWORD
Флаги, указывающие, какая часть URL-адреса предоставляется в pszURL и какие символы в этой строке следует преобразовать в escape-последовательности. Определены следующие флаги.
URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
Используется только в сочетании с URL_ESCAPE_SPACES_ONLY , чтобы предотвратить преобразование символов в запросе (часть URL-адреса после первого символа #или ?, обнаруженного в строке). Этот флаг не следует использовать отдельно или в сочетании с URL_ESCAPE_SEGMENT_ONLY.
URL_BROWSER_MODE
Определяется как то же, что и URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Преобразуйте в escape-последовательности только пробелы, включая пробелы в части ЗАПРОСА URL-адреса. Другие небезопасные символы не преобразуются в escape-последовательности. Этот флаг предполагает, что pszURL не содержит полный URL-адрес. Он ожидает только те части, которые следуют спецификации сервера.
Объедините этот флаг с URL_DONT_ESCAPE_EXTRA_INFO , чтобы предотвратить преобразование пробелов в части запроса URL-адреса.
Этот флаг нельзя сочетать с URL_ESCAPE_PERCENT или URL_ESCAPE_SEGMENT_ONLY.
URL_ESCAPE_PERCENT (0x00001000)
Преобразуйте любой символ %, найденный в разделе сегмента URL-адреса (этот раздел находится между спецификацией сервера и первым символом #или ?). По умолчанию символ %не преобразуется в escape-последовательность. Другие небезопасные символы в сегменте также преобразуются обычным образом.
Объединение этого флага с URL_ESCAPE_SEGMENT_ONLY включает эти символы % в часть запроса URL-адреса. Однако, так как флаг URL_ESCAPE_SEGMENT_ONLY приводит к тому, что вся строка считается сегментом, любой # или ? Символы также преобразуются.
Этот флаг нельзя сочетать с URL_ESCAPE_SPACES_ONLY.
URL_ESCAPE_SEGMENT_ONLY (0x00002000)
Указывает, что pszURL содержит только тот раздел URL-адреса, который следует за серверным компонентом, но перед запросом. Все небезопасные символы в строке преобразуются. Если при установке этого флага указан полный URL-адрес, преобразуются все небезопасные символы во всей строке, включая # и ? .
Объедините этот флаг с URL_ESCAPE_PERCENT , чтобы включить этот символ в преобразование.
Этот флаг нельзя сочетать с URL_ESCAPE_SPACES_ONLY или URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 и более поздние версии. Процент-кодирование всех символов, отличных от ASCII, в качестве эквивалентов UTF-8.
URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
Windows 8 и более поздних версий. Процент кодирования всех символов ASCII за пределами незарезервированного набора из URI RFC 3986 (a-zA-Z0-9-.~_).
Возвращаемое значение
Тип: HRESULT
В случае успешного выполнения возвращает S_OK. Если буфер pcchEscaped был слишком мал для хранения результата, возвращается E_POINTER, а для значения, на который указывает pcchEscaped , устанавливается требуемый размер буфера. В противном случае возвращается стандартное значение ошибки.
Комментарии
Для целей этого документа типичный URL-адрес состоит из трех разделов: сервер, сегмент и запрос. Пример:
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
Серверная часть — "http://microsoft.com/". Косая черта в конце считается частью серверной части.
Часть сегмента — это любая часть пути, найденная после серверной части, но перед первым # или ? символ, в данном случае просто "test.asp".
Часть запроса — это остаток пути от первого # или ? символ (включительно) до конца. В этом примере это "?url=/example/abc.asp?frame=true#fragment".
Небезопасные символы — это символы, которые могут быть изменены во время передачи через Интернет. Эта функция преобразует небезопасные символы в эквивалентные escape-последовательности "%xy". В следующей таблице показаны небезопасные символы и их escape-последовательности.
Знак | Escape-последовательность |
---|---|
^ | %5E |
& | %26 |
` | %60 |
{ | %7B |
} | %7D |
| | %7C |
] | %5D |
[ | %5B |
" | %22 |
< | %3C |
> | %3E |
\ | %5C |
Использование флага URL_ESCAPE_SEGMENT_ONLY также приводит к преобразованию # (%23), ? Символы (%3F) и / (%2F).
По умолчанию UrlEscape игнорирует любой текст после # или ? . Флаг URL_ESCAPE_SEGMENT_ONLY переопределяет это поведение, считая всю строку сегментом. Флаг URL_ESCAPE_SPACES_ONLY переопределяет это поведение, но только для символов пробела.
Примеры
В следующих примерах показано влияние различных флагов на URL-адрес. Пример URL-адреса недопустим, но преувеличен для демонстрационных целей.
// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query
// components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result = test%2Ft%e%3Cs%20t.asp
Примечание
Заголовок shlwapi.h определяет UrlEscape в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows 2000 Professional, Windows XP [только классические приложения] |
Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
Целевая платформа | Windows |
Header | shlwapi.h |
Библиотека | Shlwapi.lib |
DLL | Shlwapi.dll (версия 5.0 или более поздняя) |