WdfWmiInstanceCreate 函式（wdfwmi.h）

發行項
02/07/2025

[僅適用於 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。否則，此方法可能會傳回下列其中一個值：

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

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

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

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

言論

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

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

架構會指示 WMI 從驅動程式實體裝置物件的裝置實例識別元建立動態實例名稱，應用程式可以使用該名稱。（架構不支援 Windows 驅動程式模型（WDM）驅動程式在 IRP_MN_REGINFO 或 IRP_MN_REGINFO_EX 結構中設定的靜態實例名稱。

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;
}

要求

要求	價值
目標平臺	普遍
最低 KMDF 版本	1.0
標頭	wdfwmi.h （包括 Wdf.h）
連結庫	Wdf01000.sys （請參閱架構連結庫版本控制。）
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）