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

Статья
08/27/2023

Функция WinHttpConnect указывает исходный целевой сервер HTTP-запроса и возвращает дескриптор подключения HINTERNET к сеансу HTTP для этого начального целевого объекта.

Синтаксис

WINHTTPAPI HINTERNET WinHttpConnect(
  [in] HINTERNET     hSession,
  [in] LPCWSTR       pswzServerName,
  [in] INTERNET_PORT nServerPort,
  [in] DWORD         dwReserved
);

Параметры

[in] hSession

Допустимый дескриптор сеанса HINTERNET WinHTTP, возвращенный предыдущим вызовом WinHttpOpen.

[in] pswzServerName

Указатель на строку, завершающуюся нулевым значением, которая содержит имя узла HTTP-сервера. Кроме того, строка может содержать IP-адрес сайта в ASCII, например 10.0.1.45. Обратите внимание, что WinHttp не принимает международные имена узлов, не преобразуя их сначала в Punycode. Дополнительные сведения см. в разделе Обработка международных доменных имен (IDN).

[in] nServerPort

Целое число без знака, указывающее порт TCP/IP на сервере, к которому установлено соединение. Этот параметр может быть любым допустимым номером порта TCP/IP или одним из следующих значений.

Значение	Значение
INTERNET_DEFAULT_HTTP_PORT	Использует порт по умолчанию для HTTP-серверов (порт 80).
INTERNET_DEFAULT_HTTPS_PORT	Использует порт по умолчанию для HTTPS-серверов (порт 443). При выборе этого порта безопасное подключение не устанавливается автоматически. По-прежнему необходимо указать использование семантики безопасных транзакций с помощью флага WINHTTP_FLAG_SECURE с WinHttpOpenRequest.
INTERNET_DEFAULT_PORT	Использует порт 80 для HTTP и порт 443 для протокола HTTPS.

[in] dwReserved

Этот параметр зарезервирован и должен иметь значение 0.

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

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

Коды ошибок	Описание
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Для этой операции указан неправильный тип дескриптора.
ERROR_WINHTTP_INTERNAL_ERROR	Произошла внутренняя ошибка.
ERROR_WINHTTP_INVALID_URL	Недопустимый URL-адрес.
ERROR_WINHTTP_OPERATION_CANCELLED	Операция была отменена, как правило, из-за того, что дескриптор, с которым выполнялся запрос, был закрыт до завершения операции.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Не удалось распознать схему URL-адресов или она не поддерживается.
ERROR_WINHTTP_SHUTDOWN	Поддержка функции WinHTTP завершается или выгружается.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows)

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

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

WinHttpConnect указывает целевой HTTP-сервер, однако ответ может поступать с другого сервера, если запрос был перенаправлен. Вы можете определить URL-адрес сервера, отправляющего ответ, вызвав WinHttpQueryOption с флагом WINHTTP_OPTION_URL.

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

Примеры

В следующем примере показано, как использовать семантику безопасных транзакций для скачивания ресурса с HTTPS-сервера. Пример кода инициализирует программный интерфейс (API) служб HTTP Microsoft Windows (WinHTTP), выбирает целевой HTTPS-сервер, а затем открывает и отправляет запрос на этот безопасный ресурс.
WinHttpQueryDataAvailable используется с дескриптором запроса для определения объема данных, доступных для скачивания, а затем WinHttpReadData используется для чтения данных. Этот процесс повторяется до тех пор, пока не будет извлечен и отображен весь документ.


    DWORD dwSize = 0;
    DWORD dwDownloaded = 0;
    LPSTR pszOutBuffer;
    BOOL  bResults = FALSE;
    HINTERNET  hSession = NULL, 
               hConnect = NULL,
               hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen( L"WinHTTP Example/1.0",  
                            WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                            WINHTTP_NO_PROXY_NAME, 
                            WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
                                   INTERNET_DEFAULT_HTTPS_PORT, 0);

    // Create an HTTP request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       WINHTTP_FLAG_SECURE);

    // Send a request.
    if (hRequest)
        bResults = WinHttpSendRequest( hRequest,
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       0, 0);

 
    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // Keep checking for data until there is nothing left.
    if (bResults)
        do 
        {
            // Check for available data.
            dwSize = 0;
            if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
                printf("Error %u in WinHttpQueryDataAvailable.\n", GetLastError());

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                dwSize=0;
            }
            else
            {
                // Read the Data.
                ZeroMemory(pszOutBuffer, dwSize+1);

                if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                                      dwSize, &dwDownloaded))
                    printf( "Error %u in WinHttpReadData.\n", GetLastError());
                else
                    printf( "%s\n", pszOutBuffer);
            
                // Free the memory allocated to the buffer.
                delete [] pszOutBuffer;
            }

        } while (dwSize > 0);


    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n", GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Требования

Требование	Значение
Минимальная версия клиента	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.