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

Статья
08/27/2023

Функция WinHttpCreateUrl создает URL-адрес из компонентов, таких как имя узла и путь.

Синтаксис

WINHTTPAPI BOOL WinHttpCreateUrl(
  [in]      LPURL_COMPONENTS lpUrlComponents,
  [in]      DWORD            dwFlags,
  [out]     LPWSTR           pwszUrl,
  [in, out] LPDWORD          pdwUrlLength
);

Параметры

[in] lpUrlComponents

Указатель на структуру URL_COMPONENTS , содержащую компоненты, из которых создается URL-адрес.

[in] dwFlags

Флаги, управляющие работой этой функции. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
ICU_ESCAPE	Преобразует все небезопасные символы в соответствующие escape-последовательности в строке пути, на которую указывает член lpszUrlPath , а в lpszExtraInfo — в строку дополнительных сведений, на которую указывает член структуры URL_COMPONENTS , на которую указывает параметр lpUrlComponents .
ICU_REJECT_USERPWD	Отклоняет URL-адреса в качестве входных данных, содержащих либо имя пользователя, либо пароль, либо и то, и другое. Если функция завершается сбоем из-за недопустимого URL-адреса, последующие вызовы GetLastError будут возвращать ERROR_WINHTTP_INVALID_URL.

Значение

ICU_ESCAPE

Преобразует все небезопасные символы в соответствующие escape-последовательности в строке пути, на которую указывает член lpszUrlPath , а в lpszExtraInfo — в строку дополнительных сведений, на которую указывает член структуры URL_COMPONENTS , на которую указывает параметр lpUrlComponents .

ICU_REJECT_USERPWD

Отклоняет URL-адреса в качестве входных данных, содержащих либо имя пользователя, либо пароль, либо и то, и другое. Если функция завершается сбоем из-за недопустимого URL-адреса, последующие вызовы GetLastError будут возвращать ERROR_WINHTTP_INVALID_URL.

[out] pwszUrl

Указатель на буфер символов, который получает URL-адрес в виде строки расширенных символов (Юникод).

[in, out] pdwUrlLength

Указатель на переменную типа unsigned длинное целое число, которое получает длину буфера pwszUrl в расширенных символах (Юникод). При возврате функции этот параметр получает длину строки URL-адреса в символах минус 1 для завершающего символа. Если GetLastError возвращает ERROR_INSUFFICIENT_BUFFER, этот параметр получает количество расширенных символов, необходимых для хранения созданного URL-адреса.

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

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

Код ошибки	Описание
ERROR_WINHTTP_INTERNAL_ERROR	Внутренняя ошибка.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно доступной памяти для выполнения запрошенной операции. (Код ошибки Windows)

Даже если WinHTTP используется в асинхронном режиме, то есть если в WinHttpOpen задано WINHTTP_FLAG_ASYNC, эта функция работает синхронно. Возвращаемое значение указывает на успех или сбой. Чтобы получить расширенные данные об ошибках, вызовите Метод GetLastError.

Примечание Для 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 data. New data 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.

См. также раздел

Сведения о службах HTTP Microsoft Windows (WinHTTP)

Обработка универсальных указателей ресурсов

Версии WinHTTP

WinHttpCrackUrl

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