Função WinHttpReceiveResponse (winhttp.h)

Artigo
08/27/2023

A função WinHttpReceiveResponse aguarda para receber a resposta a uma solicitação HTTP iniciada por WinHttpSendRequest. Quando WinHttpReceiveResponse for concluído com êxito, os cabeçalhos de código e resposta status foram recebidos e estão disponíveis para o aplicativo inspecionar usando WinHttpQueryHeaders. Um aplicativo deve chamar WinHttpReceiveResponse antes de poder usar WinHttpQueryDataAvailable e WinHttpReadData para acessar o corpo da entidade de resposta (se houver).

Sintaxe

WINHTTPAPI BOOL WinHttpReceiveResponse(
  [in] HINTERNET hRequest,
  [in] LPVOID    lpReserved
);

Parâmetros

[in] hRequest

Identificador HINTERNET retornado por WinHttpOpenRequest e enviado por WinHttpSendRequest. Aguarde até que WinHttpSendRequest seja concluído para esse identificador antes de chamar WinHttpReceiveResponse.

[in] lpReserved

Esse parâmetro é reservado e deve ser NULL.

Retornar valor

Retorna TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.

Código do Erro	Descrição
ERROR_WINHTTP_CANNOT_CONNECT	Retornado se a conexão com o servidor falhou.
ERROR_WINHTTP_CHUNKED_ENCODING_HEADER_SIZE_OVERFLOW	Retornado quando uma condição de estouro é encontrada no curso da análise da codificação em partes.
ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED	Retornado quando o servidor solicita a autenticação do cliente.
ERROR_WINHTTP_CONNECTION_ERROR	A conexão com o servidor foi redefinida ou encerrada ou um protocolo SSL incompatível foi encontrado. Por exemplo, o WinHTTP versão 5.1 não dá suporte ao SSL2, a menos que o cliente o habilite especificamente.
ERROR_WINHTTP_HEADER_COUNT_EXCEEDED	Retornado quando um número maior de cabeçalhos estava presente em uma resposta do que o WinHTTP poderia receber.
ERROR_WINHTTP_HEADER_SIZE_OVERFLOW	Retornado por WinHttpReceiveResponse quando o tamanho dos cabeçalhos recebidos excede o limite do identificador de solicitação.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	A operação solicitada não pode ser executada porque o identificador fornecido não está no estado correto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	O tipo de identificador fornecido está incorreto para esta operação.
ERROR_WINHTTP_INTERNAL_ERROR	Ocorreu um erro interno.
ERROR_WINHTTP_INVALID_SERVER_RESPONSE	A resposta do servidor não pôde ser analisada.
ERROR_WINHTTP_INVALID_URL	A URL é inválida.
ERROR_WINHTTP_LOGIN_FAILURE	Falha na tentativa de logon. Quando esse erro é encontrado, o identificador de solicitação deve ser fechado com WinHttpCloseHandle. Um novo identificador de solicitação deve ser criado antes de tentar novamente a função que originalmente produziu esse erro.
ERROR_WINHTTP_NAME_NOT_RESOLVED	Não foi possível resolver o nome do servidor.
ERROR_WINHTTP_OPERATION_CANCELLED	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.
ERROR_WINHTTP_REDIRECT_FAILED	O redirecionamento falhou porque o esquema foi alterado ou todas as tentativas feitas para redirecionar falharam (o padrão é cinco tentativas).
ERROR_WINHTTP_RESEND_REQUEST	Falha na função WinHTTP. A função desejada pode ser repetida no mesmo identificador de solicitação.
ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW	Retornado quando uma resposta de entrada excede um limite interno de tamanho WinHTTP.
ERROR_WINHTTP_SECURE_FAILURE	Um ou mais erros foram encontrados no certificado SSL (protocolo SSL) enviado pelo servidor. Para determinar que tipo de erro foi encontrado, marcar para uma notificação de WINHTTP_CALLBACK_STATUS_SECURE_FAILURE em uma função de retorno de chamada status. Para obter mais informações, consulte WINHTTP_STATUS_CALLBACK.
ERROR_WINHTTP_TIMEOUT	O tempo limite da solicitação foi atingido.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	A URL especificou um esquema diferente de "http:" ou "https:".
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows)

Comentários

Mesmo quando WinHTTP é usado no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC foi definido no WinHttpOpen), essa função pode operar de forma síncrona ou assíncrona. Se essa função retornar FALSE, essa função falhará e você poderá chamar GetLastError para obter informações de erro estendidas. Se essa função retornar TRUE, o aplicativo deverá esperar o retorno de chamada de conclusão WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE , indicando êxito ou o retorno de chamada de conclusão WINHTTP_CALLBACK_STATUS_REQUEST_ERROR, indicando que a operação foi concluída de forma assíncrona, mas falhou.

Se uma função de retorno de chamada status tiver sido instalada com WinHttpSetStatusCallback, as seguintes notificações que foram definidas no parâmetro dwNotificationFlags de WinHttpSetStatusCallback indicam progresso no recebimento da resposta:

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE
WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
WINHTTP_CALLBACK_STATUS_REDIRECT

Se o servidor fechar a conexão, as seguintes notificações também serão relatadas, desde que tenham sido definidas no parâmetro dwNotificationFlags de WinHttpSetStatusCallback:

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Nota Para Windows XP e Windows 2000, consulte a seção Requisitos de tempo de execução da página inicial do WinHttp.

Exemplos

Este exemplo mostra o código que grava dados em um servidor HTTP. O nome do servidor fornecido no exemplo, www.wingtiptoys.com, é fictício e deve ser substituído pelo nome de um servidor para o qual você tem acesso de gravação.

    LPSTR pszData = "WinHttpWriteData Example";
    DWORD dwBytesWritten = 0;
    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/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.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       0);

    // Send a Request.
    if (hRequest) 
        bResults = WinHttpSendRequest( hRequest, 
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       (DWORD)strlen(pszData), 0);

    // Write data to the server.
    if (bResults)
        bResults = WinHttpWriteData( hRequest, pszData, 
                                     (DWORD)strlen(pszData), 
                                     &dwBytesWritten);

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

    // 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
Cliente mínimo com suporte	Windows XP, Windows 2000 Professional com SP3 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003, Windows 2000 Server com SP3 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winhttp.h
Biblioteca	Winhttp.lib
DLL	Winhttp.dll
Redistribuível	WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000.