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

Статья
11/20/2024

Если указан относительный 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, включая следующие.

Возвращаемый код	Описание
S_OK	pszCombined указывает на строку, содержащую объединенные URL-адреса. Значение pcchCombined задается числом символов в строке, а не подсчитывая конечный символ NULL символа.
E_POINTER	Буфер был слишком мал. Значение 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/жестоко/.. /world упрощено для "/hello/world". Если флаг URL_DONT_SIMPLIFY задан в dwFlags, функция не упрощает URL-адреса. В этом случае :/hello/жестоко/.. /world" остается, как это.

Заметка

Заголовок shlwapi.h определяет UrlCombine как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный, Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shlwapi.h
библиотеки	Shlwapi.lib
DLL	Shlwapi.dll (версия 5.0 или более поздняя версия)

См. также

обработка единого указателя ресурсов

UrlCanonicalize

Поделиться через