Fungsi panggilan balik PFNKSHANDLER (ks.h)

Artikel
02/07/2025

Rutinitas yang disediakan minidriver dipanggil saat Kernel Streaming menerima permintaan properti IOCTL_KS_METHOD, get/set. Berikan penunjuk ke handler ini dalam struktur KSMETHOD_ITEM, KSPROPERTY_ITEM yang relevan.

Sintaksis

PFNKSHANDLER Pfnkshandler;

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

Parameter

[in] Irp

Menentukan IRP yang berisi metode atau permintaan properti.

[in] Request

Menentukan salinan parameter metode yang selaras. Ini biasanya merupakan penunjuk keKSMETHODatau strukturKSPROPERTY.

[in, out] Data

Menentukan salinan sejajar parameter data metode atau alamat sistem parameter data asli, tergantung pada bendera yang ditentukan dalam struktur KSMETHOD_ITEM untuk metode .

Mengembalikan nilai

Kembalikan STATUS_SUCCESS jika metode ditangani dan buffer data telah diisi per bendera yang ditentukan dalam KSMETHOD_ITEM. Jika mengembalikan data, driver Anda harus mengatur bidang Irp->IoStatus.Information, tetapi tidak boleh mengatur bidang Irp->IoStatus.Status juga tidak boleh menyelesaikan IRP. Tandai IRP yang tertunda jika akan diselesaikan secara asinkron.

Atau, kembalikan STATUS_SOME_NOT_MAPPED jika metode telah ditangani tetapi permintaan tertentu belum selesai dan harus diselesaikan oleh fungsi pembantu panggilan. Kembalikan pesan kesalahan lainnya untuk menunjukkan bahwa metode tidak didukung atau terjadi kesalahan parameter.

Komentar

Minidriver menentukan alamat rutin ini di MethodHandler anggota struktur KSMETHOD_ITEM.

Deklarasi handler yang digunakan untuk KStrMethodHandler dan KStrSupportHandler juga digunakan untuk handler properti dan set peristiwa, dengan parameter dan nilai pengembalian yang sama.

Ketika fungsi pembantu seperti KsMethodHandler memanggil handler metode yang buffer datanya didefinisikan sebagai buffer tulis atau modifikasi, handler metode harus mengatur Information anggota struktur IO_STATUS_BLOCK untuk anggota IoStatus dalam parameter IRP (Irp) ke ukuran buffer data tersebut. Minidriver mengatur Flags anggota struktur KSMETHOD_ITEM agar metode KSMETHOD_TYPE_WRITE atau KSMETHOD_TYPE_MODIFY menentukan buffer data handler metode sebagai tulis atau ubah masing-masing.

Cuplikan kode berikut menunjukkan contoh implementasi handler metode yang mengatur ukuran buffer data yang dikembalikan dalam 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 menentukan alamat rutin ini di GetPropertyHandler anggota struktur KSPROPERTY_ITEM.

Minidriver menentukan alamat rutin ini di SetPropertyHandler anggota struktur KSPROPERTY_ITEM.

Minidriver menentukan alamat rutin ini di SupportHandler anggota struktur KSMETHOD_ITEM.

Deklarasi handler yang digunakan untuk KStrMethodHandler dan KStrSupportHandler juga digunakan untuk handler properti dan set peristiwa, dengan parameter dan nilai pengembalian yang sama.