Функция WinHttpCrackUrl (winhttp.h)

Статья
08/27/2023

Функция 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, который не выполняет никаких специальных операций.

Значение	Значение
ICU_DECODE	Преобразует символы, которые имеют escape-кодирование (%xx), в их неинтервированную форму. Это не декодирует другие кодировки, такие как UTF-8. Эту функцию можно использовать только в том случае, если пользователь предоставляет буферы в структуре URL_COMPONENTS для копирования компонентов.
ICU_ESCAPE	Экранирует определенные символы в их escape-последовательности (%xx). Экранируемые символы — это символы, отличные от ASCII, или символы ASCII, которые должны быть экранированы для представления в HTTP-запросе. Эту функцию можно использовать только в том случае, если пользователь предоставляет буферы в структуре URL_COMPONENTS для копирования компонентов.
ICU_REJECT_USERPWD	Отклоняет URL-адреса в качестве входных данных, содержащих внедренные учетные данные (имя пользователя, пароль или и то, и другое). Если функция завершается сбоем из-за недопустимого URL-адреса, последующие вызовы GetLastError возвращают ERROR_WINHTTP_INVALID_URL.

[in, out] lpUrlComponents

Указатель на структуру URL_COMPONENTS , которая получает компоненты URL-адреса.

Возвращаемое значение

Возвращает значение TRUE , если функция выполнена успешно, или false в противном случае. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Среди возвращаемых кодов ошибок:

Коды ошибок	Описание
ERROR_WINHTTP_INTERNAL_ERROR	Произошла внутренняя ошибка.
ERROR_WINHTTP_INVALID_URL	Недопустимый URL-адрес.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Не удалось распознать схему URL-адресов или она не поддерживается.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения запрошенной операции. (Код ошибки 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"", функция возвращает неверные результаты.

Примечание Для Windows XP и Windows 2000 см. раздел Требования к времени выполнения начальной страницы WinHttp.

Примеры

В этом примере показано, как разбить 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.