Função WinHttpSetStatusCallback (winhttp.h)

Artigo
03/15/2023

A função WinHttpSetStatusCallback configura uma função de retorno de chamada que o WinHTTP pode chamar conforme o progresso é feito durante uma operação.

Sintaxe

WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
  [in] HINTERNET               hInternet,
  [in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  [in] DWORD                   dwNotificationFlags,
  [in] DWORD_PTR               dwReserved
);

Parâmetros

[in] hInternet

Identificador HINTERNET para o qual o retorno de chamada deve ser definido.

[in] lpfnInternetCallback

Ponteiro para a função de retorno de chamada a ser chamada quando o progresso for feito. Defina isso como NULL para remover a função de retorno de chamada existente. Para obter mais informações sobre a função de retorno de chamada, consulte WINHTTP_STATUS_CALLBACK.

[in] dwNotificationFlags

Valor inteiro longo sem sinal que especifica sinalizadores para indicar quais eventos ativam a função de retorno de chamada.

Os valores possíveis são os seguintes.

Valor	Significado
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS	Ativa após qualquer notificação de conclusão. Esse sinalizador especifica que todas as notificações necessárias para operações de leitura ou gravação são usadas. Confira WINHTTP_STATUS_CALLBACK para obter uma lista de conclusões.
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS	Ativa qualquer notificação de alteração status, incluindo conclusões. Consulte WINHTTP_STATUS_CALLBACK para obter uma lista de notificações.
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME	Ativa ao iniciar e concluir a resolução de nomes.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER	Ativa ao iniciar e concluir a conexão com o servidor.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY	Ativa ao detectar o servidor proxy.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE	Ativa ao concluir uma consulta de dados.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE	Ativa quando os cabeçalhos de resposta estão disponíveis para recuperação.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE	Ativa após a conclusão de uma operação de leitura de dados.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR	Ativa quando ocorre um erro assíncrono.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST	Ativa ao iniciar e concluir o envio de um cabeçalho de solicitação com WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE	Ativa quando um cabeçalho de solicitação é enviado com WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE	Ativa após a conclusão de uma operação de postagem de dados.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE	Ativa ao iniciar e concluir o recebimento de um recurso do servidor HTTP.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION	Ativa ao iniciar e concluir o fechamento de uma conexão HTTP.
WINHTTP_CALLBACK_FLAG_HANDLES	Ativa quando um identificador HINTERNET é criado ou fechado.
WINHTTP_CALLBACK_FLAG_REDIRECT	Ativa quando a solicitação é redirecionada.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE	Ativa ao receber uma mensagem de código intermediária (nível 100) status do servidor.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE	Ativa após uma falha de conexão segura.

[in] dwReserved

Esse parâmetro é reservado e deve ser NULL.

Retornar valor

Se tiver êxito, retornará um ponteiro para a função de retorno de chamada status definida anteriormente ou NULL se não houver nenhuma função de retorno de chamada status definida anteriormente. Retorna WINHTTP_INVALID_STATUS_CALLBACK se a função de retorno de chamada não pôde ser instalada. 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_INCORRECT_HANDLE_TYPE	O tipo de identificador fornecido está incorreto para esta operação.
ERROR_WINHTTP_INTERNAL_ERROR	Ocorreu um erro interno.
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

Se você definir o retorno de chamada no identificador de sessão antes de criar o identificador de solicitação, o identificador de solicitação herdará o ponteiro da função de retorno de chamada de sua sessão pai.

Mesmo quando WinHTTP é usado no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC foi definido no 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.

As funções síncronas e assíncronas usam a função de retorno de chamada para indicar o progresso da solicitação, como resolver um nome, conectar-se a um servidor e assim por diante. A função de retorno de chamada é necessária para uma operação assíncrona.

Uma função de retorno de chamada pode ser definida em qualquer identificador e é herdada por identificadores derivados. Uma função de retorno de chamada pode ser alterada usando WinHttpSetStatusCallback, desde que não haja solicitações pendentes que precisem usar o valor de retorno de chamada anterior. No entanto, alterar a função de retorno de chamada em um identificador não altera os retornos de chamada em identificadores derivados, como o retornado por WinHttpConnect. Você deve alterar a função de retorno de chamada em cada nível.

Muitas funções WinHTTP executam várias operações na rede. Cada operação pode levar tempo para ser concluída e cada uma pode falhar.

Depois de iniciar a função WinHttpSetStatusCallback , a função de retorno de chamada pode ser acessada de dentro do WinHTTP para monitorar operações de rede com uso intensivo de tempo.

No final do processamento assíncrono, o aplicativo pode definir a função de retorno de chamada como NULL. Isso impede que o aplicativo cliente receba notificações adicionais.

O snippet de código a seguir mostra o método recomendado para definir a função de retorno de chamada como NULL.

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

No entanto, observe que o WinHTTP não sincroniza WinHttpSetStatusCallback com threads de trabalho. Se um retorno de chamada originado em outro thread estiver em andamento quando um aplicativo chamar WinHttpSetStatusCallback, o aplicativo ainda receberá uma notificação de retorno de chamada mesmo após WinHttpSetStatusCallback definir com êxito a função de retorno de chamada como NULL e retornar.

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

Exemplos

O exemplo a seguir mostra como instalar uma função de retorno de chamada para funções assíncronas do WinHTTP. O exemplo pressupõe que uma função WINHTTP_STATUS_CALLBACK chamada "AsyncCallback( )" foi implementada anteriormente:

    // 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)
    {
        // Install the status callback function.
        WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
                                               (WINHTTP_STATUS_CALLBACK)AsyncCallback,
                                               WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 
                                               NULL);
                                               
        // Place additional code here.
    
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

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.