WdfWmiInstanceCreate, fonction (wdfwmi.h)
[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 |
|---|---|
|
Un paramètre non valide a été détecté. |
|
La taille de la structure WDF_WMI_INSTANCE_CONFIG vers laquelle pointe le paramètre InstanceConfig était incorrecte. |
|
La mémoire était insuffisante. |
|
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) |
Voir aussi
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG