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

Статья
11/20/2024

Функция 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 равно нулю, WinHttpCrackUrl предполагает, что строка pwszUrlnull завершена и определяет длину строки 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 хранится в указателе, а длина компонента хранится в элементе длины.

Если указатель содержит адрес предоставленного пользователем буфера, элемент длины должен содержать размер буфера. Функция WinHttpCrackUrl копирует компонент в буфер, а член длины имеет длину скопированного компонента, минус 1 для конечного конца строки. Если предоставленный пользователем буфер недостаточно велик, WinHttpCrackUr l возвращает 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 см. Run-Time в разделе "Требования к" начальной страницы 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) [классические приложения только]
целевая платформа	Виндоус
заголовка	winhttp.h
библиотеки	Winhttp.lib
DLL	Winhttp.dll
распространяемый	WinHTTP 5.0 и Internet Explorer 5.01 или более поздней версии в Windows XP и Windows 2000.

См. также

о службах HTTP Microsoft Windows (WinHTTP)

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

версии WinHTTP

WinHttpCreateUrl

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