Compartilhar via

WINHTTP_STATUS_CALLBACK função de retorno de chamada (winhttp.h)

  • Artigo

O tipo WINHTTP_STATUS_CALLBACK representa uma função de retorno de chamada de status definida pelo aplicativo.

Sintaxe

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

Parâmetros

[in] hInternet

O identificador para o qual a função de retorno de chamada é chamada.

[in] dwContext

Um ponteiro para um DWORD que especifica o valor de contexto definido pelo aplicativo associado ao identificador no parâmetro hInternet .

Um valor de contexto pode ser atribuído a um identificador de Sessão, Conexão ou Solicitação chamando WinHttpSetOption com a opção WINHTTP_OPTION_CONTEXT_VALUE . Como alternativa, WinHttpSendRequest pode ser usado para associar um valor de contexto a um identificador de solicitação.

[in] dwInternetStatus

Aponta para um DWORD que especifica o código de status que indica por que a função de retorno de chamada é chamada. Esse valor pode ser um dos seguintes:

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

Encerrando a conexão com o servidor. O parâmetro lpvStatusInformation é NULL.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

Conectado com êxito ao servidor. O parâmetro lpvStatusInformation contém um ponteiro para um LPWSTR que indica o endereço IP do servidor na notação pontilhada.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

Conectando-se ao servidor. O parâmetro lpvStatusInformation contém um ponteiro para um LPWSTR que indica o endereço IP do servidor na notação pontilhada.

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Fechou com êxito a conexão com o servidor. O parâmetro lpvStatusInformation é NULL.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Os dados estão disponíveis para serem recuperados com WinHttpReadData. O parâmetro lpvStatusInformation aponta para um DWORD que contém o número de bytes de dados disponíveis. O parâmetro dwStatusInformationLength em si é 4 (o tamanho de um DWORD).

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

Um identificador HINTERNET foi criado. O parâmetro lpvStatusInformation contém um ponteiro para o identificador HINTERNET .

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

Esse valor de identificador foi encerrado. O parâmetro lpvStatusInformation contém um ponteiro para o identificador HINTERNET . Não haverá mais retornos de chamada para esse identificador.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

O cabeçalho de resposta foi recebido e está disponível com WinHttpQueryHeaders. O parâmetro lpvStatusInformation é NULL.

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

Recebeu uma mensagem de código de status intermediário (nível 100) do servidor. O parâmetro lpvStatusInformation contém um ponteiro para um DWORD que indica o código de status.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

O endereço IP do servidor foi encontrado com êxito. O parâmetro lpvStatusInformation contém um ponteiro para um LPWSTR que indica o nome que foi resolvido.

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

Os dados foram lidos com êxito do servidor. O parâmetro lpvStatusInformation contém um ponteiro para o buffer especificado na chamada para WinHttpReadData. O parâmetro dwStatusInformationLength contém o número de bytes lidos.

Quando usado por WinHttpWebSocketReceive, o parâmetro lpvStatusInformation contém um ponteiro para uma estrutura WINHTTP_WEB_SOCKET_STATUS e o parâmetro dwStatusInformationLength indica o tamanho de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

Aguardando o servidor responder a uma solicitação. O parâmetro lpvStatusInformation é NULL.

WINHTTP_CALLBACK_STATUS_REDIRECT

Uma solicitação HTTP está prestes a redirecionar automaticamente a solicitação. O parâmetro lpvStatusInformation contém um ponteiro para um LPWSTR que indica a nova URL. Neste ponto, o aplicativo pode ler todos os dados retornados pelo servidor com a resposta de redirecionamento e pode consultar os cabeçalhos de resposta. Ele também pode cancelar a operação fechando o identificador.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

Erro ao enviar uma solicitação HTTP. O parâmetro lpvStatusInformation contém um ponteiro para uma estrutura WINHTTP_ASYNC_RESULT . Seu membro dwResult indica a ID da função chamada e dwError indica o valor retornado.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

Enviou com êxito a solicitação de informações para o servidor. O parâmetro lpvStatusInformation contém um ponteiro para um DWORD que indica o número de bytes enviados.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

Pesquisando o endereço IP de um nome de servidor. O parâmetro lpvStatusInformation contém um ponteiro para o nome do servidor que está sendo resolvido.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

Recebeu com êxito uma resposta do servidor. O parâmetro lpvStatusInformation contém um ponteiro para um DWORD que indica o número de bytes recebidos.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

Um ou mais erros foram encontrados ao estabelecer uma conexão HTTPS (Segura) com o servidor. O parâmetro lpvStatusInformation contém um ponteiro para um DWORD que é uma combinação or bit a bit de valores de erro. Para obter mais informações, consulte a descrição de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

Enviando a solicitação de informações para o servidor. O parâmetro lpvStatusInformation é NULL.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

A solicitação foi concluída com êxito. O parâmetro lpvStatusInformation é o valor lpOptional passado para WinHttpSendRequest (o corpo da solicitação inicial) e o parâmetro dwStatusInformationLength indica o número desses bytes iniciais do corpo gravados com êxito (o valor dwOptionalLength passado para WinHttpSendRequest).

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Os dados foram gravados com êxito no servidor. O parâmetro lpvStatusInformation contém um ponteiro para um DWORD que indica o número de bytes gravados.

Quando usado por WinHttpWebSocketSend, o parâmetro lpvStatusInformation contém um ponteiro para uma estrutura WINHTTP_WEB_SOCKET_STATUS e o parâmetro dwStatusInformationLength indica o tamanho de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

A operação iniciada por uma chamada para WinHttpGetProxyForUrlEx foi concluída. Os dados estão disponíveis para serem recuperados com WinHttpReadData.

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

A conexão foi fechada com êxito por meio de uma chamada para WinHttpWebSocketClose. O parâmetro lpvStatusInformation é NULL.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

A conexão foi desligada com êxito por meio de uma chamada para WinHttpWebSocketShutdown. O parâmetro lpvStatusInformation é NULL.

[in] lpvStatusInformation

Um ponteiro para um buffer que especifica informações pertinentes a essa chamada para a função de retorno de chamada. O formato desses dados depende do valor do argumento dwInternetStatus . Para obter mais informações, consulte dwInternetStatus.

Se o argumento dwInternetStatus for WINHTTP_CALLBACK_STATUS_SECURE_FAILURE, lpvStatusInformation apontará para um DWORD que é uma combinação or bit a bit de um ou mais dos valores a seguir.

Valor Significado
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED
 A verificação de revogação de certificação foi habilitada, mas a verificação de revogação falhou ao verificar se um certificado foi revogado. O servidor usado para verificar se há revogação pode estar inacessível.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT
 O certificado SSL é inválido.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED
 O certificado SSL foi revogado.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA
 A função não está familiarizada com a Autoridade de Certificação que gerou o certificado do servidor.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID
 O nome comum do certificado SSL (campo nome do host) está incorreto, por exemplo, se você inseriu www.microsoft.com e o nome comum no certificado diz www.msn.com.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID
 A data do certificado SSL recebida do servidor é ruim. O certificado expirou.
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR
 O aplicativo sofreu um erro interno ao carregar as bibliotecas SSL.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT retornos de chamada de status fornecem um valor dwStatusInformationLength que corresponde à contagem de caracteres do LPWSTR apontado por lpvStatusInformation.

Retornar valor

Nenhum

Comentários

A função de retorno de chamada deve ser threadsafe e reentrante porque pode ser chamada em outro thread para uma solicitação separada e reentrada no mesmo thread para a solicitação atual. Portanto, ele deve ser codificado para lidar com a reentrância com segurança durante o processamento. Quando o parâmetro dwInternetStatus é igual a WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, o retorno de chamada não precisa ser capaz de lidar com a reentrância para a mesma solicitação, pois esse retorno de chamada tem a garantia de ser o último e não ocorre quando outras mensagens para essa solicitação são tratadas.

A função de retorno de chamada de status recebe atualizações sobre o status de operações assíncronas por meio de sinalizadores de notificação. As notificações que indicam que uma operação específica está concluída são chamadas de notificações de conclusão ou apenas conclusões. A tabela a seguir lista os seis sinalizadores de conclusão e a função correspondente que é concluída quando esse sinalizador é recebido.

Sinalizador de conclusão Função
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR Qualquer uma das funções acima quando ocorre um erro.
 

Como os retornos de chamada são feitos durante o processamento da solicitação, o aplicativo deve gastar o mínimo de tempo possível na função de retorno de chamada para evitar a degradação da taxa de transferência de dados na rede. Por exemplo, exibir uma caixa de diálogo em uma função de retorno de chamada pode ser uma operação tão longa que o servidor encerra a solicitação.

A função de retorno de chamada pode ser chamada em um contexto de thread diferente do thread que iniciou a solicitação.

Da mesma forma, não há afinidade de thread de retorno de chamada quando você chama WinHttp de forma assíncrona: uma chamada pode começar de um thread, mas qualquer outro thread pode receber o retorno de chamada.

Nota Para obter mais informações sobre a implementação no Windows XP e no Windows 2000, consulte Requisitos de tempo de execução.
 

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
Redistribuível WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000.

Confira também

Versões do WinHTTP

WinHttpSetStatusCallback