Share via

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

  • Статья

Функция WinHttpOpen инициализирует для приложения использование функций WinHTTP и возвращает дескриптор сеанса WinHTTP.

Синтаксис

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

Параметры

[in, optional] pszAgentW

Указатель на строковую переменную, содержащую имя приложения или сущности, вызывающей функции WinHTTP. Это имя используется в качестве агента пользователя в протоколе HTTP.

[in] dwAccessType

Тип требуемого доступа. Это может быть одно из следующих значений.

Значение Значение
WINHTTP_ACCESS_TYPE_NO_PROXY
 Разрешает все имена узлов напрямую без прокси-сервера.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
Важно Использование этого параметра не рекомендуется для Windows 8.1 и более новых версий. Вместо этого используйте WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY.
 
Извлекает статический прокси-сервер или прямую конфигурацию из реестра. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY не наследует параметры прокси-сервера браузера.

Конфигурация прокси-сервера WinHTTP задается одним из этих механизмов.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 Передает запросы к прокси-серверу, если не указан список обхода прокси-сервера и имя для разрешения обходит прокси-сервер. В этом случае эта функция использует значения, переданные для pwszProxyName и pwszProxyBypass.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 Использует системные и пользовательские параметры прокси-сервера (включая конфигурацию прокси-сервера Обозреватель Интернета), чтобы определить, какие прокси-серверы и прокси-серверы следует использовать. Автоматически пытается выполнить отработку отказа между несколькими прокси-серверами, разными конфигурациями прокси-сервера для каждого интерфейса и проверкой подлинности. Поддерживается в Windows 8.1 и более новых версиях.

[in] pszProxyW

Указатель на строковую переменную, содержащую имя прокси-сервера, используемого при указании доступа через прокси-сервер, задав параметру dwAccessTypeзначение WINHTTP_ACCESS_TYPE_NAMED_PROXY. Функции WinHTTP распознают только прокси-серверы типа CERN для HTTP. Если параметру dwAccessType не присвоено значение WINHTTP_ACCESS_TYPE_NAMED_PROXY, для этого параметра необходимо задать значение WINHTTP_NO_PROXY_NAME.

[in] pszProxyBypassW

Указатель на строковую переменную, содержащую необязательный список имен узлов или IP-адресов с разделителями с запятой, которые не должны маршрутизироваться через прокси-сервер, если параметру dwAccessType присвоено значение WINHTTP_ACCESS_TYPE_NAMED_PROXY. Список может содержать подстановочные знаки. Не используйте пустую строку, так как функция WinHttpOpen использует ее в качестве списка обхода прокси-сервера. Если этот параметр указывает макрос> local< в списке в качестве единственной записи, эта функция обходит любое имя узла, которое не содержит точку. Если параметру dwAccessType не присвоено значение WINHTTP_ACCESS_TYPE_NAMED_PROXY, для этого параметра необходимо задать значение WINHTTP_NO_PROXY_BYPASS.

[in] dwFlags

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

Значение Значение
WINHTTP_FLAG_ASYNC
 Используйте функции WinHTTP асинхронно. По умолчанию все функции WinHTTP, использующие возвращенный дескриптор HINTERNET , выполняются синхронно. Если этот флаг установлен, вызывающий объект должен указать функцию обратного вызова с помощью WinHttpSetStatusCallback.
WINHTTP_FLAG_SECURE_DEFAULTS
 Если этот флаг установлен, WinHttp потребует использования TLS 1.2 или более поздней версии. Если вызывающий объект попытается включить более старые версии TLS, задав WINHTTP_OPTION_SECURE_PROTOCOLS, это приведет к сбою при ERROR_ACCESS_DENIED. Кроме того, будет отключена резервная версия TLS. Обратите внимание, что установка этого флага также задает WINHTTP_FLAG_ASYNC флага.

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

Возвращает допустимый дескриптор сеанса в случае успешного выполнения или значение NULL в противном случае. Чтобы получить расширенные сведения об ошибке, вызовите Метод GetLastError. Среди возвращаемых кодов ошибок:

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

Комментарии

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

Функция WinHttpOpen является первой из функций WinHTTP, вызываемых приложением. Он инициализирует внутренние структуры данных WinHTTP и готовится к последующим вызовам из приложения. После завершения работы приложения с функциями WinHTTP оно должно вызвать WinHttpCloseHandle , чтобы освободить дескриптор сеанса и все связанные с ним ресурсы.

Приложение может выполнять любое количество вызовов WinHttpOpen, хотя обычно достаточно одного вызова. Каждый вызов WinHttpOpen открывает новый контекст сеанса. Так как данные пользователя не используются в нескольких контекстах сеанса, приложение, которое выполняет запросы от имени нескольких пользователей, должно создать отдельный сеанс для каждого пользователя, чтобы не предоставлять общий доступ к файлам cookie и состоянию проверки подлинности. Приложение должно определять отдельные варианты поведения для каждого экземпляра WinHttpOpen , например разные прокси-серверы, настроенные для каждого из них.

После завершения работы вызывающего приложения с дескриптором HINTERNET , возвращенным WinHttpOpen, его необходимо закрыть с помощью функции WinHttpCloseHandle .

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

Примеры

В следующем примере кода показано, как получить значение времени ожидания подключения по умолчанию.


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Требования

   
Минимальная версия клиента 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)

Версии WinHTTP

WinHttpCloseHandle