WmiSystemControl, fonction (wmilib.h)

Article
08/08/2023

La routine WmiSystemControl est une routine de répartition pour les pilotes qui utilisent des routines de prise en charge de bibliothèque WMI pour gérer les IRP WMI.

Syntaxe

NTSTATUS WmiSystemControl(
  [in]      PWMILIB_CONTEXT         WmiLibInfo,
  [in]      PDEVICE_OBJECT          DeviceObject,
  [in, out] PIRP                    Irp,
  [out]     PSYSCTL_IRP_DISPOSITION IrpDisposition
);

Paramètres

[in] WmiLibInfo

Pointeur vers une structure de WMILIB_CONTEXT qui contient des informations d’inscription pour les blocs de données et les blocs d’événements d’un pilote, et définit des points d’entrée pour les routines de rappel de la bibliothèque WMI du pilote.

[in] DeviceObject

Pointeur vers le DEVICE_OBJECT du pilote.

[in, out] Irp

Pointeur vers l’IRP.

[out] IrpDisposition

Pointeur vers une valeur d’énumération de type SYSCTL_IRP_DISPOSITION qui indique comment l’IRP a été géré. WmiSystemControl définit toujours cette valeur, même lorsqu’il retourne un code NTSTATUS non réussi.

SYSCTL_IRP_DISPOSITION est une énumération dans Wmilib.h et contient les valeurs suivantes :

IrpProcessed

L’IRP a été traité et peut-être terminé. Si la routine DpWmiXxx du pilote appelée par WmiSystemControl n’a pas terminé l’IRP, le pilote doit appeler WmiCompleteRequest pour terminer l’IRP après le retour de WmiSystemControl .

IrpNotCompleted

L’IRP a été traité, mais pas terminé, soit parce que WMI a détecté une erreur et configuré l’IRP avec un code d’erreur approprié, soit traité une demande IRP_MN_REGINFO ou IRP_MN_REGINFO_EX . Le pilote doit terminer l’IRP en appelant IoCompleteRequest.

IrpNotWmi

L’IRP n’est pas une requête WMI (autrement dit, WMI ne reconnaît pas le code secondaire de l’IRP). Si le pilote gère IRP_MJ_SYSTEM_CONTROL requêtes avec cette IRP_MN_XXX, il doit gérer l’IRP ; dans le cas contraire, le pilote doit transférer l’IRP au pilote inférieur suivant. Si le pilote est le pilote de niveau le plus bas, il doit effectuer l’IRP.

IrpForward

L’IRP est ciblé sur un autre objet d’appareil (autrement dit, le pointeur d’objet de périphérique sur Parameters.WMI.ProviderId dans l’IRP ne correspond pas au pointeur passé par le pilote dans son appel à IoWMIRegistrationControl). Le pilote doit transférer l’IRP au pilote inférieur suivant. Si le pilote est le pilote de niveau le plus bas, il doit effectuer l’IRP.

Valeur retournée

WmiSystemControl retourne STATUS_SUCCESS ou l’un des codes d’erreur suivants :

Remarques

Lorsqu’un pilote reçoit une requête IRP_MJ_SYSTEM_CONTROL avec un code mineur IRP WMI, il appelle WmiSystemControl avec un pointeur vers la structure WMILIB_CONTEXT du pilote, un pointeur vers son objet de périphérique et un pointeur vers l’IRP. La structure WMILIB_CONTEXT contient des informations d’inscription pour les blocs de données et les blocs d’événements du pilote, et définit des points d’entrée pour ses routines de rappel de bibliothèque WMI.

WmiSystemControl confirme que l’IRP est une requête WMI et détermine si le bloc spécifié par la requête est valide pour le pilote. Si c’est le cas, il traite l’IRP en appelant le point d’entrée DpWmiXxx approprié dans la structure de WMILIB_CONTEXT du pilote. WMI s’exécute sur IRQL PASSIVE_LEVEL lorsqu’il appelle la routine DpWmiXxx du pilote.

Un pilote doit s’exécuter au PASSIVE_LEVEL IRQL lorsqu’il transfère une demande de IRP_MJ_SYSTEM_CONTROL au pilote inférieur suivant.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows 2000 et versions ultérieures de Windows.
Plateforme cible	Universal
En-tête	wmilib.h (inclure Wmilib.h)
Bibliothèque	Wmilib.lib
IRQL	PASSIVE_LEVEL (voir la section Remarques)
Règles de conformité DDI	WmiComplete(wdm)