PFNKSHANDLER 回呼函式 (ks.h)

發行項
02/26/2024

當 Kernel Streaming 收到 IOCTL_KS_METHOD、取得/設定屬性要求時，會呼叫 minidriver 提供的例程。在相關的 KSMETHOD_ITEM中提供此處理程式的指標， KSPROPERTY_ITEM 結構。

語法

PFNKSHANDLER Pfnkshandler;

NTSTATUS Pfnkshandler(
  [in]      PIRP Irp,
  [in]      PKSIDENTIFIER Request,
  [in, out] PVOID Data
)
{...}

參數

[in] Irp

指定包含方法或屬性要求的 IRP。

[in] Request

指定方法參數的對齊複本。這通常是 KSMETHOD 或 KSPROPERTY 結構的指標。

[in, out] Data

根據方法的 KSMETHOD_ITEM 結構中指定的旗標，指定方法數據參數的對齊複本或原始數據參數的系統位址。

傳回值

如果已處理方法，且數據緩衝區已根據KSMETHOD_ITEM中指定的旗標填入，則傳回STATUS_SUCCESS。如果傳回數據，您的驅動程式應該設定 Irp-IoStatus.Information> 欄位，但不應該設定 Irp-IoStatus.Status> 欄位，也不應該完成 IRP。如果 IRP 是以異步方式完成，請將 IRP 標示為擱置中。

或者，如果方法已處理，但尚未完成特定要求，而且呼叫協助程式函式必須完成，則傳回STATUS_SOME_NOT_MAPPED。傳回任何其他錯誤訊息，指出不支援方法或發生參數錯誤。

備註

minidriver 會在 KSMETHOD_ITEM 結構的 MethodHandler 成員中指定此例程的位址。

用於 KStrMethodHandler 和 KStrSupportHandler 的處理程式宣告也用於屬性和事件集的處理程式，具有相同的參數和傳回值。

當 KsMethodHandler 之類的協助程式函式呼叫方法處理程式，其數據緩衝區定義為寫入或修改緩衝區時，方法處理程式必須將 IRP (Irp) 參數內 IoStatus 成員之IO_STATUS_BLOCK結構的資訊成員設定為該數據緩衝區的大小。 minidriver 會設定方法KSMETHOD_TYPE_WRITE或KSMETHOD_TYPE_MODIFY之KSMETHOD_ITEM結構的 Flags 成員，以分別將方法處理程式的數據緩衝區定義為寫入或修改。

下列代碼段顯示方法處理程序實作的範例，該處理程式會設定 IRP 中傳回數據緩衝區的大小：

NTSTATUS
  MethodHandler(PIRP pIrp, PKSIDENTIFIER Request, PVOID Data) {
    NTSTATUS Status = STATUS_UNSUCCESSFUL;
    // Pointer to hold the position on the Irp stack
    PIO_STACK_LOCATION  pIrpStack  = NULL;
    ASSERT(pIrp);
    if(Data) {
        // Modify data here
    }
    // Find the current Irp stack.
    pIrpStack = IoGetCurrentIrpStackLocation(pIrp);
    if(pIrpStack) {
        // Set the size of the returning Irp data.
        pIrp->IoStatus.Information =
          pIrpStack->Parameters.DeviceIoControl.OutputBufferLength;
        Status = STATUS_SUCCESS;
    }
    return(Status);
}

minidriver 會在 KSPROPERTY_ITEM 結構的 GetPropertyHandler 成員中指定此例程的位址。

minidriver 會在 KSPROPERTY_ITEM 結構的 SetPropertyHandler 成員中指定此例程的位址。

minidriver 會在 KSMETHOD_ITEM 結構的 SupportHandler 成員中指定此例程的位址。

用於 KStrMethodHandler 和 KStrSupportHandler 的處理程式宣告也用於屬性和事件集的處理程式，具有相同的參數和傳回值。