Função WinHttpCloseHandle (winhttp.h)

  • Artigo

A função WinHttpCloseHandle fecha um único identificador HINTERNET (consulte Identificadores HINTERNET no WinHTTP).

Sintaxe

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

Parâmetros

[in] hInternet

Um identificador HINTERNET válido (consulte Identificadores HINTERNET no WinHTTP) a ser fechado.

Retornar valor

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

Códigos de erro Descrição
ERROR_WINHTTP_SHUTDOWN
 O suporte à função WinHTTP está sendo desligado ou descarregado.
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

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.

Se houver um retorno de chamada status registrado para o identificador que está sendo fechado e o identificador tiver sido criado com um valor de contexto não NULL, será feito um retorno de chamada WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING. Este é o último retorno de chamada feito do identificador e indica que o identificador está sendo destruído.

Um aplicativo pode encerrar uma solicitação assíncrona em andamento fechando o identificador de solicitação HINTERNET usando WinHttpCloseHandle. Lembre-se bem do seguinte:

  • Depois que um aplicativo chama WinHttpCloseHandle em um identificador WinHTTP, ele não pode chamar nenhuma outra função da API WinHTTP usando esse identificador de qualquer thread.
  • Mesmo depois que uma chamada para WinHttpCloseHandle retorna, o aplicativo ainda deve estar preparado para receber retornos de chamada para o identificador fechado, pois o WinHTTP pode derrubar o identificador de forma assíncrona. Se a solicitação assíncrona não puder ser concluída com êxito, o retorno de chamada receberá uma notificação WINHTTP_CALLBACK_STATUS_REQUEST_ERROR.
  • Se um aplicativo associar uma estrutura de dados de contexto ou um objeto ao identificador, ele deverá manter essa associação até que a função de retorno de chamada receba uma notificação de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Esta é a última notificação de retorno de chamada que o WinHTTP envia antes de excluir um objeto de identificador da memória. Para receber a notificação de retorno de chamada WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, o aplicativo deve habilitar o sinalizador WINHTTP_CALLBACK_FLAG_HANDLES na chamada WinHttpSetStatusCallback .
  • Antes de chamar WinHttpCloseHandle, um aplicativo pode chamar WinHttpSetStatusCallback para indicar que não devem ser feitos mais retornos de chamada:

    WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

    Pode parecer que a estrutura de dados de contexto pode ser liberada imediatamente em vez de precisar aguardar uma notificação de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , mas esse não é o caso: o WinHTTP não sincroniza WinHttpSetStatusCallback com retornos de chamada originados em threads de trabalho. Como resultado, um retorno de chamada já pode estar em andamento de outro thread, e o aplicativo pode receber uma notificação de retorno de chamada mesmo depois de ter o ponteiro da função de retorno de chamada NULL e excluído a estrutura de dados de contexto do identificador. Devido a essa condição de corrida potencial, seja conservador ao liberar a estrutura de contexto até depois de receber a notificação de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING .

Um aplicativo nunca deve chamar WinHttpCloseHandle em uma solicitação síncrona. Isso pode criar uma condição de corrida. Confira Identificadores HINTERNET no WinHTTP para obter mais informações.
Nota Para Windows XP e Windows 2000, consulte a seção Requisitos de tempo de execução da página inicial do WinHttp.
 

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.

Confira também

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

Versões do WinHTTP

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest