WdfWmiInstanceCreate-Funktion (wdfwmi.h)

Artikel
08/08/2023

[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
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_WMI_INSTANCE_CONFIG Struktur, auf die der InstanceConfig-Parameter verweist, war falsch.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden.
STATUS_INTEGER_OVERFLOW	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)