struktur SERIAL_TIMEOUTS (ntddser.h)

Artikel
08/07/2023

Struktur SERIAL_TIMEOUTS menentukan parameter waktu habis untuk operasi baca dan tulis oleh port serial.

Sintaks

typedef struct _SERIAL_TIMEOUTS {
  ULONG ReadIntervalTimeout;
  ULONG ReadTotalTimeoutMultiplier;
  ULONG ReadTotalTimeoutConstant;
  ULONG WriteTotalTimeoutMultiplier;
  ULONG WriteTotalTimeoutConstant;
} SERIAL_TIMEOUTS, *PSERIAL_TIMEOUTS;

Anggota

ReadIntervalTimeout

Jumlah waktu maksimum, dalam milidetik, yang diizinkan antara dua byte berturut-turut dalam operasi baca. Operasi baca yang melebihi batas waktu maksimum ini. Maksimum ini tidak berlaku untuk interval waktu yang mendahului pembacaan byte pertama. Nilai nol menunjukkan bahwa batas waktu interval tidak digunakan. Untuk informasi selengkapnya, lihat Keterangan.

ReadTotalTimeoutMultiplier

Jumlah waktu maksimum, dalam milidetik, yang diizinkan per byte dalam operasi baca. Operasi baca yang melebihi batas waktu maksimum ini. Untuk informasi selengkapnya, lihat Keterangan.

ReadTotalTimeoutConstant

Jumlah maksimum waktu tambahan, dalam milidetik, yang diizinkan per operasi baca. Operasi baca yang melebihi batas waktu maksimum ini. Untuk informasi selengkapnya, lihat Keterangan.

WriteTotalTimeoutMultiplier

Total waktu maksimum, dalam milidetik, yang diizinkan per byte dalam operasi tulis. Operasi tulis yang melebihi batas waktu maksimum ini. Untuk informasi selengkapnya, lihat Keterangan.

WriteTotalTimeoutConstant

Jumlah maksimum waktu tambahan, dalam milidetik, yang diizinkan per operasi tulis. Operasi tulis yang melebihi batas waktu maksimum ini. Untuk informasi selengkapnya, lihat Keterangan.

Keterangan

Struktur SERIAL_TIMEOUTS digunakan oleh permintaan kontrol I/O IOCTL_SERIAL_SET_TIMEOUTS dan IOCTL_SERIAL_GET_TIMEOUTS . Permintaan kontrol I/O IOCTL_SERIAL_SET_TIMEOUTS menggunakan struktur ini untuk menentukan serangkaian parameter waktu habis untuk port serial yang digunakan untuk operasi baca dan tulis. Permintaan kontrol I/O IOCTL_SERIAL_GET_TIMEOUTS menggunakan struktur ini untuk mengambil parameter waktu habis yang ditetapkan oleh permintaan IOCTL_SERIAL_SET_TIMEOUTS sebelumnya.

Permintaan baca atau tulis berhasil diselesaikan ketika jumlah byte yang ditentukan ditransfer atau waktu operasi baca atau tulis yang diminta habis. Permintaan mengembalikan kode status STATUS_SUCCESS untuk menunjukkan bahwa jumlah byte yang ditentukan telah ditransfer. Permintaan mengembalikan kode status STATUS_TIMEOUT untuk menunjukkan bahwa waktu operasi habis.

Jika permintaan IRP_MJ_READ menentukan operasi baca yang panjangnya Ntₒtₐl, jumlah waktu maksimum, Tmₐₓ, bahwa port seri memungkinkan operasi selesai dihitung sebagai berikut:

Tmₐₓ = Ntₒtₐl * ReadTotalTimeoutMultiplier + ReadTotalTimeoutConstant

Permintaan baca yang melebihi maksimum ini selesai ketika waktu habis terjadi, dan mengembalikan kode status STATUS_TIMEOUT. Bidang Informasi blok status I/O menunjukkan jumlah byte yang berhasil dibaca sebelum waktu habis terjadi.

Jika permintaan IRP_MJ_WRITE menentukan operasi tulis yang panjangnya Ntₒtₐl byte, jumlah waktu maksimum, Tmₐₓ, bahwa port seri memungkinkan operasi selesai dihitung sebagai berikut:

Tmₐₓ = Ntₒtₐl * WriteTotalTimeoutMultiplier + WriteTotalTimeoutConstant

Permintaan tulis yang melebihi maksimum ini selesai ketika waktu habis terjadi, dan mengembalikan kode status STATUS_TIMEOUT. Bidang Informasi blok status I/O menunjukkan jumlah byte yang berhasil ditulis sebelum waktu habis terjadi.

Waktu maksimum, Tmₐₓ, yang diizinkan untuk menyelesaikan operasi baca atau tulis selalu diukur dari ketika port serial memulai operasi yang diminta, dan bukan dari saat klien mengirimkan permintaan.

Jika ReadIntervalTimeout, ReadTotalTimeoutMultiplier, dan ReadTotalTimeoutConstant semuanya nol, operasi baca tidak pernah kehabisan waktu. Jika WriteTotalTimeoutMultiplier dan WriteTotalTimeoutConstant keduanya nol, operasi tulis tidak pernah kehabisan waktu.

Jika ReadIntervalTimeout adalah nol, tidak ada interval maksimum antara byte berturut-turut dalam operasi baca, dan waktu habis hanya didasarkan pada anggota ReadTotalTimeoutMultiplier dan ReadTotalTimeoutConstant .

Jika ReadTotalTimeoutMultiplier dan ReadTotalTimeoutConstant adalah nol, dan ReadIntervalTimeout kurang dari MAXULONG dan lebih besar dari nol, waktu operasi baca habis hanya jika interval antara sepasang byte yang diterima secara berturut-turut melebihi ReadIntervalTimeout. Jika ketiga nilai waktu habis ini digunakan, dan buffer input port serial kosong ketika permintaan baca dikirim ke port, permintaan ini tidak pernah kehabisan waktu sampai setelah port menerima setidaknya satu byte data baru.

Jika ReadIntervalTimeout diatur ke MAXULONG, dan ReadTotalTimeoutConstant dan ReadTotalTimeoutMultiplier adalah nol, permintaan baca segera selesai dengan byte yang telah diterima, bahkan jika tidak ada byte yang diterima. Dalam hal ini, permintaan baca mengembalikan kode status STATUS_SUCCESS.

Jika ReadIntervalTimeout dan ReadTotalTimeoutMultiplier diatur ke MAXULONG, dan ReadTotalTimeoutConstant diatur ke nilai yang lebih besar dari nol dan kurang dari MAXULONG, permintaan baca berperilaku sebagai berikut:

Jika ada byte dalam buffer input port serial, permintaan baca segera selesai dengan byte yang ada di buffer dan mengembalikan kode status STATUS_SUCCESS.
Jika tidak ada byte dalam buffer input, port serial menunggu hingga byte tiba, dan kemudian segera menyelesaikan permintaan baca dengan satu byte data dan mengembalikan kode status STATUS_SUCCESS.
Jika tidak ada byte yang tiba dalam waktu yang ditentukan oleh ReadTotalTimeoutConstant, waktu permintaan baca habis, mengatur bidang Informasi blok status I/O ke nol, dan mengembalikan kode status STATUS_TIMEOUT.

Permintaan IOCTL_SERIAL_SET_TIMEOUTS gagal dan mengembalikan kode status kesalahan INVALID_PARAMETER jika ReadIntervalTimeout dan ReadTotalTimeoutConstant keduanya diatur ke MAXULONG.

Batas waktu interval baca dapat digunakan untuk mendeteksi akhir aliran data masuk saat panjang aliran data tidak diketahui sebelumnya. Jika permintaan baca menggunakan teknik ini, kode status penyelesaian STATUS_TIMEOUT biasanya berarti bahwa permintaan berhasil diselesaikan.

Batas waktu interval baca terjadi ketika interval antara byte masuk melebihi nilai ReadIntervalTimeout . Interval waktu habis diukur relatif terhadap jam sistem, dan akurasi pengukuran waktu habis dibatasi oleh granularitas jam sistem. Akibatnya, waktu habis dapat terjadi antara satu jam sistem centang sebelumnya dan satu centang lebih lambat dari interval waktu habis yang ditentukan, tergantung pada di mana tepatnya waktu mulai dan akhir interval ini jatuh di antara jam sistem. Waktu habis mungkin terjadi bahkan nanti jika pemrosesan gangguan jam sistem tertunda oleh pemrosesan interupsi untuk perangkat lain. Jika interval waktu habis yang ditentukan mendekati atau lebih kecil dari periode antara jam sistem berdetak, waktu habis mungkin segera terjadi, tanpa penundaan.

Cara yang mungkin untuk mengukur interval waktu habis yang lebih kecil secara lebih akurat adalah dengan mengurangi waktu antara jam sistem, tetapi melakukannya kemungkinan akan meningkatkan konsumsi daya. Selain itu, mengurangi periode jam sistem mungkin tidak dapat mencapai granularitas jam sistem yang lebih halus kecuali pemrosesan terkait interupsi oleh berbagai driver dalam platform dapat dijamin untuk tidak menunda pemrosesan gangguan jam sistem.

Struktur SERIAL_TIMEOUTS mirip dengan struktur COMMTIMEOUTS , yang digunakan oleh fungsi SetCommTimeouts dan GetCommTimeouts mode pengguna.

Untuk informasi selengkapnya, lihat Mengatur Batas Waktu Baca dan Tulis untuk Perangkat Serial.