Функция UrlCombineA (shlwapi.h)
При указании относительного URL-адреса и его основы возвращает URL-адрес в канонической форме.
Синтаксис
LWSTDAPI UrlCombineA(
[in] PCSTR pszBase,
[in] PCSTR pszRelative,
[out, optional] PSTR pszCombined,
[in, out] DWORD *pcchCombined,
DWORD dwFlags
);
Параметры
[in] pszBase
Тип: PCTSTR
Указатель на строку, завершающуюся значением NULL, с максимальной длиной INTERNET_MAX_URL_LENGTH, содержащую базовый URL-адрес.
[in] pszRelative
Тип: PCTSTR
Указатель на строку максимальной длины, заканчивающуюся значением NULL, INTERNET_MAX_URL_LENGTH, содержащую относительный URL-адрес.
[out, optional] pszCombined
Тип: PTSTR
Указатель на буфер, который при успешном возвращении этой функции получает строку, завершающуюся значением NULL, которая содержит объединенный URL-адрес.
[in, out] pcchCombined
Тип: DWORD*
Указатель на значение, которое при входе задается на количество символов в буфере pszCombined . Когда функция возвращается успешно, значение зависит от того, успешно ли выполняется функция или возвращается E_POINTER. Для других возвращаемых значений значение этого параметра не имеет смысла.
dwFlags
Тип: DWORD
Флаги, указывающие способ преобразования URL-адреса в каноническую форму. Можно объединить следующие флаги.
URL_DONT_SIMPLIFY (0x08000000)
Обработайте "/./" и "/.". /' в строке URL-адреса в виде литеральных символов, а не как сокращение для навигации. Дополнительные сведения см. в разделе Примечания.
URL_ESCAPE_PERCENT (0x00001000)
Преобразуйте любое вхождение "%" в его escape-последовательность.
URL_ESCAPE_SPACES_ONLY (0x04000000)
заменяют только пробелы на escape-последовательности. Этот флаг имеет приоритет над URL_ESCAPE_UNSAFE, но не применяется к непрозрачным URL-адресам.
URL_ESCAPE_UNSAFE (0x20000000)
заменяют небезопасные символы на escape-последовательности. Небезопасные символы — это символы, которые могут быть изменены во время передачи через Интернет и включают символы (<, ", >", #, {, }, |, , ^, ~, [, ], и '). Этот флаг применяется ко всем URL-адресам, включая непрозрачные URL-адреса.
URL_NO_META
Определяется как то же, что и URL_DONT_SIMPLIFY.
URL_PLUGGABLE_PROTOCOL (0x40000000)
Объединение URL-адресов с подключаемыми протоколами, определяемыми клиентом, в соответствии со спецификацией W3C. Этот флаг не применяется к стандартным протоколам, таким как FTP, HTTP, Gopher и т. д. Если этот флаг установлен, UrlCombine не упрощает URL-адреса, поэтому нет необходимости также задавать URL_DONT_SIMPLIFY.
URL_UNESCAPE (0x10000000)
Отмена экранирования всех escape-последовательностей, содержащихся в URL-адресах, с двумя исключениями. Escape-последовательности для "?" и "#" не отменяются. Если также задан один из флагов URL_ESCAPE_XXX, два URL-адреса сначала отменяются, затем объединяются, а затем экранируются.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 и более поздних версий. Процент кодирования всех символов, отличных от ASCII, в качестве эквивалентов UTF-8.
Возвращаемое значение
Тип: HRESULT
Возвращает стандартные коды ошибок COM, включая следующие.
Код возврата | Описание |
---|---|
|
pszCombined указывает на строку, содержащую объединенные URL-адреса. Значение pcchCombined равно количеству символов в строке, не считая завершающего символа NULL . |
|
Буфер был слишком мал. Для параметра pcchCombined задается минимальное количество символов, которое должен содержать буфер, включая завершающий символ NULL . |
Комментарии
Элементы между косой чертой обрабатываются как иерархические идентификаторы; последний элемент указывает сам документ. Чтобы добавить дополнительные элементы, необходимо ввести косую черту (/) после имени документа; В противном случае UrlCombine обменивает один документ на другой. Пример:
hRetVal = UrlCombine(TEXT("http://xyz/test/abc"),
TEXT("bar"),
lpszCombined,
&dwLength, 0);
Приведенный выше код возвращает URL-адрес. http://xyz/test/bar. Если вы хотите использовать объединенный URL-адрес http://xyz/test/abc/bar, используйте следующий вызов UrlCombine.
hRetVal = UrlCombine(TEXT("http://xyz/test/abc/"),
TEXT("bar"),
lpszCombined,
&dwLength, 0);
Если строка URL-адреса содержит '/.. /" или "/./" UrlCombine обычно обрабатывает символы так, как если бы они указывали на навигацию в иерархии URL-адресов. Функция упрощает URL-адреса перед их объединением. Например, "/hello/cruel/.. /world" упрощен до "/hello/world". Если флаг URL_DONT_SIMPLIFY установлен в dwFlags, функция не упрощает URL-адреса. В данном случае : "/hello/cruel/.. /world" остается как есть.
Примечание
Заголовок shlwapi.h определяет UrlCombine в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows 2000 Professional, Windows XP [только классические приложения] |
Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
Целевая платформа | Windows |
Header | shlwapi.h |
Библиотека | Shlwapi.lib |
DLL | Shlwapi.dll (версия 5.0 или более поздняя) |