Функция 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".
Небезопасные символы — это символы, которые могут быть изменены во время транспорта через Интернет. Эта функция преобразует небезопасные символы в эквивалентные "%xy" escape-последовательности. В следующей таблице показаны небезопасные символы и их 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 Профессиональный, Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | shlwapi.h |
| библиотеки |
Shlwapi.lib |
| DLL | Shlwapi.dll (версия 5.0 или более поздняя версия) |