WMI_SET_DATAITEM_CALLBACK回呼函式 (wmilib.h)
DpWmiSetDataItem 例程會變更數據區塊實例中的單一數據項。 此例程是選擇性的。
語法
WMI_SET_DATAITEM_CALLBACK WmiSetDataitemCallback;
NTSTATUS WmiSetDataitemCallback(
[in] PDEVICE_OBJECT DeviceObject,
[in] PIRP Irp,
[in] ULONG GuidIndex,
[in] ULONG InstanceIndex,
[in] ULONG DataItemId,
[in] ULONG BufferSize,
[in] PUCHAR Buffer
)
{...}
參數
[in] DeviceObject
驅動程式 WDM DEVICE_OBJECT 結構的指標。
[in] Irp
IRP 的指標。
[in] GuidIndex
藉由將以零起始的索引提供給驅動程式在傳遞給 WmiSystemControl之WMILIB_CONTEXT結構中提供的 GUID 清單中，以指定數據區塊。
[in] InstanceIndex
如果 GuidIndex 指定的區塊有多個實例， InstanceIndex 是指定 實例的以零起始的值。
[in] DataItemId
指定要設定之數據項的識別碼。
[in] BufferSize
指定緩衝區大小，以位元組為單位的 Buffer。
[in] Buffer
緩衝區的指標，其中包含數據項的新值。
傳回值
DpWmiSetDataItem 會傳回STATUS_SUCCESS或適當的錯誤碼，如下所示：
備註
WMI 會在驅動程式呼叫 WmiSystemControl 以回應IRP_MN_CHANGE_SINGLE_ITEM要求之後呼叫驅動程式的 DpWmiSetDataItem 例程。
除非您確定系統提供的使用者模式元件需要這項功能，否則請勿實作 DpWmiSetDataItem 。 如果您實作 DpWmiSetDataItem 例程，驅動程式必須將例程的位址放在傳遞給 WmiSystemControl 之WMILIB_CONTEXT結構的 SetWmiDataItem 成員中。 如果您未實作 DpWmiSetDataItem 例程，驅動程式必須將 SetWmiDataItem 設定為 NULL。 在後者的情況下，WMI 會將STATUS_READ_ONLY傳回給呼叫端。
驅動程式負責驗證所有輸入自變數。 具體而言，驅動程式必須執行下列動作：
- 根據 WMILIB_CONTEXT 結構的 GuidCount 成員，確認 GuidIndex 值介於零和 GuidCount-1 之間。
- 確認驅動程式尚未將指定的數據區塊標示為移除。 如果驅動程式最近在包含在 WMILIB_CONTEXT 結構中的 WMIGUIDREGINFO 結構中指定 了 WMIREG_FLAG_REMOVE_GUID 旗標，在移除發生之前，可能會有設定要求送達。
- 確認 InstanceIndex 值位於數據區塊驅動程式支援的實例索引範圍內。
- 確認 DataItemId 值在數據區塊驅動程式所支援的數據項標識碼範圍內。
- 確認 Buffer 和 BufferSize 描述有效的大小數據項，而且緩衝區的內容對數據項有效。
- 確認指定的數據項是驅動程式允許呼叫端起始的修改之一。 換句話說，驅動程式不應允許修改您打算只讀的數據項。
此例程可以分頁。
如需實作此例程的詳細資訊，請參閱 呼叫 WmiSystemControl 來處理 WMI IRP。
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | 桌面 |
| 標頭 | wmilib.h (包含 Wmilib.h) |
| IRQL | 在 PASSIVE_LEVEL呼叫。 |