WdfWmiProviderCreate 函式 (wdfwmi.h)

發行項
02/27/2024

[僅適用於 KMDF]

WdfWmiProviderCreate 方法會建立代表 WMI 數據區塊的 WMI 提供者物件。

語法

NTSTATUS WdfWmiProviderCreate(
  [in]           WDFDEVICE                Device,
  [in]           PWDF_WMI_PROVIDER_CONFIG WmiProviderConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   ProviderAttributes,
  [out]          WDFWMIPROVIDER           *WmiProvider
);

參數

[in] Device

架構裝置物件的句柄，該物件將是新提供者物件的父物件。裝置物件不能是控件裝置物件。

[in] WmiProviderConfig

呼叫端初始化 WDF_WMI_PROVIDER_CONFIG 結構的指標，其中包含有關WMI數據區塊的組態資訊。

[in, optional] ProviderAttributes

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

[out] WmiProvider

接收新 WMI 提供者物件句柄之位置的指標。

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INFO_LENGTH_MISMATCH	WmiProviderConfig 參數指向的WDF_WMI_PROVIDER_CONFIG結構大小不正確。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足，無法完成作業。
STATUS_OBJECT_NAME_EXISTS	驅動程式已針對指定的裝置和 WMI 數據區塊呼叫 WdfWmiProviderCreate 。

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

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

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

備註

如果驅動程式將建立提供者的多個實例，您的驅動程式必須呼叫 WdfWmiProviderCreate 來建立 WMI 提供者物件。如果驅動程式只會建立提供者的一個實例，它可以呼叫 WdfWmiInstanceCreate ，而不需要先呼叫 WdfWmiProviderCreate。

驅動程式可以隨時呼叫 WdfWmiProviderCreate，但驅動程式通常會從其 EvtDriverDeviceAdd 回呼函式內呼叫 WdfWmiProviderCreate。

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

驅動程式呼叫 WdfWmiProviderCreate 之後，驅動程式可以呼叫 WdfWmiProviderGetDevice 來擷取提供者物件的父裝置物件的句柄。

在驅動程式建立 WMI 提供者對象之後，驅動程式就無法刪除物件。當架構刪除代表裝置的架構裝置物件時，架構會刪除裝置的 WMI 提供者物件。 WMI 提供者物件使用最少的系統資源。

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

範例

下列程式代碼範例會初始化 WDF_WMI_PROVIDER_CONFIG結構，並呼叫 WdfWmiProviderCreate。

WDF_WMI_PROVIDER_CONFIG config;
WDFWMIPROVIDER provider;
GUID providerGuid = MY_WMI_DATA_BLOCK_GUID;
NTSTATUS status;

WDF_WMI_PROVIDER_CONFIG_INIT(
                             &config,
                             providerGuid
                             );
config.Flags = WdfWmiProviderTracing;
config.EvtWmiProviderFunctionControl = MyProviderFunctionControl;

status = WdfWmiProviderCreate(
                              Device,
                              &config,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &provider
                              );

規格需求

需求	值
目標平台	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)