Condividi tramite


Funzione CloseHandle (handleapi.h)

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

Vedere anche

CreateFile

CreateFileTransacted

DeleteFile

FindClose

Findfirstfile

Handle e Funzioni oggetto

Oggetti kernel

Interfaccia oggetto