Функция WinHttpConnect (winhttp.h)
Функция WinHttpConnect указывает исходный целевой сервер HTTP-запроса и возвращает дескриптор подключения HINTERNET сеанс HTTP для этого начального целевого объекта.
Синтаксис
WINHTTPAPI HINTERNET WinHttpConnect(
[in] HINTERNET hSession,
[in] LPCWSTR pswzServerName,
[in] INTERNET_PORT nServerPort,
[in] DWORD dwReserved
);
Параметры
[in] hSession
Допустимый дескриптор сеанса WinHTTP HINTERNET, возвращенный предыдущим вызовом WinHttpOpen.
[in] pswzServerName
Указатель на строку null-terminated, содержащую имя узла HTTP-сервера. Кроме того, строка может содержать IP-адрес сайта в виде строки, например 10.0.1.45. Обратите внимание, что WinHttp не принимает международные имена узлов, не преобразовывая их сначала в Punycode. Дополнительные сведения см. в разделе Обработка международных доменных имен (IDN).
[in] nServerPort
Целое число без знака, указывающее порт TCP/IP на сервере, к которому выполняется подключение. Этот параметр может быть любым допустимым номером порта TCP/IP или одним из следующих значений.
| Ценность | Значение |
|---|---|
|
Использует порт по умолчанию для HTTP-серверов (порт 80). |
|
Использует порт по умолчанию для HTTPS-серверов (порт 443). При выборе этого порта не устанавливается безопасное подключение автоматически. По-прежнему необходимо указать использование семантики безопасных транзакций с помощью флага WINHTTP_FLAG_SECURE с WinHttpOpenRequest. |
|
Использует порт 80 для ПРОТОКОЛА HTTP и порта 443 для протокола безопасной передачи гипертекстов (HTTPS). |
[in] dwReserved
Этот параметр зарезервирован и должен иметь значение 0.
Возвращаемое значение
Возвращает допустимый дескриптор подключения к сеансу HTTP, если подключение выполнено успешно или null в противном случае. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. Среди возвращенных кодов ошибок приведены следующие коды.
| Коды ошибок | Описание |
|---|---|
|
Тип дескриптора некорректен для этой операции. |
|
Произошла внутренняя ошибка. |
|
Недопустимый URL-адрес. |
|
Операция была отменена, как правило, так как дескриптор, с которым был выполнен запрос, был закрыт до завершения операции. |
|
Схема URL-адресов не может быть распознана или не поддерживается. |
|
Поддержка функции WinHTTP завершается или выгружается. |
|
Недостаточно памяти было доступно для выполнения запрошенной операции. (Код ошибки Windows) |
Замечания
Даже если WinHTTP используется в асинхронном режиме (то есть если WINHTTP_FLAG_ASYNC задан в WinHttpOpen), эта функция работает синхронно. Возвращаемое значение указывает на успешность или сбой. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
После завершения вызова приложения с помощью дескриптора HINTERNET, возвращаемого WinHttpConnect, его необходимо закрыть с помощью функции WinHttpCloseHandle.
WinHttpConnect указывает целевой HTTP-сервер, однако ответ может поступать с другого сервера, если запрос был перенаправлен. Url-адрес сервера, отправляющего ответ, можно определить, вызвав WinHttpQueryOption с флагом WINHTTP_OPTION_URL.
Примеры
В следующем примере показано, как использовать семантику безопасной транзакции для скачивания ресурса с сервера HTTPS. Пример кода инициализирует интерфейс программирования приложений microsoft Windows HTTP Services (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) [классические приложения только] |
| целевая платформа | Виндоус |
| заголовка | winhttp.h |
| библиотеки |
Winhttp.lib |
| DLL | Winhttp.dll |
| распространяемый | WinHTTP 5.0 и Internet Explorer 5.01 или более поздней версии в Windows XP и Windows 2000. |