Funzione CloseHandle (handleapi.h)

Articolo
08/24/2023

Chiude un handle di oggetti aperto.

Sintassi

BOOL CloseHandle(
  [in] HANDLE hObject
);

Parametri

[in] hObject

Handle valido per un oggetto aperto.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se l'applicazione è in esecuzione in un debugger, la funzione genererà un'eccezione se riceve un valore di handle non valido o un valore di pseudo-handle. Ciò può verificarsi se si chiude un handle due volte o se si chiama CloseHandle in un handle restituito dalla funzione FindFirstFile anziché chiamare la funzione FindClose .

Commenti

La funzione CloseHandle chiude gli handle agli oggetti seguenti:

Token di accesso
Dispositivo di comunicazione
Input della console
Buffer dello schermo della console
Evento
File
Mapping dei file
Porta di completamento di I/O
Processo
Mailslot
Notifica delle risorse di memoria
Mutex
Named pipe
Pipe
Processo
Semaphore
Thread
Transazione
Timer attendebile

La documentazione per le funzioni che creano questi oggetti indica che CloseHandle deve essere usato al termine dell'oggetto e ciò che accade alle operazioni in sospeso sull'oggetto dopo la chiusura dell'handle. In generale , CloseHandle invalida l'handle dell'oggetto specificato, decrementa il conteggio degli handle dell'oggetto ed esegue controlli di conservazione degli oggetti. Dopo la chiusura dell'ultimo handle a un oggetto, l'oggetto viene rimosso dal sistema. Per un riepilogo delle funzioni di creator per questi oggetti, vedere Oggetti kernel.

In genere, un'applicazione deve chiamare CloseHandle una volta per ogni handle aperto. In genere non è necessario chiamare CloseHandle se una funzione che usa un handle non riesce con ERROR_INVALID_HANDLE, perché questo errore indica in genere che l'handle è già invalidato. Tuttavia, alcune funzioni usano ERROR_INVALID_HANDLE per indicare che l'oggetto stesso non è più valido. Ad esempio, una funzione che tenta di usare un handle per un file in una rete potrebbe non riuscire con ERROR_INVALID_HANDLE se la connessione di rete è grave, perché l'oggetto file non è più disponibile. In questo caso, l'applicazione deve chiudere l'handle.

Se viene eseguito un handle, tutti gli handle associati a una transazione devono essere chiusi prima del commit della transazione. Se un handle transazionato è stato aperto chiamando CreateFileTransacted con il flag FILE_FLAG_DELETE_ON_CLOSE, il file non viene eliminato finché l'applicazione chiude l'handle e chiama CommitTransaction. Per altre informazioni sugli oggetti transazionati, vedere Uso delle transazioni.

La chiusura di un handle di thread non termina il thread associato o rimuove l'oggetto thread. La chiusura di un handle di processo non termina il processo associato o rimuove l'oggetto process. Per rimuovere un oggetto thread, è necessario terminare il thread, quindi chiudere tutti gli handle al thread. Per altre informazioni, vedere Terminazione di un thread. Per rimuovere un oggetto processo, è necessario terminare il processo, quindi chiudere tutti gli handle al processo. Per altre informazioni, vedere Terminazione di un processo.

La chiusura di un handle a un mapping di file può essere completata anche quando sono ancora aperte visualizzazioni file. Per altre informazioni, vedere Chiusura di un oggetto Mapping file.

Non usare la funzione CloseHandle per chiudere un socket. Usare invece la funzione closesocket , che rilascia tutte le risorse associate al socket, incluso l'handle all'oggetto socket. Per altre informazioni, vedere Chiusura socket.

Non usare la funzione CloseHandle per chiudere un handle a una chiave del Registro di sistema aperta. Usare invece la funzione RegCloseKey . CloseHandle non chiude l'handle alla chiave del Registro di sistema, ma non restituisce un errore per indicare questo errore.

Esempio

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 );
}

Per visualizzare questo esempio nel contesto, vedere Acquisizione di uno snapshot e processi di visualizzazione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	handleapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll