Função CloseHandle (handleapi.h)

Artigo
10/05/2022
3 minutos para o fim da leitura

Fecha um identificador de objeto aberto.

Sintaxe

BOOL CloseHandle(
  [in] HANDLE hObject
);

Parâmetros

[in] hObject

Um identificador válido para um objeto aberto.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Se o aplicativo estiver em execução em um depurador, a função gerará uma exceção se receber um valor de identificador que não seja válido ou um valor pseudo-identificador. Isso pode acontecer se você fechar um identificador duas vezes ou se você chamar CloseHandle em um identificador retornado pela função FindFirstFile em vez de chamar a função FindClose .

Comentários

A função CloseHandle fecha as alças dos seguintes objetos:

Token de acesso
Dispositivo de comunicações
Entrada do console
Buffer de tela do console
Evento
Arquivo
Mapeamento de arquivos
Porta de conclusão de E/S
Trabalho
Maillot
Notificação de recurso de memória
Mutex
Pipe nomeado
Pipe
Processo
Sinal
Thread
Transação
Temporizador de espera

A documentação das funções que criam esses objetos indica que CloseHandle deve ser usado quando você terminar de usar o objeto e o que acontece com operações pendentes no objeto após o fechamento do identificador. Em geral, CloseHandle invalida o identificador de objeto especificado, decrementa a contagem de identificadores do objeto e executa verificações de retenção de objeto. Depois que o último identificador de um objeto é fechado, o objeto é removido do sistema. Para obter um resumo das funções de criador para esses objetos, consulte Objetos Kernel.

Em geral, um aplicativo deve chamar CloseHandle uma vez para cada identificador aberto. Normalmente, não é necessário chamar CloseHandle se uma função que usa um identificador falhar com ERROR_INVALID_HANDLE, pois esse erro geralmente indica que o identificador já está invalidado. No entanto, algumas funções usam ERROR_INVALID_HANDLE para indicar que o objeto em si não é mais válido. Por exemplo, uma função que tenta usar um identificador para um arquivo em uma rede pode falhar com ERROR_INVALID_HANDLE se a conexão de rede for cortada, porque o objeto de arquivo não está mais disponível. Nesse caso, o aplicativo deve fechar o identificador.

Se um identificador for transacionado, todos os identificadores associados a uma transação deverão ser fechados antes que a transação seja confirmada. Se um identificador transacionado foi aberto chamando CreateFileTransacted com o sinalizador FILE_FLAG_DELETE_ON_CLOSE, o arquivo não será excluído até que o aplicativo feche o identificador e chame CommitTransaction. Para obter mais informações sobre objetos transacionados, consulte Working With Transactions.

Fechar um identificador de thread não encerra o thread associado nem remove o objeto thread. Fechar um identificador de processo não encerra o processo associado nem remove o objeto de processo. Para remover um objeto thread, você deve encerrar o thread e fechar todas as alças do thread. Para obter mais informações, consulte Terminating a Thread. Para remover um objeto de processo, você deve encerrar o processo e fechar todos os identificadores do processo. Para obter mais informações, consulte Terminando um processo.

Fechar um identificador para um mapeamento de arquivo pode ter êxito mesmo quando há exibições de arquivo que ainda estão abertas. Para obter mais informações, consulte Fechando um objeto de mapeamento de arquivo.

Não use a função CloseHandle para fechar um soquete. Em vez disso, use a função closesocket , que libera todos os recursos associados ao soquete, incluindo o identificador para o objeto socket. Para obter mais informações, consulte Fechamento de Soquete.

Não use a função CloseHandle para fechar um identificador para uma chave aberta do Registro. Em vez disso, use a função RegCloseKey . CloseHandle não fecha o identificador da chave do Registro, mas não retorna um erro para indicar essa falha.

Exemplos

dwPriorityClass = 0;
hProcess = OpenProcess( PROCESS_ALL_ACCESS, FALSE, pe32.th32ProcessID );
if( hProcess == NULL )
	printError( TEXT("OpenProcess") );
else
{
	dwPriorityClass = GetPriorityClass( hProcess );
	if( !dwPriorityClass )
	printError( TEXT("GetPriorityClass") );
	CloseHandle( hProcess );
}

Para ver este exemplo no contexto, consulte Como tirar um instantâneo e exibir processos.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	handleapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll