WMI_QUERY_REGINFO_CALLBACK fonction de rappel (wmilib.h)
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 requise.
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 wdM du pilote DEVICE_OBJECT.
[out] RegFlags
Ce paramètre indique les caractéristiques courantes 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 indicateurs dans la structure WMIGUIDREGINFO du bloc. Par exemple, un pilote peut effacer WMIREG_FLAG_EXPENSIVE dans RegFlags, mais le définir dans Flags 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 d’instances statiques à partir d’un nom de base fourni par le pilote à l'instanceName. WMI génère des noms d’instance en ajoutant un compteur au nom de base.
WMIREG_FLAG_INSTANCE_PDO
Demande à WMI de générer des noms d’instances statiques à partir de l’ID d’instance de l’appareil pour l’application PDO. Si le pilote définit cet indicateur, il doit également définir Pdo sur l’objet PDO passé à la routine AddDevice du pilote. WMI génère des noms d’instance à partir du chemin d’accès de l’instance d’appareil de l’application PDO. L’utilisation du chemin d’accès de l’instance d’appareil comme base pour les noms d’instances statiques est efficace, car ces noms sont garantis comme uniques. WMI fournit automatiquement un nom « convivial » pour l’instance en tant qu’élément d’un bloc de données qui peut être interrogé par les consommateurs de données.
Un pilote peut également définir un ou plusieurs des indicateurs suivants dans RegFlags, mais il les définirait généralement dans 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 le 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, nom_instance 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 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 WmiSystemControl retourne. Si le pilote n’a pas de ressource MOF attachée, il peut laisser MofResourceName inchangé.
[out] Pdo
Pointeur vers l’objet d’appareil physique (PDO) passé à la routine AddDevice du pilote. Si WMIREG_FLAG_INSTANCE_PDO est défini, WMI utilise le chemin d’accès de l’instance d’appareil de ce PDO comme base à partir de laquelle générer des noms d’instances statiques. Si WMIREG_FLAG_INSTANCE_PDO est clair, WMI ignore Pdo .
Valeur de retour
DpWmiQueryReginfo retourne toujours STATUS_SUCCESS.
Remarques
WMI appelle la routine DpWmiQueryReginfo d’un pilote une fois que le pilote appelle WmiSystemControl en réponse à une demande de IRP_MN_REGINFO ou de IRP_MN_REGINFO_EX. Le pilote doit placer l’adresse de son DpWmiQueryReginfo routine dans la structure WMILIB_CONTEXT qu’il passe à WmiSystemControl.
WMI envoie l’IRP après qu’un pilote appelle 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 au nom du pilote.
WMI n’envoie pas de demande de IRP_MN_REGINFO ou de IRP_MN_REGINFO_EX après qu’un pilote appelle IoWMIRegistrationControl avec WMIREG_ACTION_DEREGISTER, car WMI ne nécessite aucune information supplémentaire du pilote. Un pilote désinscrit généralement 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 passe à WmiSystemControl. Après l’appel initial, qui établit le chemin d’accès au Registre du pilote et le nom de la ressource MOF, les dpWmiQueryReginfo routine peuvent modifier les indicateurs communs à tous les blocs d’un pilote, fournir une autre chaîne de nom de base utilisée pour générer des noms d’instance, ou modifier la base des noms d’instance d’une chaîne vers le chemin d’accès de l’instance d’appareil du PDO.
Le pilote ne doit pas retourner STATUS_PENDING ou bloquer la requête. Le pilote ne doit pas terminer la requête en appelant WmiCompleteRequest à partir de sa routine DpWmiQueryReginfo ou en appelant ioCompleteRequest après retour de WmiSystemControl.
Cette routine peut être paginable.
Pour plus d’informations sur l’implémentation de cette routine, consultez Appel de WmiSystemControl pour gérer les runtimes d’intégration WMI.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Bureau |
| d’en-tête | wmilib.h (include Wmilib.h) |
| IRQL | Appelé à PASSIVE_LEVEL. |