Função WinHttpSetStatusCallback (winhttp.h)

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.

[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.

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.

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

Confira também

Sobre os Serviços HTTP do Microsoft Windows (WinHTTP)

WINHTTP_STATUS_CALLBACK

Versões do WinHTTP

WinHttpConnect

WinHttpOpen