Fonction NtGetNotificationResourceManager (wdm.h)

Article
03/01/2024

La routine ZwGetNotificationResourceManager récupère la notification de transaction suivante à partir de la file d’attente de notification d’un gestionnaire de ressources spécifié.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtGetNotificationResourceManager(
  [in]            HANDLE                    ResourceManagerHandle,
  [out]           PTRANSACTION_NOTIFICATION TransactionNotification,
  [in]            ULONG                     NotificationLength,
  [in]            PLARGE_INTEGER            Timeout,
  [out, optional] PULONG                    ReturnLength,
  [in]            ULONG                     Asynchronous,
  [in, optional]  ULONG_PTR                 AsynchronousContext
);

Paramètres

[in] ResourceManagerHandle

Handle d’un objet Resource Manager obtenu par un appel précédent à ZwCreateResourceManager ou ZwOpenResourceManager. Le handle doit avoir RESOURCEMANAGER_GET_NOTIFICATION accès à l’objet.

[out] TransactionNotification

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit des informations sur la notification récupérée. La mémoire tampon doit être suffisamment grande pour contenir une structure TRANSACTION_NOTIFICATION plus des arguments supplémentaires spécifiques à la notification.

[in] NotificationLength

Longueur, en octets, de la mémoire tampon vers laquelle pointe le paramètre TransactionNotification .

[in] Timeout

Pointeur vers une valeur qui spécifie une heure relative ou absolue, en unités de 100 nanosecondes. Ce pointeur est facultatif et peut avoir la valeur NULL.

Si le pointeur a la valeur NULL, ZwGetNotificationResourceManager ne retourne pas tant qu’une notification de transaction n’est pas disponible. Si une valeur d’heure est spécifiée, ZwGetNotificationResourceManager retourne quand une notification est disponible ou après l’expiration du temps spécifié, selon la première éventualité.

Une valeur négative spécifie une heure relative à l’heure système actuelle. Par exemple, une valeur de temps relative de cinq secondes fait en sorte que ZwGetNotificationResourceManager expire cinq secondes après son appel.

Une valeur positive spécifie une heure absolue, qui est en fait relative à 00 :00, le 1er janvier 1601. Si une valeur d’heure absolue est spécifiée, le système d’exploitation ajoute la valeur d’heure absolue à la valeur de temps qui représente 00 :00, le 1er janvier 1601.

Si l’appelant spécifie une valeur zéro (au lieu d’un pointeur NULL ), ZwGetNotificationResourceManager retourne immédiatement, qu’une notification soit disponible ou non.

[out, optional] ReturnLength

Pointeur facultatif vers une variable. Si ce pointeur n’a pas la valeur NULL et si la valeur du paramètre NotificationLength est trop petite, ZwGetNotificationResourceManager fournit la longueur requise dans la variable et retourne STATUS_BUFFER_TOO_SMALL.

[in] Asynchronous

Valeur ULONG qui doit être égale à zéro. ZwGetNotificationResourceManager ne prend pas en charge les notifications asynchrones. Utilisez TmEnableCallbacks pour activer les notifications asynchrones .

[in, optional] AsynchronousContext

Pointeur vers une valeur ULONG. Ce pointeur doit avoir la valeur NULL.

Valeur retournée

ZwGetNotificationResourceManager retourne STATUS_SUCCESS si l’opération réussit et qu’une notification est disponible. Sinon, cette routine peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_TIMEOUT	Intervalle de délai d’attente spécifié par Le délai d’expiration s’est écoulé avant qu’une notification soit disponible.
STATUS_OBJECT_TYPE_MISMATCH	Le handle spécifié n’est pas un handle pour un objet Resource Manager.
STATUS_INVALID_HANDLE	Le handle d’objet n’est pas valide.
STATUS_ACCESS_DENIED	L’appelant n’a pas l’accès approprié à l’objet Resource Manager.
STATUS_BUFFER_TOO_SMALL	La valeur du paramètre NotificationLength est trop petite.

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

Utilisez la routine ZwGetNotificationResourceManager pour obtenir des notifications de manière synchrone. Utilisez la routine TmEnableCallbacks pour activer les notifications asynchrones.

La structure TRANSACTION_NOTIFICATION reçue contient la clé d’inscription spécifiée par le gestionnaire de ressources lorsqu’elle a appelé ZwCreateEnlistment. Vous pouvez utiliser la clé d’inscription pour identifier l’inscription à laquelle la notification s’applique.

Pour plus d’informations sur la routine ZwGetNotificationResourceManager, consultez Création d’un Resource Manager.

NtGetNotificationResourceManager et ZwGetNotificationResourceManager sont deux versions de la même routine Windows Native System Services.

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	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, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	= PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs, PowerIrpDDis