Функция WinHttpCrackUrl (winhttp.h)
Функция WinHttpCrackUrl разделяет URL-адрес на компоненты, такие как имя узла и путь.
Синтаксис
WINHTTPAPI BOOL WinHttpCrackUrl(
[in] LPCWSTR pwszUrl,
[in] DWORD dwUrlLength,
[in] DWORD dwFlags,
[in, out] LPURL_COMPONENTS lpUrlComponents
);
Параметры
[in] pwszUrl
Указатель на строку, содержащую канонический URL-адрес для разделения. WinHttpCrackUrl не проверка этот URL-адрес для допустимости или правильного формата, прежде чем пытаться взломать его.
[in] dwUrlLength
Длина строки pwszUrl в символах. Если параметру dwUrlLength присвоено значение 0, WinHttpCrackUrl предполагает, что строка pwszUrl заканчивается null , и определяет длину строки pwszUrl на основе этого предположения.
[in] dwFlags
Флаги, управляющие операцией. Этот параметр может быть сочетанием одного или нескольких следующих флагов (значения могут быть побитовой ИЛИ). Или параметр может иметь значение 0, который не выполняет никаких специальных операций.
| Значение | Значение |
|---|---|
|
Преобразует символы, которые имеют escape-кодирование (%xx), в их неинтервированную форму. Это не декодирует другие кодировки, такие как UTF-8. Эту функцию можно использовать только в том случае, если пользователь предоставляет буферы в структуре URL_COMPONENTS для копирования компонентов. |
|
Экранирует определенные символы в их escape-последовательности (%xx). Экранируемые символы — это символы, отличные от ASCII, или символы ASCII, которые должны быть экранированы для представления в HTTP-запросе. Эту функцию можно использовать только в том случае, если пользователь предоставляет буферы в структуре URL_COMPONENTS для копирования компонентов. |
|
Отклоняет URL-адреса в качестве входных данных, содержащих внедренные учетные данные (имя пользователя, пароль или и то, и другое). Если функция завершается сбоем из-за недопустимого URL-адреса, последующие вызовы GetLastError возвращают ERROR_WINHTTP_INVALID_URL. |
[in, out] lpUrlComponents
Указатель на структуру URL_COMPONENTS , которая получает компоненты URL-адреса.
Возвращаемое значение
Возвращает значение TRUE , если функция выполнена успешно, или false в противном случае. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Среди возвращаемых кодов ошибок:
| Коды ошибок | Описание |
|---|---|
|
Произошла внутренняя ошибка. |
|
Недопустимый URL-адрес. |
|
Не удалось распознать схему URL-адресов или она не поддерживается. |
|
Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows) |
Комментарии
Даже если WinHTTP используется в асинхронном режиме (то есть, если WINHTTP_FLAG_ASYNC задано в WinHttpOpen), эта функция работает синхронно. Возвращаемое значение указывает на успех или сбой. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Необходимые компоненты указываются членами структуры URL_COMPONENTS . Каждый компонент имеет указатель на значение и элемент, в котором хранится длина хранимого значения. Если и значение, и длина компонента равны нулю, этот компонент не возвращается. Если указатель на значение компонента не равен NULL и значение соответствующего элемента длины не равно нулю, адрес первого символа соответствующего компонента в строке pwszUrl хранится в указателе, а длина компонента хранится в элементе длины.
Если указатель содержит адрес буфера, предоставленного пользователем, член length должен содержать размер буфера. Функция WinHttpCrackUrl копирует компонент в буфер, а для элемента length устанавливается длина скопированного компонента минус 1 для признака конца строки. Если предоставленный пользователем буфер недостаточно велик, WinHttpCrackUrl возвращает значение FALSE, а GetLastError — ERROR_INSUFFICIENT_BUFFER.
Для правильной работы WinHttpCrackUrl размер структуры URL_COMPONENTS должен храниться в элементе dwStructSize этой структуры.
Если интернет-протокол URL-адреса, переданного для pwszUrl , не является HTTP или HTTPS, то WinHttpCrackUrl возвращает значение FALSE , а GetLastError указывает, что
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.
WinHttpCrackUrl не проверка допустимость или формат URL-адреса, прежде чем пытаться взломать его. В результате, если передается строка, например ""http://server?Bad=URL"", функция возвращает неверные результаты.
Примеры
В этом примере показано, как разбить URL-адрес на его компоненты, обновить компонент, а затем восстановить URL-адрес.
URL_COMPONENTS urlComp;
LPCWSTR pwszUrl1 =
L"http://search.msn.com/results.asp?RS=CHECKED&FORM=MSNH&v=1&q=wininet";
DWORD dwUrlLen = 0;
// Initialize the URL_COMPONENTS structure.
ZeroMemory(&urlComp, sizeof(urlComp));
urlComp.dwStructSize = sizeof(urlComp);
// Set required component lengths to non-zero
// so that they are cracked.
urlComp.dwSchemeLength = (DWORD)-1;
urlComp.dwHostNameLength = (DWORD)-1;
urlComp.dwUrlPathLength = (DWORD)-1;
urlComp.dwExtraInfoLength = (DWORD)-1;
// Crack the URL.
if (!WinHttpCrackUrl( pwszUrl1, (DWORD)wcslen(pwszUrl1), 0, &urlComp))
{
printf("Error %u in WinHttpCrackUrl.\n", GetLastError());
}
else
{
// Change the search information.
// New info is the same length.
urlComp.lpszExtraInfo = L"?RS=CHECKED&FORM=MSNH&v=1&q=winhttp";
// Obtain the size of the new URL and allocate memory.
WinHttpCreateUrl( &urlComp, 0, NULL, &dwUrlLen);
LPWSTR pwszUrl2 = new WCHAR[dwUrlLen];
// Create a new URL.
if(!WinHttpCreateUrl( &urlComp, 0, pwszUrl2, &dwUrlLen))
{
printf("Error %u in WinHttpCreateUrl.\n", GetLastError());
}
else
{
// Show both URLs.
printf("Old URL: %S\nNew URL: %S\n", pwszUrl1, pwszUrl2);
}
// Free allocated memory.
delete [] pwszUrl2;
}
Требования
| Минимальная версия клиента | Windows XP, Windows 2000 Профессиональная с пакетом обновления 3 (SP3) [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003, Windows 2000 Server с пакетом обновления 3 (SP3) [только классические приложения] |
| Целевая платформа | Windows |
| Header | winhttp.h |
| Библиотека | Winhttp.lib |
| DLL | Winhttp.dll |
| Распространяемые компоненты | WinHTTP 5.0 и Internet Обозреватель 5.01 или более поздней версии в Windows XP и Windows 2000. |
См. также раздел
Сведения о службах MICROSOFT Windows HTTP (WinHTTP)