ObCloseHandle, fonction (wdm.h)

Article
02/27/2024

La routine ObCloseHandle ferme un handle d’objet.

Syntaxe

NTSTATUS ObCloseHandle(
  [in] HANDLE          Handle,
  [in] KPROCESSOR_MODE PreviousMode
);

Paramètres

[in] Handle

Handle d’un objet fourni par le système de tout type.

[in] PreviousMode

Spécifie le mode processeur précédent du thread qui a ouvert le handle. Pour fermer un handle de noyau, définissez ce paramètre sur KernelMode. Pour fermer un handle utilisateur, définissez ce paramètre sur UserMode. Pour plus d’informations sur ces deux types de handle, consultez Remarques.

Valeur retournée

ObCloseHandle retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes NTSTATUS suivants.

Code de retour	Description
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.

Remarques

Un pilote en mode noyau appelle ObCloseHandle pour fermer un handle à tout type d’objet créé par le noyau Windows. Un pilote doit fermer chaque poignée qu’il ouvre dès que la poignée n’est plus nécessaire.

Une fois ObCloseHandle fermé le handle d’un objet, l’appelant doit traiter le handle comme non valide et éviter d’utiliser le handle pour accéder à l’objet. Toutefois, d’autres handles peuvent rester ouverts sur le même objet. Lors d’un appel ObCloseHandle , le système décrémente le nombre de handles pour l’objet et vérifie si l’objet peut être supprimé. Le système ne supprime pas l’objet tant que tous les handles de l’objet n’ont pas été fermés et que tous les pointeurs comptabilisés en référence vers l’objet n’ont pas été libérés.

Le paramètre PreviousMode spécifie si le handle à fermer est un handle de noyau ou un handle utilisateur. Pour fermer un handle de noyau, définissez PreviousMode sur KernelMode. Pour fermer un handle utilisateur, définissez PreviousMode sur UserMode.

Un handle de noyau est un handle ouvert par un thread système ou par un pilote en mode noyau qui affecte l’attribut OBJ_KERNEL_HANDLE au handle. (Par exemple, consultez la description de OBJ_KERNEL_HANDLE dans ZwCreateFile.) Si un pilote en mode noyau ouvre un handle pour son utilisation privée et que ce pilote s’exécute dans le contexte d’un thread en mode utilisateur, le pilote doit ouvrir le handle avec l’attribut OBJ_KERNEL_HANDLE. Cet attribut garantit que le handle est inaccessible aux applications en mode utilisateur.

Un handle utilisateur est un handle ouvert par une application en mode utilisateur ou par un pilote en mode noyau qui s’exécute dans le contexte d’un thread en mode utilisateur, mais qui n’ouvre pas le handle avec l’attribut OBJ_KERNEL_HANDLE. Si un pilote crée un handle utilisateur à utiliser par une application en mode utilisateur, mais qu’une erreur se produit qui oblige le pilote à fermer le handle au nom de l’application, le pilote peut appeler ObCloseHandle pour fermer le handle.

La routine ZwClose est similaire à ObCloseHandle , mais ne peut fermer que les handles du noyau. L’appel ZwClose(hObject), qui ferme le handle du noyau hObject, a le même effet que l’appel ObCloseHandle(hObject, KernelMode). Pour plus d’informations sur la fermeture d’un handle de noyau, consultez ZwClose.

Pour déterminer si un handle est un handle de noyau ou un handle utilisateur, un pilote qui reçoit un handle peut appeler la routine ExGetPreviousMode . Le pilote peut également lire le champ RequestorMode à partir de la structure IRP qui décrit la demande d’E/S. Le gestionnaire d’E/S définit le champ RequestorMode sur le mode processeur précédent du thread qui demandait l’opération d’E/S.

Les appelants d’ObCloseHandle ne doivent pas supposer que cette routine attend automatiquement que toutes les opérations d’E/S en attente se terminent avant de retourner.

Pour plus d’informations, consultez Handles d’objet.

ObCloseHandle n’est pas déclaré dans un fichier d’en-tête avant Windows 7. Pour utiliser cette routine dans votre pilote, incluez la déclaration de fonction suivante dans votre code de pilote :

#if (NTDDI_VERSION < NTDDI_WIN7)
NTKERNELAPI
NTSTATUS
  ObCloseHandle(
    __in HANDLE Handle,
    __in KPROCESSOR_MODE PreviousMode
    );
#endif

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h
Bibliothèque	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL

Voir aussi