Fonction TmReferenceEnlistmentKey (wdm.h)

Article
02/27/2024

La routine TmReferenceEnlistmentKey incrémente le nombre de références pour la clé d’un objet d’inscription spécifié et récupère la clé.

Syntaxe

NTSTATUS TmReferenceEnlistmentKey(
  [in]  PKENLISTMENT Enlistment,
  [out] PVOID        *Key
);

Paramètres

[in] Enlistment

Pointeur vers un objet d’inscription. Votre composant peut recevoir ce pointeur en tant qu’entrée dans une routine de rappel ResourceManagerNotification . Votre composant peut également appeler ObReferenceObjectByHandle et fournir le handle d’objet fourni par un appel précédent à ZwCreateEnlistment, TmCreateEnlistment ou ZwOpenEnlistment .

[out] Key

Pointeur vers une variable qui reçoit la clé d’inscription de l’objet d’inscription. L’appelant affecte une clé d’inscription lorsqu’il appelle ZwCreateEnlistment ou TmCreateEnlistment.

Valeur retournée

TmReferenceEnlistmentKey retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette routine peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	La valeur du paramètre Key est NULL.
STATUS_UNSUCCESSFUL	Le nombre de références de l’objet d’inscription spécifié étant décrémenté à zéro, le nombre de références ne peut pas être incrémenté.
STATUS_INSUFFICIENT_RESOURCES	Le nombre de références est à sa valeur maximale (0xFFFFFFFF) et ne peut pas être incrémenté.

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

La routine TmReferenceEnlistmentKey incrémente le nombre de références pour la valeur de clé d’un objet d’inscription, et la routine TmDereferenceEnlistmentKey décrémente le nombre.

Si un gestionnaire de ressources a défini une valeur de clé pour une inscription, le gestionnaire de ressources reçoit la valeur de clé lorsqu’il appelle ZwGetNotificationResourceManager ou quand KTM appelle la routine de rappel ResourceManagerNotification .

Pendant qu’un gestionnaire de ressources traite une notification, il peut utiliser la clé comme pointeur vers une allocation de mémoire temporaire, et il peut utiliser le nombre de références pour déterminer quand il doit libérer la mémoire.

Pour plus d’informations sur l’utilisation des routines TmXxx de KTM au lieu des routines ZwXxx , consultez Utilisation des routines TmXxx.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions ultérieures du système d’exploitation.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL