Fonction NtClose (ntifs.h)

Article
02/26/2024

La routine NtClose ferme un handle d’objet.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtClose(
  [in] HANDLE Handle
);

Paramètres

[in] Handle

Gérez un objet de n’importe quel type.

Valeur retournée

NtClose retourne STATUS_SUCCESS en cas de réussite, ou le code d’erreur NTSTATUS approprié, comme le suivant.

Code de retour	Signification
STATUS_INVALID_HANDLE	Handle n’est pas un handle valide.
STATUS_HANDLE_NOT_CLOSABLE	Le thread appelant n’a pas l’autorisation de fermer le handle ; autrement dit, le handle d’objet spécifié est protégé contre la fermeture de toute tentative de instance de NtClose.

Un exemple où le dernier code NTSTATUS se produit est lorsqu’un appel de ZwDuplicateObject a été appelé avec OBJ_PROTECT_CLOSE passé à l’argument de paramètre handle attributes. Le noyau garantit que le handle ne peut pas être fermé dans ce cas.

Remarques

NtClose est une routine générique qui fonctionne sur n’importe quel type d’objet.

La fermeture d’un handle d’objet ouvert rend ce handle non valide. Le système décrémente également le nombre de handles pour l’objet et vérifie si l’objet peut être supprimé. Le système ne supprime pas réellement l’objet tant que tous les handles de l’objet ne sont pas fermés et qu’aucun pointeur référencé ne reste.

Un pilote doit fermer chaque poignée qu’il ouvre dès que la poignée n’est plus nécessaire. Les handles de noyau, qui sont ouverts par un thread système ou en spécifiant l’indicateur OBJ_KERNEL_HANDLE, ne peuvent être fermés que lorsque le mode processeur précédent est KernelMode. Cette exigence s’applique à la fois aux threads système et aux routines de distribution pour les IRP qui ont été émis à partir du mode noyau. (Pour plus d’informations sur le mode processeur précédent, consultez ExGetPreviousMode.) Par exemple, un handle que NtCreateKey retourne à une routine DriverEntry ne peut pas être fermé par la suite par les mêmes routines de répartition du pilote. Une routine DriverEntry s’exécute dans un processus système, tandis que les routines de répartition s’exécutent généralement soit dans le contexte du thread qui émet la demande d’E/S actuelle, soit, pour les pilotes de niveau inférieur, dans un contexte de thread arbitraire.

Un handle sans noyau ne peut être fermé que si l’une des deux conditions est remplie : le mode processeur précédent est KernelMode ou si le thread appelant a suffisamment d’autorisations pour fermer le handle. Un exemple de ce dernier se produit lorsque le thread appelant est celui qui a créé le handle.

Les appelants de NtClose ne doivent pas supposer que cette routine attend automatiquement que toutes les E/S se terminent avant de retourner.

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtClose » au lieu de « ZwClose ».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000
Plateforme cible	Universal
En-tête	ntifs.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs, IrqlZwPassive, PowerIrpDDis, ZwRegistryCreate, ZwRegistryCreate(storport), ZwRegistryOpen, ZwRegistryOpen(storport)

Voir aussi

ZwCreateDirectoryObject