WdfWmiInstanceCreate 函式 (wdfwmi.h)

發行項
02/27/2024

[僅適用於 KMDF]

WdfWmiInstanceCreate 方法會建立代表 WMI 數據提供者實例的 WMI 實例物件。

語法

NTSTATUS WdfWmiInstanceCreate(
  [in]            WDFDEVICE                Device,
  [in]            PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES   InstanceAttributes,
  [out, optional] WDFWMIINSTANCE           *Instance
);

參數

[in] Device

架構裝置物件的句柄，代表要為其建立實例的裝置。裝置物件不能是控件裝置物件。

[in] InstanceConfig

呼叫端初始化 WDF_WMI_INSTANCE_CONFIG 結構的指標，其中包含 WMI 數據提供者實例的組態資訊。

[in, optional] InstanceAttributes

呼叫端配置的 WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含新 WMI 實例對象的驅動程式提供物件屬性。 (結構的 ParentObject 成員必須是 NULL。) 此參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out, optional] Instance

接收新 WMI 實例物件句柄之位置的指標。這個參數是選擇性的，而且可以是 NULL。

傳回值

如果作業成功，WdfWmiInstanceCreate 會傳回STATUS_SUCCESS。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INFO_LENGTH_MISMATCH	InstanceConfig 參數指向的WDF_WMI_INSTANCE_CONFIG結構大小不正確。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_INTEGER_OVERFLOW	驅動程式會將 WDF_WMI_INSTANCE_CONFIG 結構的UseContextForQuery成員設定為TRUE，但指定在InstanceAttributes 參數WDF_OBJECT_ATTRIBUTES結構中大於ULONG_MAX的內容空間大小。

如需 WdfWmiInstanceCreate 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

如果驅動程式正在建立提供者的多個實例，驅動程式必須呼叫 WdfWmiProviderCreate ，才能呼叫 WdfWmiInstanceCreate 來建立提供者物件。驅動程式會將提供者物件的句柄傳遞至 WdfWmiInstanceCreate ，方法是將句柄放在 WDF_WMI_INSTANCE_CONFIG 結構中。 (如果驅動程式提供提供者物件句柄， 則不會使用Device 參數，而且可以是 NULL.)

如果驅動程式正在建立提供者的單一實例，則不需要先呼叫 WdfWmiInstanceCreate ，再呼叫 WdfWmiInstanceCreate。在此情況下， WdfWmiInstanceCreate 也會建立 WMI 提供者物件。因此，驅動程式WDF_WMI_INSTANCE_CONFIG結構必須包含描述 WMI 數據提供者之WDF_WMI_PROVIDER_CONFIG 結構的指標。

架構會指示 WMI 從驅動程式實體裝置物件的裝置實例識別元建立動態實例名稱， (PDO) 。 (架構不支援 Windows 驅動程式模型 (WDM) 驅動程式在 IRP_MN_REGINFO 或 IRP_MN_REGINFO_EX structure 中設定的靜態實例名稱。)

WMI 實例物件的父代是 WMI 提供者物件。驅動程式無法變更此父代， 而且 ParentObject 成員或 WDF_OBJECT_ATTRIBUTES 結構必須是 NULL。

驅動程式呼叫 WdfWmiInstanceCreate 之後，它可以呼叫 WdfWmiInstanceGetProvider 來取得父提供者物件的句柄，而 WdfWmiInstanceGetDevice 則可取得提供者裝置的句柄。

如需 WdfWmiInstanceCreate 方法的詳細資訊，請參閱在 Framework-Based Drivers 中支援 WMI。

如果 InstanceConfig 指向的 WDF_WMI_INSTANCE_CONFIG 結構的 Register 成員為 TRUE，WdfWmiInstanceCreate 會同步登錄提供者實例， (亦即，在傳回) 如果在 IRQL = PASSIVE_LEVEL呼叫此方法，並在 IRQL > PASSIVE_LEVEL呼叫它時以異步方式呼叫。

範例

下列程式代碼範例來自 PCIDRV 範例驅動程式。此範例會註冊裝置的MOF資源名稱、初始化WDF_WMI_PROVIDER_CONFIG結構和WDF_WMI_INSTANCE_CONFIG結構，並呼叫 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;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfwmi.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)