Kode Kontrol SIO_IDEAL_SEND_BACKLOG_CHANGE

Artikel
06/13/2023

Deskripsi

Kode kontrol SIO_IDEAL_SEND_BACKLOG_CHANGE memberi tahu aplikasi ketika nilai kirim backlog (ISB) yang ideal berubah untuk koneksi.

Untuk melakukan operasi ini, panggil fungsi WSAIoctl atau WSPIoctl dengan parameter berikut.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameter

s

Deskriptor yang mengidentifikasi soket.

dwIoControlCode

Kode kontrol untuk operasi. Gunakan SIO_IDEAL_SEND_BACKLOG_CHANGE untuk operasi ini.

lpvInBuffer

Penunjuk ke buffer input. Parameter ini tidak digunakan untuk operasi ini.

cbInBuffer

Ukuran, dalam byte, dari buffer input. Parameter ini tidak digunakan untuk operasi ini.

lpvOutBuffer

Penunjuk ke buffer output. Parameter ini tidak digunakan untuk operasi ini.

cbOutBuffer

Ukuran, dalam byte, dari buffer output. Parameter ini harus diatur ke nol.

lpcbBytesReturned

Penunjuk ke variabel yang menerima ukuran, dalam byte, dari data yang disimpan dalam buffer output. Parameter yang dikembalikan ini menunjuk ke nilai DWORD nol untuk operasi ini, karena tidak ada output.

lpvOverlapped

Penunjuk ke struktur WSAOVERLAPPED.

Jika soket dibuat tanpa atribut yang tumpang tindih, parameter lpOverlapped diabaikan.

Jika s dibuka dengan atribut yang tumpang tindih dan parameter lpOverlapped bukan NULL, operasi dilakukan sebagai operasi yang tumpang tindih (asinkron). Dalam hal ini, parameter lpOverlapped harus menunjuk ke struktur WSAOVERLAPPED yang valid.

Untuk operasi yang tumpang tindih, fungsi WSAIoctl atau WSPIoctl segera kembali, dan metode penyelesaian yang sesuai disinyalir ketika operasi telah selesai. Jika tidak, fungsi tidak kembali sampai operasi selesai atau terjadi kesalahan.

lpCompletionRoutine

Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi telah selesai (diabaikan untuk soket yang tidak tumpang tindih).

lpThreadId

Penunjuk ke struktur WSATHREADID yang akan digunakan oleh penyedia dalam panggilan berikutnya ke WPUQueueApc. Penyedia harus menyimpan struktur WSATHREADID yang direferensikan (bukan penunjuk ke yang sama) sampai setelah fungsi WPUQueueApc kembali.

Catatan Parameter ini hanya berlaku untuk fungsi WSPIoctl .

lpErrno

Penunjuk ke kode kesalahan.

Catatan Parameter ini hanya berlaku untuk fungsi WSPIoctl .

Nilai hasil

Jika operasi berhasil diselesaikan, fungsi WSAIoctl atau WSPIoctl mengembalikan nol.

Jika operasi gagal atau tertunda, fungsi WSAIoctl atau WSPIoctl mengembalikan SOCKET_ERROR. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi WSAGetLastError.

Kode kesalahan	Makna
WSA_IO_PENDING	Operasi tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED	Operasi tumpang tindih dibatalkan karena penutupan soket atau eksekusi perintah SIO_FLUSH IOCTL.
WSAEFAULT	Parameter lpOverlapped atau lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
WSAEINPROGRESS	Fungsi ini dipanggil ketika panggilan balik sedang berlangsung.
WSAEINTR	Operasi pemblokiran terganggu.
WSAEINVAL	Parameter dwIoControlCode bukan perintah yang valid, atau parameter input tertentu tidak dapat diterima, atau perintah tidak berlaku untuk jenis soket yang ditentukan. Kesalahan ini dikembalikan jika parameter cbOutBuffer bukan nol.
WSAENETDOWN	Subsistem jaringan gagal.
WSAENOPROTOOPT	Opsi soket tidak didukung pada protokol yang ditentukan.
WSAENOTCONN	Soket tidak tersambung.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Perintah IOCTL yang ditentukan tidak didukung. Kesalahan ini dikembalikan jika SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL tidak didukung oleh penyedia transportasi. Kesalahan ini juga dikembalikan ketika upaya untuk menggunakan SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL dibuat pada soket datagram.

Keterangan

IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE didukung pada Windows Server 2008, Windows Vista dengan Paket Layanan 1 (SP1), dan versi sistem operasi yang lebih baru.

Saat mengirim data melalui koneksi TCP menggunakan soket Windows, penting untuk menjaga jumlah data yang cukup terutang (dikirim tetapi belum diakui) di TCP untuk mencapai throughput tertinggi. Nilai ideal untuk jumlah data yang luar biasa untuk mencapai throughput terbaik untuk koneksi TCP disebut ukuran send backlog (ISB) yang ideal. Nilai ISB adalah fungsi dari produk penundaan bandwidth koneksi TCP dan jendela penerima yang diiklankan penerima (dan sebagian jumlah kemacetan dalam jaringan).

Nilai ISB per koneksi tersedia dari implementasi protokol TCP di Windows Server 2008, Windows Vista dengan SP1, dan versi sistem operasi yang lebih baru. IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE dapat digunakan oleh aplikasi untuk mendapatkan pemberitahuan ketika nilai ISB berubah secara dinamis untuk koneksi.

Pada Windows Server 2008, Windows Vista dengan SP1, dan versi sistem operasi yang lebih baru, IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE dan SIO_IDEAL_SEND_BACKLOG_QUERY didukung pada soket berorientasi aliran yang dalam keadaan tersambung.

Rentang untuk nilai ISB untuk koneksi TCP dapat secara teoritis bervariasi dari 0 hingga maksimum 16 megabyte.

Lihat halaman referensi IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY untuk penggunaan umum mekanisme ISB untuk mencapai throughput yang lebih baik melalui koneksi produk penundaan bandwidth tinggi.

IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE hanya diizinkan pada soket aliran yang berada dalam status terhubung. Jika tidak, fungsi WSAIoctl atau WSPIoctl akan gagal dengan WSAENOTCONN.

IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE tidak menggunakan buffer input atau output dan tertunda atau blok hingga perubahan ISB terjadi pada koneksi yang mendasar. Ketika IOCTL ini selesai, aplikasi Winsock dapat menggunakan SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL untuk mengambil nilai ISB baru pada koneksi.

IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE tidak mendukung mode non-pemblokiran. Aplikasi diizinkan untuk mengeluarkan IOCTL ini pada soket non-pemblokiran, tetapi IOCTL hanya akan memblokir atau menunggu hingga nilai ISB berubah.

Jika parameter lpOverlapped dan lpCompletionRoutine adalah NULL, soket dalam fungsi ini akan diperlakukan sebagai soket yang tidak tumpang tindih. Untuk parameter soket yang tidak tumpang tindih, lpOverlapped dan lpCompletionRoutine diabaikan, kecuali bahwa fungsi dapat memblokir jika soket dalam mode pemblokiran. Jika soket dalam mode non-pemblokiran, fungsi ini masih akan diblokir karena IOCTL khusus ini tidak mendukung mode non-pemblokiran.

Untuk soket yang tumpang tindih, operasi yang tidak dapat segera diselesaikan akan dimulai, dan penyelesaian akan ditunjukkan di lain waktu.

IOCTL apa pun dapat memblokir tanpa batas waktu, tergantung pada implementasi penyedia layanan. Jika aplikasi tidak dapat mentolerir pemblokiran dalam panggilan fungsi WSAIoctl atau WSPIoctl , I/O yang tumpang tindih akan disarankan untuk IOCTL yang sangat mungkin diblokir.

IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE menyediakan pemberitahuan dan diharapkan untuk memblokir atau menunggu hingga nilai ISB berubah. Jadi biasanya akan dipanggil secara asinkron dengan parameter lpOverlapped diatur ke struktur WSAOVERLAPPED yang valid.

IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE dapat gagal dengan WSAEINTR atau WSA_OPERATION_ABORTED dalam kasus berikut:

Koneksi TCP terputus dengan anggun dalam arah pengiriman. Ini dapat terjadi sebagai akibat dari panggilan ke fungsi matikan dengan bagaimana parameter diatur ke SD_SEND, panggilan ke fungsi DisconnectEx , atau panggilan ke fungsi TransmitFile atau TransmitPackets dengan parameter dwFlags diatur ke TF_DISCONNECT atau TF_REUSE.
Koneksi TCP telah direset atau dibatalkan.
Aplikasi mengeluarkan IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE ketika sudah ada permintaan pemberitahuan yang tertunda. Hanya satu permintaan SIO_IDEAL_SEND_BACKLOG_CHANGE yang tertunda yang diizinkan pada satu waktu.
Permintaan dibatalkan oleh Manajer I/O.
Soket ditutup.

Dua fungsi pembungkus sebaris untuk IOCTL ini didefinisikan dalam file header Ws2tcpip.h . Disarankan agar fungsi sebaris ini digunakan alih-alih menggunakan IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE dan SIO_IDEAL_SEND_BACKLOG_QUERY secara langsung.

Fungsi pembungkus sebaris untuk SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL adalah fungsi idealsendbacklognotify .

Fungsi pembungkus sebaris untuk SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL adalah fungsi idealsendbacklogquery .

Bagikan melalui