Função WinHttpConnect (winhttp.h)
A função WinHttpConnect especifica o servidor de destino inicial de uma solicitação HTTP e retorna um identificador de conexão HINTERNET para uma sessão HTTP para esse destino inicial.
Sintaxe
WINHTTPAPI HINTERNET WinHttpConnect(
[in] HINTERNET hSession,
[in] LPCWSTR pswzServerName,
[in] INTERNET_PORT nServerPort,
[in] DWORD dwReserved
);
Parâmetros
[in] hSession
Identificador de sessão HINTERNET WinHTTP retornado por uma chamada anterior para WinHttpOpen.
[in] pswzServerName
Ponteiro para um cadeia de caracteresterminada nula que contém o nome do host de um servidor HTTP. Como alternativa, a cadeia de caracteres pode conter o endereço IP do site como uma cadeia de caracteres, por exemplo, 10.0.1.45. Observe que o WinHttp não aceita nomes de host internacionais sem convertê-los primeiro em punycode. Para obter mais informações, consulte manipulação de IDNs (nomes de domínio internacionalizados).
[in] nServerPort
Inteiro sem sinal que especifica a porta TCP/IP no servidor para o qual uma conexão é feita. Esse parâmetro pode ser qualquer número de porta TCP/IP válido ou um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Usa a porta padrão para servidores HTTP (porta 80). |
|
Usa a porta padrão para servidores HTTPS (porta 443). A seleção dessa porta não estabelece automaticamente uma conexão segura. Você ainda deve especificar o uso de semântica de transação segura usando o sinalizador WINHTTP_FLAG_SECURE com WinHttpOpenRequest. |
|
Usa a porta 80 para HTTP e a porta 443 para HTTPS (Secure Hypertext Transfer Protocol). |
[in] dwReserved
Esse parâmetro é reservado e deve ser 0.
Valor de retorno
Retorna um identificador de conexão válido para a sessão HTTP se a conexão for bem-sucedida ou NULL caso contrário. Para recuperar informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.
| Códigos de erro | Descrição |
|---|---|
|
O tipo de identificador fornecido está incorreto para esta operação. |
|
Ocorreu um erro interno. |
|
A URL é inválida. |
|
A operação foi cancelada, geralmente porque o identificador no qual a solicitação estava operando foi fechado antes da conclusão da operação. |
|
O esquema de URL não pôde ser reconhecido ou não tem suporte. |
|
O suporte à função WinHTTP está sendo desligado ou descarregado. |
|
Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows) |
Observações
Mesmo quando WinHTTP é usado no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC foi definido em WinHttpOpen), essa função opera de forma síncrona. O valor retornado indica êxito ou falha. Para obter informações de erro estendidas, chame GetLastError.
Depois que o aplicativo de chamada terminar de usar o identificador HINTERNET retornado por WinHttpConnect, ele deverá ser fechado usando a função WinHttpCloseHandle.
WinHttpConnect especifica o servidor HTTP de destino, no entanto, uma resposta pode vir de outro servidor se a solicitação foi redirecionada. Você pode determinar a URL do servidor que envia a resposta chamando WinHttpQueryOption com o sinalizador WINHTTP_OPTION_URL.
Exemplos
O exemplo a seguir mostra como usar a semântica de transação segura para baixar um recurso de um servidor HTTPS. O código de exemplo inicializa a API (interface de programação de aplicativo) do Microsoft Windows HTTP Services (WinHTTP), seleciona um servidor HTTPS de destino e, em seguida, abre e envia uma solicitação para esse recurso seguro.
WinHttpQueryDataAvailable é usado com o identificador de solicitação para determinar quantos dados estão disponíveis para download e WinHttpReadData é usado para ler esses dados. Esse processo se repete até que todo o documento seja recuperado e exibido.
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);
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP, Windows 2000 Professional com SP3 [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003, Windows 2000 Server com SP3 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winhttp.h |
| biblioteca | Winhttp.lib |
| de DLL |
Winhttp.dll |
| redistribuível | WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000. |