共用方式為


WMI_EXECUTE_METHOD_CALLBACK回呼函式 (wmilib.h)

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

藉由將以零起始的索引提供給驅動程式在傳遞給 WmiSystemControlWMILIB_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 例程,驅動程式必須將例程的位址放在傳遞至 WmiSystemControlWMILIB_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 所提供的方法識別碼是指定數據區塊的有效識別碼,而且允許呼叫端執行方法。
  • 確認 BufferInBufferSize 描述足以包含指定方法輸入參數的緩衝區,包括在必要時填補,並確認輸入參數有效。
  • 確認 BufferOutBufferSize 描述足以接收指定方法輸出資料的緩衝區,包括在必要時填補。
請勿假設線程內容是起始使用者模式應用程式的線程內容,較高層級的驅動程式可能已經變更它。

如果指定的方法執行導致數據遺失的作業,例如擷取和重設一組計數器的內容,驅動程式應該先驗證輸出緩衝區大小,再執行作業。 如此一來,驅動程式就可以傳回STATUS_BUFFER_TOO_SMALL,並允許呼叫端以較大的緩衝區重新提交要求,而不會提前重設計數器。

執行 方法並將任何輸出數據寫入緩衝區之後,驅動程式會呼叫 WmiCompleteRequest 來完成要求。

這個例程可以是可分頁的。

如需實作此例程的詳細資訊,請參閱 呼叫 WmiSystemControl 來處理 WMI IRP

規格需求

需求
目標平台 桌面
標頭 wmilib.h (包含 Wmilib.h)
IRQL 在 PASSIVE_LEVEL呼叫。

另請參閱

IRP_MN_EXECUTE_METHOD

WMILIB_CONTEXT

WmiCompleteRequest

WmiSystemControl