Função CloseHandle (handleapi.h)

Artigo
02/26/2024

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 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 os identificadores 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
Processar
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, diminui a contagem de identificadores do objeto e executa verificações de retenção de objeto. Depois que o último identificador para um objeto é fechado, o objeto é removido do sistema. Para obter um resumo das funções do criador para esses objetos, consulte Objetos kernel.

Geralmente, um aplicativo deve chamar CloseHandle uma vez para cada identificador aberto. Geralmente, 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 próprio objeto 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, pois 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 tiver sido 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 Trabalhando com transações.

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, em seguida, fechar todos os identificadores do thread. Para obter mais informações, consulte Terminando um thread. Para remover um objeto de processo, você deve encerrar o processo e, em seguida, fechar todos os identificadores do processo. Para obter mais informações, consulte Encerrando 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 do Registro aberta. Em vez disso, use a função RegCloseKey . CloseHandle não fecha o identificador para a 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 Tomando um instantâneo e exibindo processos.

Requisitos

Requisito	Valor
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