EVT_SERCX2_CONTROL fungsi panggilan balik (sercx.h)

Artikel
03/08/2023

Fungsi panggilan balik peristiwa EvtSerCx2Control dipanggil oleh versi 2 dari ekstensi kerangka kerja serial (SerCx2) untuk menangani permintaan kontrol I/O serial.

Sintaks

EVT_SERCX2_CONTROL EvtSercx2Control;

NTSTATUS EvtSercx2Control(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

Parameter

[in] Device

Handel WDFDEVICE ke objek perangkat kerangka kerja yang mewakili pengontrol serial. Driver pengontrol serial membuat objek ini dalam fungsi panggilan balik EvtDriverDeviceAdd . Untuk informasi selengkapnya, lihat SerCx2InitializeDevice.

[in] Request

Handel WDFREQUEST ke objek permintaan kerangka kerja yang mewakili permintaan kontrol I/O serial.

[in] OutputBufferLength

Panjang, dalam byte, dari buffer output untuk permintaan kontrol I/O serial yang ditentukan oleh parameter Permintaan .

[in] InputBufferLength

Panjangnya, dalam byte, dari buffer input untuk permintaan kontrol I/O serial yang ditentukan oleh parameter Permintaan .

[in] IoControlCode

Menentukan kode kontrol I/O (IOCTL) dari permintaan kontrol I/O serial yang ditentukan oleh parameter Permintaan . IOCTL untuk permintaan kontrol I/O serial didefinisikan dalam file header Ntddser.h. Untuk informasi selengkapnya, lihat Keterangan.

Mengembalikan nilai

Fungsi EvtSerCx2Control mengembalikan STATUS_SUCCESS jika panggilan berhasil. Jika tidak, kode status kesalahan akan ditampilkan.

Keterangan

Driver pengontrol serial Anda harus menerapkan fungsi ini. Driver mendaftarkan fungsi dalam panggilan ke metode SerCx2InitializeDevice yang menyelesaikan inisialisasi objek perangkat kerangka kerja untuk pengontrol serial.

Fungsi EvtSerCx2Control memungkinkan driver Anda menangani permintaan kontrol I/O serial tertentu yang tidak dapat ditangani SerCx2. SerCx2 menangani semua pemrosesan untuk subset IOCTL serial yang didefinisikan dalam file header Ntddser.h. Namun, SerCx2 mengandalkan driver untuk menangani permintaan kontrol I/O serial untuk melakukan operasi yang bergantung pada perangkat keras.

Ketika SerCx2 menerima permintaan kontrol I/O serial yang hanya dapat ditangani oleh driver pengontrol serial, SerCx2 memanggil fungsi EvtSerCx2Control untuk menyerahkan permintaan kontrol I/O ke driver. Driver bertanggung jawab untuk menyelesaikan permintaan ini. Driver yang tidak menerapkan dukungan untuk permintaan kontrol I/O tertentu harus menyelesaikan permintaan kontrol I/O ini dengan kode status kesalahan STATUS_NOT_SUPPORTED.

Untuk menyelesaikan permintaan kontrol I/O, driver biasanya memanggil metode dan persediaan WdfRequestComplete , sebagai parameter input, nilai parameter Permintaan , dan nilai status untuk menunjukkan apakah permintaan berhasil. Nilai status ini ditulis ke blok status permintaan.

Nilai pengembalian fungsi EvtSerCx2Control harus selalu cocok dengan nilai status yang ditulis fungsi ini ke blok status permintaan kontrol I/O. Implementasi SerCx2 saat ini mengabaikan nilai pengembalian ini.

SerCx2 memanggil fungsi EvtSerCx2Control untuk menangani IOCTL yang diperlihatkan dalam tabel berikut. Kolom di sisi kanan tabel menunjukkan apakah fungsi EvtSerCx2Control diperlukan untuk mengimplementasikan dukungan untuk IOCTL tertentu.

Nama permintaan kontrol I/O	Diperlukan atau opsional
IOCTL_SERIAL_CLR_DTR	Opsional
IOCTL_SERIAL_CLR_RTS	Diperlukan
IOCTL_SERIAL_GET_BAUD_RATE	Diperlukan
IOCTL_SERIAL_GET_COMMSTATUS	Diperlukan
IOCTL_SERIAL_GET_DTRRTS	Diperlukan
IOCTL_SERIAL_GET_HANDFLOW	Diperlukan
IOCTL_SERIAL_GET_LINE_CONTROL	Diperlukan
IOCTL_SERIAL_GET_MODEM_CONTROL	Diperlukan
IOCTL_SERIAL_GET_MODEMSTATUS	Diperlukan
IOCTL_SERIAL_GET_PROPERTIES	Diperlukan
IOCTL_SERIAL_SET_BAUD_RATE	Diperlukan
IOCTL_SERIAL_SET_BREAK_OFF	Diperlukan
IOCTL_SERIAL_SET_BREAK_ON	Diperlukan
IOCTL_SERIAL_SET_DTR	Opsional
IOCTL_SERIAL_SET_FIFO_CONTROL	Opsional
IOCTL_SERIAL_SET_HANDFLOW	Diperlukan
IOCTL_SERIAL_SET_LINE_CONTROL	Diperlukan
IOCTL_SERIAL_SET_MODEM_CONTROL	Diperlukan
IOCTL_SERIAL_SET_RTS	Diperlukan

Tabel sebelumnya mencantumkan semua IOCTL serial yang disajikan SerCx2 ke fungsi EvtSerCx2Control . Untuk IOCTL apa pun yang tidak ada dalam daftar ini, SerCx2 menangani IOCTL, atau segera gagal IOCTL dan mengatur status permintaan ke STATUS_NOT_SUPPORTED. SerCx2 menangani permintaan IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION , tetapi memanggil fungsi panggilan balik peristiwa EvtSerCx2ApplyConfig selama pemrosesan permintaan tersebut. SerCx2 menangani permintaan IOCTL_SERIAL_PURGE , tetapi mungkin memanggil fungsi panggilan balik peristiwa EvtSerCx2PurgeFifos selama pemrosesan permintaan tersebut. SerCx melakukan pemrosesan awal permintaan IOCTL_SERIAL_SET_WAIT_MASK , tetapi memanggil fungsi panggilan balik peristiwa EvtSerCx2SetWaitMask , jika diimplementasikan, untuk menyelesaikan penanganan permintaan tersebut. Untuk informasi selengkapnya tentang dukungan SerCx2 untuk IOCTL serial, lihat Serial I/O Request Interface.

IOCTL_SERIAL_CLR_DTR dan IOCTL_SERIAL_SET_DTR

Jika fungsi EvtSerCx2Control di driver pengontrol serial Anda mendukung permintaan IOCTL_SERIAL_SET_DTR , fungsi ini juga harus mendukung permintaan IOCTL_SERIAL_CLR_DTR , dan sebaliknya. Jika driver Anda tidak mendukung kedua permintaan ini, handler driver untuk permintaan IOCTL_SERIAL_GET_DTRRTS harus mengatur bit bendera SERIAL_DTR_STATE dalam nilai output untuk permintaan ini menjadi nol.

IOCTL_SERIAL_GET_DTRRTS

Fungsi EvtSerCx2Control di driver pengontrol serial Anda harus mendukung permintaan IOCTL_SERIAL_GET_DTRRTS , tetapi handler driver untuk permintaan ini diperlukan untuk hanya mendukung bit bendera SERIAL_RTS_STATE dalam nilai output untuk permintaan ini. Sebagai opsi, driver juga dapat mendukung bit bendera SERIAL_DTR_STATE. Jika bit bendera SERIAL_DTR_STATE tidak didukung, atur bit ini ke nol.

IOCTL_SERIAL_GET_COMMSTATUS

Fungsi EvtSerCx2Control di driver pengontrol serial Anda harus mendukung permintaan IOCTL_SERIAL_GET_COMMSTATUS , tetapi handler driver untuk permintaan ini diperlukan untuk hanya mendukung anggota berikut dari struktur SERIAL_STATUS yang digunakan oleh permintaan ini:

Kesalahan
HoldReasons

Sebagai opsi, driver juga dapat mendukung salah satu anggota lain dari struktur ini. Atur semua anggota yang tidak didukung ke nol.

IOCTL_SERIAL_GET_PROPERTIES

Fungsi EvtSerCx2Control di driver pengontrol serial Anda harus mendukung permintaan IOCTL_SERIAL_GET_PROPERTIES . Handler driver untuk permintaan ini harus mengatur anggota MaxBaud dari struktur SERIAL_COMMPROP yang digunakan oleh permintaan ini ke tingkat baud maksimum yang didukung, yang dinyatakan dalam bit per detik (bps). Misalnya, jika pengontrol seri mendukung tingkat baud maksimum 115.200 bps, driver menetapkan MaxBaud = 115200.

IOCTL_SERIAL_GET_MODEMSTATUS

Fungsi EvtSerCx2Control di driver pengontrol serial Anda harus mendukung permintaan IOCTL_SERIAL_GET_MODEMSTATUS . Handler driver untuk permintaan ini harus mengatur nilai output permintaan ke nilai register status modem mentah yang dibaca dari perangkat keras pengontrol serial.

IOCTL_SERIAL_GET_HANDFLOW dan IOCTL_SERIAL_SET_HANDFLOW

Fungsi EvtSerCx2Control di driver pengontrol serial Anda harus mendukung permintaan IOCTL_SERIAL_GET_HANDFLOW dan IOCTL_SERIAL_SET_HANDFLOW , tetapi diperlukan untuk hanya mendukung subset bit bendera yang ditentukan untuk permintaan ini. Bit bendera didefinisikan untuk anggota ControlHandShake dan FlowReplace dari struktur SERIAL_HANDFLOW yang digunakan oleh permintaan ini.

Driver Anda harus mendukung bit bendera berikut di anggota ControlHandshake :

SERIAL_CTS_HANDSHAKE

Sebagai opsi, driver dapat mendukung salah satu bit bendera lain yang ditentukan untuk anggota ControlHandshake .

Driver Anda harus mendukung bit bendera berikut di anggota FlowReplace :

SERIAL_RTS_CONTROL
SERIAL_RTS_HANDSHAKE

Sebagai opsi, driver dapat mendukung salah satu bit bendera lain yang ditentukan untuk anggota FlowReplace . Namun, bit bendera lainnya jarang, jika pernah, diperlukan, dan Microsoft merekomendasikan untuk tidak mendukungnya.

Driver yang tidak mendukung bit bendera tertentu di anggota ControlHandShake atau FlowReplace harus mengatur bit bendera ini ke nol dalam nilai output untuk permintaan IOCTL_SERIAL_GET_HANDFLOW . Jika permintaan IOCTL_SERIAL_SET_HANDFLOW menentukan bit bendera ControlHandshake atau FlowReplace yang tidak didukung driver, fungsi EvtSerCx2Control harus menggagalkan permintaan dan mengembalikan STATUS_INVALID_PARAMETER.

Sebagai opsi, driver dapat mendukung anggota XonLimit dan XoffLimit dari struktur SERIAL_HANDFLOW . Namun, anggota ini jarang, jika pernah, diperlukan, dan Microsoft merekomendasikan untuk tidak mendukung mereka. Driver yang tidak mendukung anggota XonLimit dan XoffLimit harus mengatur anggota ini ke nol dalam nilai output untuk permintaan IOCTL_SERIAL_GET_HANDFLOW . Jika permintaan IOCTL_SERIAL_SET_HANDFLOW menentukan anggota XonLimit atau XoffLimit nonzero dan driver tidak mendukung anggota ini, fungsi EvtSerCx2Control harus gagal dalam permintaan dan mengembalikan STATUS_NOT_IMPLEMENTED.

Contoh

Untuk menentukan fungsi panggilan balik EvtSerCx2Control , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. 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 EvtSerCx2Control yang diberi nama MyControl, gunakan jenis fungsi EVT_SERCX2_CONTROL , seperti yang ditunjukkan dalam contoh kode ini:

EVT_SERCX2_CONTROL  MyControl;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
NTSTATUS
  MyControl(
    WDFDEVICE  Device,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

Jenis fungsi EVT_SERCX2_CONTROL didefinisikan 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_CONTROL 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.