Freigeben über


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
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
Nicht genügend Arbeitsspeicher vorhanden.
STATUS_INTEGER_OVERFLOW
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

IRP_MN_REGINFO

WDF_OBJECT_ATTRIBUTES

WDF_WMI_INSTANCE_CONFIG

WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG_INIT

WdfDeviceAssignMofResourceName

WdfWmiInstanceGetDevice

WdfWmiInstanceGetProvider-

WdfWmiProviderCreate