Функция 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

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

[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

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

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

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

Комментарии

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

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

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

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

Примеры

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

    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());
    }

Требования

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

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

Версии WinHTTP

WinHttpCloseHandle