Kode Kontrol SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS

Artikel
06/12/2023

Deskripsi

Kode kontrol SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS mengambil rekaman pengalihan untuk koneksi TCP/IP yang diterima untuk digunakan oleh layanan pengalihan Windows Filtering Platform (WFP).

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // 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 WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

Parameter

s

Deskriptor yang mengidentifikasi soket.

dwIoControlCode

Kode kontrol untuk operasi. Gunakan SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS 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 harus menunjuk ke jenis data ULONG jika parameter lpOverlapped dan lpCompletionRoutine adalah NULL.

cbOutBuffer

Ukuran, dalam byte, dari buffer output. Parameter ini harus setidaknya ukuran jenis data ULONG .

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. Kesalahan ini dikembalikan jika parameter cbOutBuffer kurang dari ukuran jenis data ULONG .
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_WFP_CONNECTION_REDIRECT_RECORDS IOCTL tidak didukung oleh penyedia transportasi.

Keterangan

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

WFP memungkinkan akses ke jalur pemrosesan paket TCP/IP, di mana paket keluar dan masuk dapat diperiksa atau diubah sebelum memungkinkannya diproses lebih lanjut. Dengan memanfaatkan jalur pemrosesan TCP/IP, vendor perangkat lunak independen (ISV) dapat dengan lebih mudah membuat firewall, perangkat lunak antivirus, perangkat lunak diagnostik, dan jenis aplikasi dan layanan lainnya. WFP menyediakan komponen mode pengguna dan mode kernel sehingga ISV pihak ketiga dapat berpartisipasi dalam keputusan pemfilteran yang terjadi pada beberapa lapisan dalam tumpukan protokol TCP/IP dan di seluruh sistem operasi. Fitur pengalihan koneksi WFP memungkinkan driver kernel callout WFP untuk mengalihkan koneksi secara lokal ke proses mode pengguna, melakukan inspeksi konten dalam mode pengguna, dan meneruskan konten yang diperiksa menggunakan koneksi yang berbeda ke tujuan asli.

IOCTL SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS dan beberapa IOCTLS terkait lainnya adalah komponen mode pengguna yang digunakan untuk memungkinkan beberapa aplikasi proksi koneksi berbasis WFP memeriksa arus lalu lintas yang sama dengan cara yang kooperatif. Setiap agen inspeksi dapat dengan aman memeriksa kembali lalu lintas jaringan yang telah diperiksa oleh agen inspeksi lain. Dengan adanya beberapa proksi (dikembangkan oleh ISV yang berbeda, misalnya) koneksi yang digunakan oleh satu proksi untuk berkomunikasi dengan tujuan akhir pada gilirannya dapat dialihkan oleh proksi kedua, dan bahwa koneksi baru dapat kembali dialihkan oleh proksi asli. Tanpa pelacakan koneksi, koneksi asli mungkin tidak pernah mencapai tujuan akhirnya karena terjebak dalam perulangan proksi tak terbatas.

IOCTL SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS digunakan untuk menyediakan pelacakan koneksi yang diproksi pada koneksi soket yang dialihkan. Fitur WFP ini memfasilitasi pelacakan rekaman pengalihan dari pengalihan awal koneksi ke koneksi akhir ke tujuan.

IOCTL SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS digunakan oleh layanan pengalihan berbasis WFP untuk mengambil rekaman pengalihan dari koneksi paket TCP/IP yang diterima (soket yang terhubung untuk soket TCP atau soket UDP, misalnya) dialihkan ke dalamnya oleh callout mode kernel pendamping yang terdaftar di lapisan ALE_CONNECT_REDIRECT dalam driver mode kernel. IOCTL SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT digunakan oleh layanan pengalihan berbasis WFP untuk mengambil konteks pengalihan untuk rekaman pengalihan dari koneksi paket TCP/IP yang diterima (soket yang terhubung untuk soket TCP atau soket UDP, misalnya) dialihkan ke dalamnya oleh callout pendamping yang terdaftar di lapisan ALE_CONNECT_REDIRECT. Konteks pengalihan adalah konteks opsional yang dialokasikan driver yang digunakan jika status pengalihan koneksi saat ini adalah bahwa koneksi dialihkan oleh layanan pengalihan panggilan atau koneksi sebelumnya dialihkan oleh layanan pengalihan panggilan tetapi kemudian dialihkan lagi oleh layanan pengalihan yang berbeda. Untuk koneksi proksi TCP, layanan pengalihan mentransfer rekaman pengalihan yang diambil ke soket TCP yang digunakannya untuk memproksi konten asli menggunakan SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.

Ketika layanan pengalihan mengalihkan soket non-TCP (UDP, misalnya), rekaman pengalihan yang dikembalikan oleh SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL menunjukkan ini ke layanan pengalihan menggunakan struktur WSAMSG yang digunakan dengan fungsi LPFN_WSARECVMSG (WSARecvMsg ). Anggota kontrol struktur WSAMSG akan memiliki cmsg_type dalam struktur WSACMSGHDR yang diatur ke IP_CONNECTION_REDIRECT_RECORD. Parameter LPFN_WSARECVMSG (WSARecvMsg) harus disediakan oleh layanan pengalihan saat menerima pengalihan non-TCP.

Untuk lalu lintas non-TCP, catatan pengalihan diteruskan menggunakan struktur WSAMSG dengan fungsi WSASendMsg .

Perhatikan bahwa untuk lalu lintas non-TCP, hanya paket pembuatan alur yang akan membawa IP_CONNECTION_REDIRECT_RECORD. Akibatnya, hanya paket proksi pertama yang perlu menyertakan informasi ini menggunakan fungsi LPFN_WSARECVMSG (WSARecvMsg).

Karena rekaman pengalihan WFP adalah blob data panjang variabel, pemanggil dapat menyediakan buffer output besar (buffer 1.024 byte yang diarahkan oleh parameter lpvOutBuffer , misalnya) atau dapat meneruskan ukuran buffer output dalam parameter cbOutBuffer 0 untuk mengkueri ukuran buffer yang diperlukan untuk menahan blob yang dikembalikan. Jika ukuran buffer output tidak cukup untuk menahan data, fungsi WSAIoctl atau WSPIoctl akan mengembalikan ERROR_INSUFFICIENT_BUFFER dan ukuran buffer yang diperlukan akan dikembalikan dalam nilai yang ditunjukkan oleh parameter lpcbBytesReturned .

Aplikasi yang memanggil SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT tidak perlu memahami blob yang berisi konteks pengalihan yang diambil. Ini adalah blob data buram yang perlu diambil dan diteruskan kembali ke soket baru.