Kode Kontrol SIO_QUERY_TRANSPORT_SETTING

Artikel
06/12/2023

Deskripsi

Kode kontrol SIO_QUERY_TRANSPORT_SETTING mengkueri pengaturan transportasi pada soket.

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY_TRANSPORT_SETTING untuk operasi ini.

lpvInBuffer

Penunjuk ke buffer input. Parameter ini berisi penunjuk ke struktur di mana anggota pertama struktur adalah struktur TRANSPORT_SETTING_ID yang menentukan pengaturan transportasi apa yang sedang dikueri.

cbInBuffer

Ukuran, dalam byte, dari buffer input. Parameter ini tergantung pada pengaturan transportasi yang dikueri.

lpvOutBuffer

Penunjuk ke buffer output. Parameter ini tergantung pada pengaturan transportasi yang dikueri jika parameter lpOverlapped dan lpCompletionRoutine adalah NULL.

cbOutBuffer

Ukuran, dalam byte, dari buffer output.

lpcbBytesReturned

Penunjuk ke variabel yang menerima ukuran, dalam byte, dari data yang disimpan dalam buffer output.

Jika buffer output terlalu kecil, panggilan gagal, WSAGetLastError mengembalikan WSAEINVAL, dan parameter lpcbBytesReturned menunjuk ke nilai DWORD nol.

Jika lpOverlapped adalah NULL, nilai DWORD yang diarahkan oleh parameter lpcbBytesReturned yang dikembalikan pada panggilan yang berhasil tidak boleh nol.

Jika parameter lpOverlapped bukan NULL untuk soket yang tumpang tindih, operasi yang tidak dapat segera diselesaikan akan dimulai, dan penyelesaian akan ditunjukkan di lain waktu. Nilai DWORD yang ditunjukkan oleh parameter lpcbBytesReturned yang dikembalikan mungkin nol karena ukuran data yang disimpan tidak dapat ditentukan sampai operasi yang tumpang tindih selesai. Status penyelesaian akhir dapat diambil ketika metode penyelesaian yang sesuai disinyalir ketika operasi telah selesai.

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 kembali

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, panggil WSAGetLastError.

Kode kesalahan	Makna
ERROR_INSUFFICIENT_BUFFER	Area data yang diteruskan ke panggilan sistem terlalu kecil. Kesalahan ini dikembalikan jika buffer yang diarahkan oleh parameter lpvOutBuffer dengan ukuran buffer yang diteruskan dalam parameter cbOutBuffer terlalu kecil. Ukuran buffer yang diperlukan akan dikembalikan dalam parameter lpcbBytesReturned .
WSA_IO_PENDING	Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED	Operasi yang tumpang tindih dibatalkan karena penutupan soket atau eksekusi perintah SIO_FLUSH IOCTL.
WSAEFAULT	Parameter lpvOutBuffer, lpcbBytesReturned, 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.
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_QUERY_TRANSPORT_SETTING IOCTL tidak didukung oleh penyedia transportasi.

Keterangan

IOCTL SIO_QUERY_TRANSPORT_SETTING didukung pada Windows 8, dan Windows Server 2012, dan versi sistem operasi yang lebih baru.

IOCTL SIO_QUERY_TRANSPORT_SETTING adalah IOCTL generik yang digunakan untuk mengkueri pengaturan transportasi pada soket. Pengaturan transportasi yang sedang dikueri didasarkan pada TRANSPORT_SETTING_ID yang diteruskan dalam parameter lpvInBuffer .

Satu-satunya pengaturan transportasi yang saat ini ditentukan adalah untuk kemampuan REAL_TIME_NOTIFICATION_CAPABILITY pada soket TCP.

Jika TRANSPORT_SETTING_ID yang diteruskan dalam parameter lpvInBuffer memiliki anggota Guid yang diatur ke REAL_TIME_NOTIFICATION_CAPABILITY, maka ini adalah permintaan untuk mengkueri pengaturan pemberitahuan real time untuk soket TCP yang digunakan dengan ControlChannelTrigger untuk menerima pemberitahuan jaringan latar belakang di aplikasi Windows Store. Parameter lpvInBuffer harus menunjuk ke struktur TRANSPORT_SETTING_ID . Parameter lpvOutBuffer harus menunjuk ke struktur REAL_TIME_NOTIFICATION_SETTING_OUTPUT . Pengaturan transportasi ini hanya berlaku untuk soket TCP. Pengaturan transportasi ini menyediakan cara bagi WinInet atau layanan jaringan serupa untuk mengkueri soket TCP tertentu untuk menentukan status ControlChannelTrigger . Aplikasi Bursa Windows tidak akan memanggil IOCTL ini secara langsung. Jika panggilan WSAIoctl atau WSPIoctl berhasil, IOCTL ini mengembalikan struktur REAL_TIME_NOTIFICATION_SETTING_OUTPUT dengan status saat ini.

IOCTL SIO_QUERY_TRANSPORT_SETTING menyediakan cara bagi WinInet atau layanan jaringan serupa untuk meminta status pengaturan transportasi untuk soket TCP tertentu untuk menentukan apakah ControlChannelTrigger diaktifkan pada soket. Aplikasi Bursa Windows tidak akan memanggil IOCTL ini secara langsung.

IOCTL ini hanya berlaku untuk soket TCP.