PFNKSHANDLER コールバック関数 (ks.h)

[アーティクル]
08/07/2023

カーネルストリーミングが IOCTL_KS_METHODの get/set プロパティ要求を受信すると、ミニドライバーによって提供されるルーチンが呼び出されます。関連する 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 をマークします。

または、メソッドが処理されているが、特定の要求が完了していないため、呼び出し元のヘルパー関数によって完了する必要がある場合は、STATUS_SOME_NOT_MAPPEDを返します。メソッドがサポートされていないか、パラメーターエラーが発生したことを示すその他のエラーメッセージを返します。

注釈

ミニドライバーは、KSMETHOD_ITEM構造体の MethodHandler メンバーでこのルーチンのアドレスを指定します。

KStrMethodHandler と KStrSupportHandler に使用されるハンドラー宣言は、同じパラメーターと戻り値を持つプロパティとイベントセットのハンドラーにも使用されます。

KsMethodHandler などのヘルパー関数が、データバッファーが書き込みバッファーまたは変更バッファーとして定義されているメソッドハンドラーを呼び出す場合、メソッドハンドラーは、IRP (Irp パラメーター) 内の IoStatus メンバーのIO_STATUS_BLOCK構造体の Information メンバーを、そのデータバッファーのサイズに設定する必要があります。ミニドライバーは、メソッドのKSMETHOD_ITEM構造体の Flags メンバーをKSMETHOD_TYPE_WRITEまたはKSMETHOD_TYPE_MODIFYに設定して、メソッドハンドラーのデータバッファーをそれぞれ書き込みまたは変更として定義します。

次のコードスニペットは、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);
}

ミニドライバーは、KSPROPERTY_ITEM構造体の GetPropertyHandler メンバーで、このルーチンのアドレスを指定します。

ミニドライバーは、KSPROPERTY_ITEM構造体の SetPropertyHandler メンバーでこのルーチンのアドレスを指定します。

ミニドライバーは、KSMETHOD_ITEM構造体の SupportHandler メンバーで、このルーチンのアドレスを指定します。