Fonction CloseHandle (handleapi.h)
Ferme un handle d’objet ouvert.
BOOL CloseHandle(
[in] HANDLE hObject
);
[in] hObject
Handle valide pour un objet ouvert.
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 .
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
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.
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.
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 |