WdfWmiInstanceCreate, fonction (wdfwmi.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfWmiInstanceCreate crée un objet WMI instance qui représente un instance d’un fournisseur de données WMI.

Syntaxe

NTSTATUS WdfWmiInstanceCreate(
  [in]            WDFDEVICE                Device,
  [in]            PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES   InstanceAttributes,
  [out, optional] WDFWMIINSTANCE           *Instance
);

Paramètres

[in] Device

Handle d’un objet d’appareil framework qui représente l’appareil pour lequel le instance est créé. L’objet device ne peut pas être un objet de périphérique de contrôle.

[in] InstanceConfig

Pointeur vers une structure de WDF_WMI_INSTANCE_CONFIG initialisée par l’appelant, qui contient des informations de configuration pour un instance d’un fournisseur de données WMI.

[in, optional] InstanceAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée à l’appelant qui contient les attributs d’objet fournis par le pilote pour le nouvel objet WMI instance. (Le membre ParentObject de la structure doit être NULL.) Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Instance

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet instance WMI. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

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

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_WMI_INSTANCE_CONFIG vers laquelle pointe le paramètre InstanceConfig était incorrecte.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante.
STATUS_INTEGER_OVERFLOW	Le pilote a défini le membre UseContextForQuery de la structure WDF_WMI_INSTANCE_CONFIG sur TRUE, mais a spécifié une taille d’espace de contexte supérieure à ULONG_MAX dans la structure WDF_OBJECT_ATTRIBUTES du paramètre InstanceAttributes.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfWmiInstanceCreate peut retourner, consultez Erreurs de création d’objets framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Si un pilote crée plusieurs instances d’un fournisseur, il doit appeler WdfWmiProviderCreate pour créer un objet fournisseur avant d’appeler WdfWmiInstanceCreate. Le pilote transmet le handle de l’objet fournisseur à WdfWmiInstanceCreate en le plaçant dans une structure WDF_WMI_INSTANCE_CONFIG . (Si le pilote fournit un handle d’objet fournisseur, le paramètre Device n’est pas utilisé et peut être NULL.)

Si le pilote crée une seule instance d’un fournisseur, il n’a pas besoin d’appeler WdfWmiInstanceCreate avant d’appeler WdfWmiInstanceCreate. Dans ce cas, WdfWmiInstanceCreate crée également un objet de fournisseur WMI. Par conséquent, la structure de WDF_WMI_INSTANCE_CONFIG du pilote doit inclure un pointeur vers une structure de WDF_WMI_PROVIDER_CONFIG qui décrit le fournisseur de données WMI.

L’infrastructure indique à WMI de créer un nom de instance dynamique, que les applications peuvent utiliser, à partir de l’ID de instance d’appareil de l’objet de périphérique physique (PDO) du pilote. (L’infrastructure ne prend pas en charge les noms de instance statiques définis par les pilotes WDM (Windows Driver Model) dans une structure IRP_MN_REGINFO ou IRP_MN_REGINFO_EX.)

Le parent de l’objet instance WMI est l’objet fournisseur WMI. Le pilote ne peut pas modifier ce parent, et le membre ParentObject ou la structure WDF_OBJECT_ATTRIBUTES doit avoir la valeur NULL.

Une fois que le pilote a appelé WdfWmiInstanceCreate, il peut appeler WdfWmiInstanceGetProvider pour obtenir un handle pour l’objet de fournisseur parent et WdfWmiInstanceGetDevice pour obtenir un handle sur l’appareil du fournisseur.

Pour plus d’informations sur la méthode WdfWmiInstanceCreate , consultez Prise en charge de WMI dans les pilotes Framework-Based.

Si le membre Register de la structure WDF_WMI_INSTANCE_CONFIG vers laquelle InstanceConfig pointe a la valeur TRUE, WdfWmiInstanceCreate inscrit le fournisseur instance de manière synchrone (c’est-à-dire, avant de retourner) si cette méthode est appelée à IRQL = PASSIVE_LEVEL et de manière asynchrone si elle est appelée au PASSIVE_LEVEL IRQL>.

Exemples

L’exemple de code suivant provient de l’exemple de pilote PCIDRV . Cet exemple enregistre un nom de ressource MOF pour un appareil, initialise une structure WDF_WMI_PROVIDER_CONFIG et une structure WDF_WMI_INSTANCE_CONFIG, puis appelle WdfWmiInstanceCreate.

NTSTATUS
PciDrvWmiRegistration(
    WDFDEVICE  Device
    )
{
    WDF_WMI_PROVIDER_CONFIG  providerConfig;
    WDF_WMI_INSTANCE_CONFIG  instanceConfig;
    NTSTATUS  status;
    DECLARE_CONST_UNICODE_STRING(mofRsrcName, MOFRESOURCENAME);

    status = WdfDeviceAssignMofResourceName(
                                            Device,
                                            &mofRsrcName
                                            );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    WDF_WMI_PROVIDER_CONFIG_INIT(
                                 &providerConfig,
                                 &PCIDRV_WMI_STD_DATA_GUID
                                 );
    providerConfig.MinInstanceBufferSize = sizeof(PCIDRV_WMI_STD_DATA);

    WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG(
                                                 &instanceConfig,
                                                 &providerConfig
                                                 );
    instanceConfig.Register = TRUE;
    instanceConfig.EvtWmiInstanceQueryInstance = EvtWmiDeviceInfoQueryInstance;
    instanceConfig.EvtWmiInstanceSetInstance = EvtWmiDeviceInfoSetInstance;

    status = WdfWmiInstanceCreate(
                                  Device,
                                  &instanceConfig,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  WDF_NO_HANDLE
                                  );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfwmi.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)