WMI_QUERY_REGINFO_CALLBACK fonction de rappel (wmilib.h)

Article
08/08/2023

La routine DpWmiQueryReginfo fournit des informations sur les blocs de données et les blocs d’événements à inscrire par un pilote. Cette routine est obligatoire.

Syntaxe

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

Paramètres

[in] DeviceObject

Pointeur vers la structure de DEVICE_OBJECT WDM du pilote.

[out] RegFlags

Ce paramètre indique les caractéristiques communes de tous les blocs inscrits. Tout indicateur défini dans RegFlags est appliqué à tous les blocs. Un pilote peut compléter RegFlags pour un bloc donné en définissant des indicateurs dans la structure WMIGUIDREGINFO du bloc. Par exemple, un pilote peut effacer WMIREG_FLAG_EXPENSIVE dans RegFlags, mais le définir dans Indicateurs pour inscrire un bloc donné comme coûteux à collecter.

Le pilote définit l’un des indicateurs suivants dans RegFlags :

WMIREG_FLAG_INSTANCE_BASENAME

Demande à WMI de générer des noms de instance statiques à partir d’un nom de base fourni par le pilote à l’emplacement InstanceName. WMI génère des noms instance en ajoutant un compteur au nom de base.

WMIREG_FLAG_INSTANCE_PDO

Demande à WMI de générer des noms de instance statiques à partir de l’ID de instance de l’appareil pour l’AOP. Si le pilote définit cet indicateur, il doit également définir Pdo sur l’AOP passée à la routine AddDevice du pilote. WMI génère des noms instance à partir du chemin d’instance de l’appareil de l’ADO. L’utilisation du chemin d’instance de l’appareil comme base pour les noms de instance statiques est efficace, car ces noms sont garantis comme uniques. WMI fournit automatiquement un nom « convivial » pour le instance en tant qu’élément d’un bloc de données pouvant être interrogé par les consommateurs de données.

Un pilote peut également définir un ou plusieurs des indicateurs suivants dans RegFlags, mais plus généralement dans Les indicateurs de la structure WMIGUIDREGINFO d’un bloc :

WMIREG_FLAG_EVENT_ONLY_GUID

Les blocs peuvent être activés ou désactivés en tant qu’événements uniquement, et ne peuvent pas être interrogés ou définis. Si cet indicateur est clair, les blocs peuvent également être interrogés ou définis.

WMIREG_FLAG_EXPENSIVE

Demande à WMI d’envoyer une demande de IRP_MN_ENABLE_COLLECTION la première fois qu’un consommateur de données ouvre un bloc de données et une demande de IRP_MN_DISABLE_COLLECTION lorsque le dernier consommateur de données ferme le bloc de données. Cela est recommandé si la collecte de ces données affecte les performances, car un pilote n’a pas besoin de collecter les données tant qu’un consommateur de données ne les demande pas explicitement en ouvrant le bloc.

WMIREG_FLAG_REMOVE_GUID

Demande à WMI de supprimer la prise en charge des blocs. Cet indicateur est valide uniquement en réponse à une demande de mise à jour des informations d’inscription (IRP_MN_REGINFO ou IRP_MN_REGINFO_EX avec Parameters.WMI.DataPath défini sur WMIUPDATE).

[out] InstanceName

Pointeur vers une chaîne Unicode comptée unique qui sert de nom de base pour toutes les instances de tous les blocs à inscrire par le pilote. WMI libère la chaîne avec ExFreePool. Si WMIREG_FLAG_INSTANCE_BASENAME est clair, InstanceName est ignoré.

[out] RegistryPath

Pointeur vers un pointeur vers une chaîne Unicode comptée qui spécifie le chemin du Registre passé à la routine DriverEntry du pilote.

[out] MofResourceName

Pointeur vers une chaîne Unicode comptée unique qui indique le nom de la ressource MOF attachée au fichier image binaire du pilote. En règle générale, cette chaîne est une chaîne statique définie par le pilote. WMI effectue une copie de cette chaîne après le retour du pilote à partir de cette routine. Cette chaîne peut être allouée dynamiquement par le pilote. Dans le cas d’une chaîne allouée, le pilote est chargé de libérer la chaîne qui doit être effectuée après le retour de WmiSystemControl . Si le pilote n’a pas de ressource MOF attachée, il peut laisser MofResourceName inchangé.

[out] Pdo

Pointeur vers l’objet de périphérique physique (PDO) passé à la routine AddDevice du pilote. Si WMIREG_FLAG_INSTANCE_PDO est défini, WMI utilise le chemin d’instance d’appareil de ce PDO comme base à partir de laquelle générer des noms de instance statiques. Si WMIREG_FLAG_INSTANCE_PDO est clair, WMI ignore Pdo.

Valeur retournée

DpWmiQueryReginfo retourne toujours STATUS_SUCCESS.

Remarques

WMI appelle la routine DpWmiQueryReginfo d’un pilote après que le pilote a appelé WmiSystemControl en réponse à une demande IRP_MN_REGINFO ou IRP_MN_REGINFO_EX . Le pilote doit placer l’adresse de sa routine DpWmiQueryReginfo dans la structure WMILIB_CONTEXT qu’il transmet à WmiSystemControl.

WMI envoie l’IRP après qu’un pilote a appelé IoWMIRegistrationControl avec WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER ou WMIREG_ACTION_UPDATE. WMI gère en toute transparence les différences entre IRP_MN_REGINFO et IRP_MN_REGINFO_EX pour le compte du pilote.

WMI n’envoie pas de demande de IRP_MN_REGINFO ou de IRP_MN_REGINFO_EX après qu’un pilote a appelé IoWMIRegistrationControl avec WMIREG_ACTION_DEREGISTER, car WMI ne nécessite aucune autre information du pilote. Un pilote annule généralement l’inscription de ses blocs en réponse à une demande de IRP_MN_REMOVE_DEVICE .

Le pilote fournit des informations d’inscription nouvelles ou mises à jour sur des blocs individuels, ou indique des blocs à supprimer, dans la structure WMILIB_CONTEXT qu’il transmet à WmiSystemControl. Après l’appel initial, qui établit le chemin d’accès du registre du pilote et le nom de la ressource MOF, la routine DpWmiQueryReginfo d’un pilote peut modifier les indicateurs communs à tous les blocs d’un pilote, fournir une chaîne de nom de base différente utilisée pour générer des noms de instance, ou modifier la base des noms de instance d’une chaîne à l’appareil instance chemin de l’AOP.

Le pilote ne doit pas retourner STATUS_PENDING ou bloquer la requête. Le pilote ne doit pas terminer la demande en appelant WmiCompleteRequest à partir de sa routine DpWmiQueryReginfo ou en appelant IoCompleteRequest après le retour de WmiSystemControl .

Cette routine peut être paginable.

Pour plus d’informations sur l’implémentation de cette routine, consultez Calling WmiSystemControl to Handle WMI IRPs.