IRP_MN_EXECUTE_METHOD

發行項
06/15/2023

支援資料區塊內方法的所有驅動程式都必須處理此 IRP。驅動程式可以藉由呼叫 WmiSystemControl 或處理 IRP 本身來處理 WMI IRP，如處理 WMI 要求中所述。

如果驅動程式呼叫 WmiSystemControl 來處理 IRP_MN_EXECUTE_METHOD 要求，WMI 接著會呼叫該驅動程式的 DpWmiExecuteMethod 常式。

主要程式碼

傳送時

WMI 會傳送這個 IRP 來執行與資料區塊相關聯的方法。

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

WMI 會在傳送 IRP_MN_EXECUTE_METHOD 之前傳送 IRP_MN_QUERY_SINGLE_INSTANCE。如果驅動程式支援 IRP_MN_EXECUTE_METHOD 它必須有執行方法之相同資料區塊 的IRP_MN_QUERY_SINGLE_INSTANCE 處理常式。

輸入參數

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

Parameters.WMI.DataPath 指向 GUID，識別與要執行之方法相關聯的資料區塊。

Parameters.WMI.BufferSize 指出 Parameters.WMI.Buffer 的非分頁緩衝區大小，其大小必須是 > = sizeof (WNODE_METHOD_ITEM) 加上方法的任何輸出資料的大小。

Parameters.WMI.Buffer 指向 WNODE_METHOD_ITEM 結構，其中 MethodID 指出要執行的方法識別碼，而 DataBlockOffset 表示結構開頭到輸入資料第一個位元組的位移。 Parameters.WMI.Buffer- >SizeDataBlock 指出輸入 WNODE_METHOD_ITEM 包含輸入資料的大小，如果沒有輸入，則為零。

輸出參數

如果驅動程式藉由呼叫 WmiSystemControl 來處理 WMI IRP，WMI 會填入 WNODE_METHOD_ITEM 驅動程式 的 DpWmiExecuteMethod 常式所傳回的資料。

否則，驅動程式會填入Parameters.WMI.Buffer指向的WNODE_METHOD_ITEM結構，如下所示：

更新WnodeHeader.BufferSize，輸出大小WNODE_METHOD_ITEM，包括任何輸出資料。
更新具有輸出資料大小的SizeDataBlock，如果沒有輸出資料，則為零。
檢查 Parameters.WMI.Buffersize ，以判斷緩衝區是否夠大，足以接收輸出 WNODE_METHOD_ITEM 包括任何輸出資料。如果緩衝區不夠大，驅動程式會在Parameters.WMI.Buffer所指向WNODE_TOO_SMALL結構中填入所需的大小。如果緩衝區小於 sizeof (WNODE_TOO_SMALL) ，驅動程式會失敗 IRP 並傳回STATUS_BUFFER_TOO_SMALL。
寫入輸出資料，如果有的話，透過從 DataBlockOffset開始的輸入資料。驅動程式不得變更 DataBlockOffset的輸入值。

I/O 狀態欄塊

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

否則，驅動程式會將 Irp-IoStatus.Status > 設定為STATUS_SUCCESS或適當的錯誤狀態，如下所示：

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

成功時，驅動程式會將 Irp-IoStatus.Information > 設定為寫入至 Parameters.WMI.Buffer之緩衝區的位元組數目。

作業

驅動程式可以藉由呼叫 WmiSystemControl 或處理 IRP 本身來處理 WMI IRP，如處理 WMI 要求中所述。

如果驅動程式藉由呼叫 WmiSystemControl 來處理 WMI IRP，該常式會呼叫驅動程式的 DpWmiExecuteMethod 常式，或如果驅動程式未定義常式，則會傳回STATUS_INVALID_DEVICE_REQUEST。

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

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

針對靜態名稱，請確認WNODE_METHOD_ITEM結構的InstanceIndex成員位於資料區塊驅動程式支援的實例索引範圍內。
針對動態名稱，請確認實例名稱字串會識別驅動程式支援的資料區塊實例。
確認WNODE_METHOD_ITEM結構的MethodId成員在資料區塊的驅動程式所支援的方法識別碼範圍內，而且允許呼叫端執行方法。
確認WNODE_METHOD_ITEM結構的DataBlockOffset和SizeDataBlock成員描述足以包含指定方法參數的緩衝區，以及參數對方法有效。
確認 Parameters.WMI.Buffersize 指定足以在更新輸出資料之後接收 WNODE_METHOD_ITEM 結構的緩衝區。

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

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

如果驅動程式支援資料區塊，它會在Parameters.WMI.Buffer檢查輸入WNODE_METHOD_ITEM實例名稱，如下所示：

如果在 WnodeHeader.Flags中設定WNODE_FLAG_STATIC_INSTANCE_NAMES，驅動程式會使用 InstanceIndex 作為該區塊之驅動程式靜態實例名稱清單的索引。 WMI 會從驅動程式註冊區塊時所提供的註冊資料取得索引。
如果在 WnodeHeader.Flags 中清除WNODE_FLAG_STATIC_INSTANCE_NAMES，驅動程式會使用 OffsetInstanceName 的位 移來找出輸入 WNODE_METHOD_ITEM中的實例名稱字串。 OffsetInstanceName 是結構開頭到 USHORT 的位元組位移，這是實例名稱字串的長度，以位元組為單位， (非字元) ，包括如果有終止 Null，後面接著 Unicode 中的實例名稱字串。

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

驅動程式接著會檢查輸入 WNODE_METHOD_ITEM 中的方法識別碼，以判斷它是否為該資料區塊的有效方法。如果沒有，驅動程式會失敗 IRP 並傳回STATUS_WMI_ITEMID_NOT_FOUND。

如果方法產生輸出，驅動程式應該先檢查 Parameters.WMI.BufferSize 中的輸出緩衝區大小，再執行任何可能有副作用或不應該執行兩次的作業。例如，如果方法傳回一組計數器的值，然後重設計數器，驅動程式應該檢查緩衝區大小 (，如果緩衝區太小) ，在重設計數器之前，IRP 會失敗。這可確保 WMI 可以使用較大的緩衝區安全地重新傳送要求。

如果實例和方法識別碼有效，且緩衝區大小足夠，驅動程式會執行方法。如果輸入WNODE_METHOD_ITEM中的SizeDataBlock為非零，驅動程式會使用從DataBlockOffset開始的資料作為方法的輸入。

如果方法產生輸出，驅動程式會從 DataBlockOffset 開始將輸出資料寫入緩衝區，並將輸出中的 SizeDataBlock設定為 輸出資料的位元組數WNODE_METHOD_ITEM。如果方法沒有輸出資料，驅動程式會將 SizeDataBlock 設定為零。驅動程式不得變更 DataBlockOffset的輸入值。

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