WdfWmiInstanceCreate-Funktion (wdfwmi.h)
[Gilt nur für KMDF]
Die WdfWmiInstanceCreate-Methode erstellt ein WMI-instance-Objekt, das eine instance eines WMI-Datenanbieters darstellt.
Syntax
NTSTATUS WdfWmiInstanceCreate(
[in] WDFDEVICE Device,
[in] PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES InstanceAttributes,
[out, optional] WDFWMIINSTANCE *Instance
);
Parameter
[in] Device
Ein Handle für ein Frameworkgeräteobjekt, das das Gerät darstellt, für das die instance erstellt wird. Das Geräteobjekt kann kein Steuerelementgerätobjekt sein.
[in] InstanceConfig
Ein Zeiger auf eine vom Aufrufer initialisierte WDF_WMI_INSTANCE_CONFIG-Struktur, die Konfigurationsinformationen für eine instance eines WMI-Datenanbieters enthält.
[in, optional] InstanceAttributes
Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES-Struktur, die vom Treiber bereitgestellte Objektattribute für das neue WMI-instance-Objekt enthält. (Das ParentObject-Element der Struktur muss NULL sein.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.
[out, optional] Instance
Ein Zeiger auf eine Position, die ein Handle für das neue WMI-instance-Objekt empfängt. Dieser Parameter ist optional und kann NULL sein.
Rückgabewert
WdfWmiInstanceCreate gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Die Größe der WDF_WMI_INSTANCE_CONFIG Struktur, auf die der InstanceConfig-Parameter verweist, war falsch. |
|
Es war nicht genügend Arbeitsspeicher vorhanden. |
|
Der Treiber legt den UseContextForQuery-Member der WDF_WMI_INSTANCE_CONFIG-Struktur auf TRUE fest, gibt jedoch eine Kontextraumgröße an, die in der WDF_OBJECT_ATTRIBUTES-Struktur des InstanceAttributes-Parameters größer als ULONG_MAX ist. |
Eine Liste mit anderen Rückgabewerten, die von der WdfWmiInstanceCreate-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.
Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Wenn ein Treiber mehrere Instanzen eines Anbieters erstellt, muss der Treiber WdfWmiProviderCreate aufrufen, um ein Anbieterobjekt zu erstellen, bevor WdfWmiInstanceCreate aufgerufen wird. Der Treiber übergibt das Handle des Anbieterobjekts an WdfWmiInstanceCreate , indem er das Handle in einer WDF_WMI_INSTANCE_CONFIG-Struktur platziert. (Wenn der Treiber ein Anbieterobjekthandle bereitstellt, wird der Device-Parameter nicht verwendet und kann NULL sein.)
Wenn der Treiber eine einzelne instance eines Anbieters erstellt, muss er vor dem Aufrufen von WdfWmiInstanceCreate nicht WdfWmiInstanceCreate aufrufen. In diesem Fall erstellt WdfWmiInstanceCreate auch ein WMI-Anbieterobjekt. Daher muss die WDF_WMI_INSTANCE_CONFIG-Struktur des Treibers einen Zeiger auf eine WDF_WMI_PROVIDER_CONFIG-Struktur enthalten, die den WMI-Datenanbieter beschreibt.
Das Framework weist WMI an, einen dynamischen instance Namen zu erstellen, den Anwendungen verwenden können, aus dem Gerät instance ID des Physischen Geräteobjekts (PDO) des Treibers. (Das Framework unterstützt keine statischen instance Namen, die WDM-Treiber (Windows Driver Model) in einer IRP_MN_REGINFO- oder IRP_MN_REGINFO_EX-Struktur festlegen.)
Das übergeordnete WMI-instance-Objekt ist das WMI-Anbieterobjekt. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject-Element oder die WDF_OBJECT_ATTRIBUTES-Struktur muss NULL sein.
Nachdem der Treiber WdfWmiInstanceCreate aufgerufen hat, kann er WdfWmiInstanceGetProvider aufrufen, um ein Handle für das übergeordnete Anbieterobjekt zu erhalten, und WdfWmiInstanceGetDevice , um ein Handle für das Gerät des Anbieters abzurufen.
Weitere Informationen zur WdfWmiInstanceCreate-Methode finden Sie unter Unterstützen von WMI in Framework-Based Drivers.
Wenn der Register-Member der WDF_WMI_INSTANCE_CONFIG-Struktur, auf die InstanceConfig verweist, TRUE ist, registriert WdfWmiInstanceCreate den Anbieter instance synchron (d. h. vor der Rückgabe), wenn diese Methode unter IRQL = PASSIVE_LEVEL aufgerufen wird, und asynchron, wenn sie am IRQL-PASSIVE_LEVEL > aufgerufen wird.
Beispiele
Das folgende Codebeispiel stammt aus dem PCIDRV-Beispieltreiber . In diesem Beispiel wird ein MOF-Ressourcenname für ein Gerät registriert, eine WDF_WMI_PROVIDER_CONFIG-Struktur und eine WDF_WMI_INSTANCE_CONFIG-Struktur initialisiert und WdfWmiInstanceCreate aufgerufen.
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;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| KMDF-Mindestversion | 1.0 |
| Kopfzeile | wdfwmi.h (einschließen von Wdf.h) |
| Bibliothek | Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Weitere Informationen
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG