Функция UrlEscapeA (shlwapi.h)

Статья
08/26/2023

Преобразует символы или суррогатные пары в 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 , устанавливается требуемый размер буфера. В противном случае возвращается стандартное значение ошибки.

Небезопасные символы — это символы, которые могут быть изменены во время передачи через Интернет. Эта функция преобразует небезопасные символы в эквивалентные 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 или более поздняя)

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

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

Share via