WdfWmiInstanceCreate-Funktion (wdfwmi.h)
[Gilt nur für KMDF]
Die WdfWmiInstanceCreate-Methode erstellt ein WMI-Instanzobjekt, das eine Instanz 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 zu einem Framework-Geräteobjekt, das das Gerät darstellt, für das die Instanz erstellt wird. Das Geräteobjekt kann kein Steuerelement-Geräteobjektsein.
[in] InstanceConfig
Ein Zeiger auf eine vom Aufrufer initialisierte WDF_WMI_INSTANCE_CONFIG-Struktur, die Konfigurationsinformationen für eine Instanz 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-Instanzobjekt 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-Instanzobjekt empfängt. Dieser Parameter ist optional und kann NULL-werden.
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. |
|
Nicht genügend Arbeitsspeicher vorhanden. |
|
Der Treiber legt den UseContextForQuery Member der WDF_WMI_INSTANCE_CONFIG Struktur auf TRUE- fest, aber eine Kontextraumgröße angegeben, die größer als ULONG_MAX in der InstanceAttributesWDF_OBJECT_ATTRIBUTES Struktur des Parameters ist. |
Eine Liste mit anderen Rückgabewerten, die von der WdfWmiInstanceCreate Methode möglicherweise zurückgegeben werden, finden Sie unter Framework Object Creation Errors.
Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.
Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.
Bemerkungen
Wenn ein Treiber mehrere Instanzen eines Anbieters erstellt, muss der Treiber WdfWmiProviderCreate aufrufen, um ein Anbieterobjekt zu erstellen, bevor WdfWmiInstanceCreateaufgerufen wird. Der Treiber übergibt das Handle des Anbieterobjekts an WdfWmiInstanceCreate, indem der Handle in einer WDF_WMI_INSTANCE_CONFIG-Struktur platziert wird. (Wenn der Treiber ein Anbieterobjekthandle bereitstellt, wird der parameter Device nicht verwendet und kann NULL-sein.)
Wenn der Treiber eine einzelne Instanz eines Anbieters erstellt, muss er nicht WdfWmiInstanceCreate aufrufen, bevor WdfWmiInstanceCreateaufgerufen wird. 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 Instanznamen zu erstellen, den Anwendungen verwenden können, aus der Geräteinstanz-ID des physischen Geräteobjekts des Treibers (PDO). (Das Framework unterstützt keine statischen Instanznamen, die windows Driver Model (WDM)-Treiber in einer IRP_MN_REGINFO- oder IRP_MN_REGINFO_EX-Struktur festgelegt sind.)
Das übergeordnete Objekt des WMI-Instanzobjekts 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 WdfWmiInstanceCreateaufgerufen hat, kann er WdfWmiInstanceGetProvider- aufrufen, um ein Handle für das übergeordnete Anbieterobjekt abzurufen, 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 das Register Member der WDF_WMI_INSTANCE_CONFIG Struktur, auf die InstanceConfig verweist, TRUEist, WdfWmiInstanceCreate registriert die Anbieterinstanz synchron (d. h. vor dem Zurückgeben), wenn diese Methode bei IRQL = PASSIVE_LEVEL aufgerufen wird und asynchron, wenn sie bei 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 WdfWmiInstanceCreateaufgerufen.
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- | Universal |
| Minimale KMDF-Version | 1.0 |
| Header- | wdfwmi.h (einschließen Wdf.h) |
| Library | Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.) |
| IRQL- | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Siehe auch
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG