IRP_MN_CHANGE_SINGLE_ITEM

所有支援 WMI 的驅動程式都必須處理此 IRP。 驅動程式可以呼叫 WmiSystemControl 或處理 IRP 本身來處理 WMI IRP,如 處理 WMI 要求中所述。

如果驅動程式呼叫 WmiSystemControl 來處理 IRP_MN_CHANGE_SINGLE_ITEM 要求,WMI 接著會呼叫該驅動程式的 DpWmiSetDataItem 常式。

主要程式碼

IRP_MJ_SYSTEM_CONTROL

傳送時

WMI 會傳送此 IRP 來變更單一資料區塊實例中的單一資料項目。

WMI 會在 IRQL = PASSIVE_LEVEL任意執行緒內容中傳送此 IRP。

輸入參數

Parameters.WMI.ProviderId 指向應回應要求的驅動程式裝置物件。 此指標位於 IRP 的驅動程式 I/O 堆疊位置。

Parameters.WMI.DataPath 指向可識別要設定之資料區塊的 GUID。

Parameters.WMI.BufferSize 指出 Parameters.WMI.Buffer的非分頁緩衝區大小。

Parameters.WMI.Buffer會指向 WNODE_SINGLE_ITEM 結構,識別資料區塊的實例、要設定的專案識別碼,以及新的資料值。

輸出參數

無。

I/O 狀態欄塊

如果驅動程式藉由呼叫 WmiSystemControl來處理 IRP,WMI 會在 I/O 狀態欄塊中設定 Irp-IoStatus.Status >Irp-IoStatus.Information >

否則,驅動程式會將 Irp-IoStatus.Status > 設定為STATUS_SUCCESS或適當的錯誤狀態,例如:

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

成功時,驅動程式會將 Irp-IoStatus.Information > 設定為零。

作業

如果驅動程式藉由呼叫 WmiSystemControl 來處理 WMI IRP,該常式會呼叫驅動程式的 DpWmiSetDataItem 常式,如果驅動程式未定義常式,則會傳回STATUS_WMI_READ_ONLY。

如果驅動程式處理 IRP_MN_CHANGE_SINGLE_ITEM 本身,只有當 Parameters.WMI.ProviderId 指向與驅動程式傳遞至 IoWMIRegistrationControl的指標相同的裝置物件時,才應該這麼做。 否則,驅動程式必須將要求轉送至下一個較低的驅動程式。

除非您確定系統提供的使用者模式元件需要這項功能,否則請勿實作 IRP_MN_CHANGE_SINGLE_ITEM 支援。

處理要求之前,驅動程式必須判斷 Parameters.WMI.DataPath 是否指向驅動程式支援的 GUID。 如果沒有,驅動程式必須失敗 IRP 並傳回STATUS_WMI_GUID_NOT_FOUND。

如果驅動程式支援資料區塊,它必須檢查Parameters.WMI.Buffer指向的輸入WNODE_SINGLE_ITEM結構,以取得實例名稱,如下所示:

  • 如果在 WnodeHeader.Flags中設定WNODE_FLAG_STATIC_INSTANCE_NAMES,驅動程式會使用 InstanceIndex 做為該區塊之靜態實例名稱的索引。 WMI 會從驅動程式註冊區塊時所提供的註冊資料取得索引。

  • 如果在 WnodeHeader.Flags 中清除WNODE_FLAG_STATIC_INSTANCE_NAMES,驅動程式會使用 OffsetInstanceName 的位移,在輸入 WNODE_SINGLE_ITEM 結構中找出實例名稱字串。 OffsetInstanceName 是從結構開頭到實例名稱字串的 USHORT 大小長度的位元組位移, (不是字元) 。 如果存在,這個長度會包含 Null 結束字元,後面接著 Unicode 中的實例名稱字串。

驅動程式負責驗證所有輸入值。 具體而言,如果驅動程式處理 IRP 要求本身,則必須執行下列動作:

  • 針對靜態名稱,請確認WNODE_SINGLE_ITEM結構的 InstanceIndex 成員位於資料區塊驅動程式支援的實例索引範圍內。

  • 針對動態名稱,請確認實例名稱字串識別驅動程式支援的資料區塊實例。

  • 確認WNODE_SINGLE_ITEM結構的ItemId成員位於資料區塊驅動程式支援的專案識別碼範圍內。

  • 確認WNODE_SINGLE_ITEM結構的DataBlockOffsetSizeDataItem成員描述有效的資料區塊,以及緩衝區的內容對資料項目有效。

  • 確認指定的資料項目是驅動程式允許呼叫端起始的修改之一。 換句話說,驅動程式不應該允許修改您想要唯讀的資料項目。

請勿假設執行緒內容是起始使用者模式應用程式的執行緒內容,較高層級的驅動程式可能已經變更它。

如果驅動程式找不到指定的實例,它必須失敗 IRP 並傳回STATUS_WMI_INSTANCE_NOT_FOUND。 對於具有動態實例名稱的實例,此狀態表示驅動程式不支援 實例。 因此,WMI 可以繼續查詢其他資料提供者,如果另一個提供者找到實例,但因其他原因而無法處理要求,則傳回適當的錯誤給資料取用者。

如果驅動程式找到 實例,而且可以處理要求,它會將 實例中的資料項目設定為 WNODE_SINGLE_ITEM中的值。 如果資料項目是唯讀的,驅動程式會將專案保留不變、IRP 失敗,並傳回STATUS_WMI_READ_ONLY。

如果實例有效,但驅動程式無法處理要求,它可以傳回任何適當的錯誤狀態。

規格需求

標頭

Wdm.h (包括 Wdm.h、Ntddk.h 或 Ntifs.h)

另請參閱

DpWmiSetDataItem

IoWMIRegistrationControl

WMILIB_CONTEXT

WmiSystemControl

WNODE_SINGLE_ITEM