WMI_EXECUTE_METHOD_CALLBACK回呼函式 (wmilib.h)

發行項
03/01/2024

DpWmiExecuteMethod 例程會執行與數據區塊相關聯的方法。此例程是選擇性的。

語法

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

參數

[in] DeviceObject

驅動程式的 WDM DEVICE_OBJECT 結構的指標。

[in] Irp

IRP 的指標。

[in] GuidIndex

藉由將以零起始的索引提供給驅動程式在傳遞給 WmiSystemControl 的 WMILIB_CONTEXT 結構中提供的 GUID 清單中，以指定數據區塊。

[in] InstanceIndex

如果 GuidIndex 指定的區塊有多個實例， InstanceIndex 會指定識別實例之以零起始的索引值。

[in] MethodId

指定要執行之方法的識別碼。驅動程式會將方法識別元定義為數據區塊中的專案。

[in] InBufferSize

表示輸入數據位元組的大小。如果沒有輸入數據， InBufferSize 為零。

[in] OutBufferSize

指出緩衝區中可用的輸出數據位元組數目。

[in, out] Buffer

包含輸入數據的緩衝區指標，如果有的話，並接收方法的輸出數據。如果緩衝區太小而無法接收所有輸出數據，驅動程式會傳回STATUS_BUFFER_TOO_SMALL，並呼叫具有所需大小的 WmiCompleteRequest 。

傳回值

DpWmiExecuteMethod 會傳回STATUS_SUCCESS或適當的錯誤碼，如下所示：

備註

WMI 會在驅動程式呼叫 WmiSystemControl 以回應IRP_MN_EXECUTE_METHOD要求之後呼叫驅動程式的 DpWmiExecuteMethod 例程。

如果驅動程式實作 DpWmiExecuteMethod 例程，驅動程式必須將例程的位址放在傳遞至 WmiSystemControl 之 WMILIB_CONTEXT 結構的 ExecuteWmiMethod 成員中。如果驅動程式未實作 DpWmiExecuteMethod 例程，則必須將 ExecuteWmiMethod 設定為 NULL。在後者的情況下，WMI 會傳回STATUS_INVALID_DEVICE_REQUEST給呼叫端，以回應任何 IRP_MN_EXECUTE_METHOD 要求。

驅動程式負責驗證所有輸入自變數。具體而言，驅動程式必須執行下列動作：

根據 WMILIB_CONTEXT 結構的 GuidCount 成員，確認 GuidIndex 值介於零和 GuidCount-1 之間。
確認驅動程式尚未標示要移除的指定數據區塊。如果驅動程式最近在包含在WMILIB_CONTEXT 結構中的 WMIGUIDREGINFO 結構中指定WMIREG_FLAG_REMOVE_GUID旗標，在移除發生之前，可能會有其他要求抵達。
確認 InstanceIndex 值位於數據區塊驅動程式支援的實例索引範圍內。
確認 MethodId 所提供的方法識別碼是指定數據區塊的有效識別碼，而且允許呼叫端執行方法。
確認 Buffer 和 InBufferSize 描述足以包含指定方法輸入參數的緩衝區，包括在必要時填補，並確認輸入參數有效。
確認 Buffer 和 OutBufferSize 描述足以接收指定方法輸出資料的緩衝區，包括在必要時填補。