Fonction CloseHandle (handleapi.h)

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 .

Notes

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
  • Process
  • 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

   
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

Voir aussi

CreateFile

CreateFileTransacted

DeleteFile

FindClose

FindFirstFile

Fonctions de handle et d’objet

Objets du noyau

Interface d’objet