EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START fungsi panggilan balik (sercx.h)

Artikel
08/07/2023

Fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionStart dipanggil oleh versi 2 dari ekstensi kerangka kerja serial (SerCx2) untuk memulai transaksi penerimaan kustom.

Sintaks

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START EvtSercx2CustomReceiveTransactionStart;

void EvtSercx2CustomReceiveTransactionStart(
  [in] SERCX2CUSTOMRECEIVETRANSACTION CustomReceiveTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parameter

[in] CustomReceiveTransaction

Handel SERCX2CUSTOMRECEIVETRANSACTION ke objek transaksi penerima kustom. Driver pengontrol serial sebelumnya disebut metode SerCx2CustomReceiveTransactionCreate untuk membuat objek ini.

[in] Request

Handel ke objek permintaan kerangka kerja yang terkait dengan transaksi penerima kustom. Driver bertanggung jawab untuk menyelesaikan permintaan ini. Permintaan ini mungkin bukan permintaan IRP_MJ_READ yang dikirim oleh klien, dan dengan demikian driver pengontrol serial tidak boleh mencoba menggunakan permintaan ini untuk mengakses buffer baca. Permintaan ini terutama digunakan untuk pembatalan, penyelesaian, dan penerusan antrean (jika diperlukan). Untuk mengakses buffer baca untuk permintaan baca klien, gunakan parameter Mdl, Offset, dan Length .

[in] Mdl

Penunjuk ke MDL yang menjelaskan halaman memori yang dibentangkan oleh buffer baca untuk transaksi penerima kustom. Daftar sebar/kumpulkan untuk transfer data akan menggunakan wilayah memori ini yang ditentukan oleh parameter Offset dan Panjang .

[in] Offset

Offset awal untuk transfer data. Parameter ini adalah offset byte dari awal wilayah buffer yang dijelaskan oleh MDL. Jika MDL menentukan total N byte ruang buffer, kemungkinan nilai Offset berada dalam rentang 0 hingga N–1.

[in] Length

Ukuran, dalam byte, dari transfer data. Jika MDL menentukan total N byte ruang buffer, kemungkinan nilai Panjang berada dalam rentang 1 hingga N–Offset.

Nilai kembali

Tidak ada

Keterangan

Driver pengontrol serial Anda harus menerapkan fungsi ini jika membuat objek transaksi penerima kustom. Driver mendaftarkan fungsi dalam panggilan SerCx2CustomReceiveTransactionCreate yang membuat objek ini.

Setelah SerCx2 memanggil fungsi EvtSerCx2CustomReceiveTransactionStart , driver pengontrol serial memulai transaksi dengan memprogram mekanisme transfer data kustom untuk memindahkan data dari FIFO penerima di perangkat keras pengontrol serial ke buffer dalam permintaan baca. Kecuali permintaan dapat segera diselesaikan, sebelum fungsi EvtSerCx2CustomReceiveTransactionStart kembali, driver harus memanggil metode seperti WdfRequestMarkCancelableEx untuk menandai permintaan sebagai dapat dibatalkan.

Setelah fungsi EvtSerCx2CustomReceiveTransactionStart memulai transaksi, SerCx2 secara berkala memanggil fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionQueryProgress untuk memantau kemajuan yang dibuat oleh driver pengontrol serial dalam melakukan transaksi ini. Setelah transaksi selesai dan driver menyelesaikan permintaan baca yang tertunda, SerCx2 memanggil fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionCleanup , jika driver mengimplementasikan fungsi ini.

Jika driver pengontrol serial mengimplementasikan fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionInitialize , SerCx2 memanggil fungsi ini sebelum memanggil fungsi EvtSerCx2CustomReceiveTransactionStart . Tepat sebelum panggilan EvtSerCx2CustomReceiveTransactionStart , dan setelah panggilan EvtSerCx2CustomReceiveTransactionInitialize kembali, SerCx2 memulai timer yang mendeteksi apakah waktu permintaan baca habis. Untuk informasi selengkapnya, lihat diskusi total waktu habis dalam SERIAL_TIMEOUTS.

Jika mekanisme transfer data kustom adalah perangkat DMA master bus, fungsi EvtSerCx2CustomReceiveTransactionStart dapat memanggil metode seperti WdfDmaTransactionInitializeUsingOffset untuk memulai transaksi DMA yang menggunakan buffer baca yang dijelaskan oleh parameter Mdl, Offset, dan Length .

Jika objek permintaan yang diidentifikasi oleh parameter Permintaan berisi penyimpanan untuk konteks privat, penyimpanan ini mungkin tidak diinisialisasi saat pertama kali driver pengontrol serial mengakses konteks. Pada akses pertama, driver biasanya harus mengisi konteks dengan nol, lalu, jika diperlukan, secara eksplisit mengatur bidang apa pun dalam konteks yang memerlukan nilai awal bukan nol.

Untuk informasi selengkapnya, lihat SerCx2 Custom-Receive Transactions.

Contoh

Untuk menentukan fungsi panggilan balik EvtSerCx2CustomReceiveTransactionStart , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan fungsi panggilan balik EvtSerCx2CustomReceiveTransactionStart yang diberi nama MyCustomReceiveTransactionStart, gunakan jenis fungsi EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START , seperti yang ditunjukkan dalam contoh kode ini:

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START  MyCustomReceiveTransactionStart;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionStart(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

Jenis fungsi EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START ditentukan dalam file header Sercx.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver KMDF. Untuk informasi selengkapnya tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.1.
Target Platform	Desktop
Header	sercx.h
IRQL	Dipanggil di IRQL <= DISPATCH_LEVEL.