Fonction CloseHandle (handleapi.h)

Article
02/29/2024

Ferme un handle d’objet ouvert.

Syntaxe

BOOL CloseHandle(
  [in] HANDLE hObject
);

Paramètres

[in] hObject

Handle valide pour un objet ouvert.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Si l’application s’exécute sous un débogueur, la fonction lève une exception si elle reçoit une valeur de handle qui n’est pas valide ou une valeur pseudo-handle. Cela peut se produire si vous fermez un handle deux fois, ou si vous appelez CloseHandle sur un handle retourné par la fonction FindFirstFile au lieu d’appeler la fonction FindClose .

Remarques

La fonction CloseHandle ferme les handles aux objets suivants :

Access token (Jeton d’accès)
Appareil de communication
Entrée console
Mémoire tampon d’écran de console
Événement
Fichier
Mappage de fichiers
Port d’achèvement des E/S
Travail
Maillot
Notification des ressources de mémoire
Mutex
Canal nommé
Pipe
Processus
Semaphore
Thread
Transaction
Minuteur pouvant être attendu

La documentation relative aux fonctions qui créent ces objets indique que CloseHandle doit être utilisé lorsque vous avez terminé avec l’objet, et que se passe-t-il des opérations en attente sur l’objet après la fermeture du handle. En général, CloseHandle invalide le handle d’objet spécifié, décrémente le nombre de handles de l’objet et effectue des vérifications de rétention des objets. Une fois le dernier handle d’un objet fermé, l’objet est supprimé du système. Pour obtenir un résumé des fonctions créatrices pour ces objets, consultez Objets du noyau.

En règle générale, une application doit appeler CloseHandle une fois pour chaque handle qu’elle s’ouvre. Il n’est généralement pas nécessaire d’appeler CloseHandle si une fonction qui utilise un handle échoue avec ERROR_INVALID_HANDLE, car cette erreur indique généralement que le handle est déjà invalidé. Toutefois, certaines fonctions utilisent ERROR_INVALID_HANDLE pour indiquer que l’objet lui-même n’est plus valide. Par exemple, une fonction qui tente d’utiliser un handle dans un fichier sur un réseau peut échouer avec ERROR_INVALID_HANDLE si la connexion réseau est interrompue, car l’objet file n’est plus disponible. Dans ce cas, l’application doit fermer le handle.

Si un handle est traité, tous les handles liés à une transaction doivent être fermés avant la validation de la transaction. Si un handle traité a été ouvert en appelant CreateFileTransacted avec l’indicateur FILE_FLAG_DELETE_ON_CLOSE, le fichier n’est pas supprimé tant que l’application n’a pas fermé le handle et appelé CommitTransaction. Pour plus d’informations sur les objets traités, consultez Utilisation des transactions.

La fermeture d’un handle de thread n’arrête pas le thread associé ni ne supprime l’objet thread. La fermeture d’un handle de processus n’arrête pas le processus associé ni ne supprime l’objet de processus. Pour supprimer un objet thread, vous devez arrêter le thread, puis fermer toutes les poignées au thread. Pour plus d’informations, consultez Fin d’un thread. Pour supprimer un objet de processus, vous devez arrêter le processus, puis fermer tous les handles du processus. Pour plus d’informations, consultez Fin d’un processus.

La fermeture d’un handle à un mappage de fichiers peut réussir même si des vues de fichiers sont toujours ouvertes. Pour plus d’informations, consultez Fermeture d’un objet de mappage de fichiers.

N’utilisez pas la fonction CloseHandle pour fermer un socket. Utilisez plutôt la fonction closesocket , qui libère toutes les ressources associées au socket, y compris le handle de l’objet socket. Pour plus d’informations, consultez Fermeture de socket.

N’utilisez pas la fonction CloseHandle pour fermer un handle à une clé de Registre ouverte. Utilisez plutôt la fonction RegCloseKey . CloseHandle ne ferme pas le handle à la clé de Registre, mais ne retourne pas d’erreur pour indiquer cet échec.

Exemples

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

Pour voir cet exemple en contexte, consultez Prise d’un instantané et affichage des processus.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	handleapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll