Fungsi WSAIoctl (winsock2.h)
Fungsi WSAIoctl mengontrol mode soket.
Sintaks
int WSAAPI WSAIoctl(
[in] SOCKET s,
[in] DWORD dwIoControlCode,
[in] LPVOID lpvInBuffer,
[in] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Parameter
[in] s
Deskriptor yang mengidentifikasi soket.
[in] dwIoControlCode
Kode kontrol operasi yang akan dilakukan. Lihat Winsock IOCTLs.
[in] lpvInBuffer
Penunjuk ke buffer input.
[in] cbInBuffer
Ukuran, dalam byte, dari buffer input.
[out] lpvOutBuffer
Penunjuk ke buffer output.
[in] cbOutBuffer
Ukuran, dalam byte, dari buffer output.
[out] lpcbBytesReturned
Penunjuk ke jumlah aktual byte output.
[in] lpOverlapped
Penunjuk ke struktur WSAOVERLAPPED (diabaikan untuk soket yang tidak tumpang tindih).
[in] lpCompletionRoutine
Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_
Nilai kembali
Setelah berhasil diselesaikan, WSAIoctl mengembalikan nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.
Kode kesalahan | Makna |
---|---|
Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu. | |
Subsistem jaringan gagal. | |
Parameter lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, atau lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid, atau parameter cbInBuffer atau cbOutBuffer terlalu kecil. | |
Parameter dwIoControlCode bukan perintah yang valid, atau parameter input tertentu tidak dapat diterima, atau perintah tidak berlaku untuk jenis soket yang ditentukan. | |
Fungsi ini dipanggil ketika panggilan balik sedang berlangsung. | |
Deskriptor bukan soket. | |
Perintah IOCTL yang ditentukan tidak dapat direalisasikan. (Misalnya, struktur FLOWSPEC yang ditentukan dalam SIO_SET_QOS atau SIO_SET_GROUP_QOS tidak dapat dipenuhi.) | |
Soket ditandai sebagai non-pemblokiran dan operasi yang diminta akan memblokir. | |
Opsi soket tidak didukung pada protokol yang ditentukan. Misalnya, upaya untuk menggunakan SIO_GET_BROADCAST_ADDRESS IOCTL dibuat pada soket IPv6 atau upaya untuk menggunakan TCP SIO_KEEPALIVE_VALS IOCTL dibuat pada soket datagram. |
Keterangan
Fungsi WSAIoctl digunakan untuk mengatur atau mengambil parameter operasi yang terkait dengan soket, protokol transportasi, atau subsistem komunikasi.
Jika lpOverlapped dan lpCompletionRoutineADALAH NULL, soket dalam fungsi ini akan diperlakukan sebagai soket yang tidak tumpang tindih. Untuk parameter soket yang tidak tumpang tindih, lpOverlapped dan lpCompletionRoutine diabaikan, yang menyebabkan fungsi bertingkah seperti fungsi ioctlsocket standar kecuali bahwa fungsi dapat memblokir jika soket dalam mode pemblokiran. Jika soket dalam mode non-pemblokiran, fungsi ini dapat mengembalikan WSAEWOULDBLOCK ketika operasi yang ditentukan tidak dapat segera diselesaikan. Dalam hal ini, aplikasi dapat mengubah soket ke mode pemblokiran dan menerbitkan ulang permintaan atau menunggu peristiwa jaringan yang sesuai (seperti FD_ROUTING_INTERFACE_CHANGE atau FD_ADDRESS_LIST_CHANGE dalam kasus SIO_ROUTING_INTERFACE_CHANGE atau SIO_ADDRESS_LIST_CHANGE) menggunakan pesan Windows (menggunakan WSAAsyncSelect) berbasis atau peristiwa (menggunakan mekanisme pemberitahuan berbasis WSAEventSelect).
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 dapat diabaikan. Status penyelesaian akhir dan byte yang dikembalikan dapat diambil ketika metode penyelesaian yang sesuai disinyalir ketika operasi telah selesai.
IOCTL apa pun dapat memblokir tanpa batas waktu, tergantung pada implementasi penyedia layanan. Jika aplikasi tidak dapat mentolerir pemblokiran dalam panggilan WSAIoctl , I/O yang tumpang tindih akan disarankan untuk IOCTL yang sangat mungkin diblokir termasuk:
SIO_ADDRESS_LIST_CHANGE
SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_SET_QOS
SIO_SET_GROUP_QOS
Beberapa IOCTL khusus protokol mungkin juga sangat mungkin diblokir. Periksa lampiran khusus protokol yang relevan untuk informasi apa pun yang tersedia.
Prototipe untuk rutinitas penyelesaian yang diarahkan oleh parameter lpCompletionRoutine adalah sebagai berikut:
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
void CALLBACK CompletionRoutine (
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine adalah tempat penampung untuk nama fungsi yang disediakan aplikasi. Parameter dwError menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh parameter lpOverlapped . Parameter cbTransferred menentukan jumlah byte yang diterima. Parameter dwFlags tidak digunakan untuk IOCTL ini. Rutinitas penyelesaian tidak mengembalikan nilai.
Dimungkinkan untuk mengadopsi skema pengodean yang mempertahankan opcode ioctlsocket yang saat ini ditentukan sambil menyediakan cara yang mudah untuk mempartisi ruang pengidentifikasi opcode di sebanyak parameter dwIoControlCode sekarang menjadi entitas 32-bit. Parameter dwIoControlCode dibangun untuk memungkinkan protokol dan kemandirian vendor saat menambahkan kode kontrol baru sambil mempertahankan kompatibilitas mundur dengan kode kontrol Windows Sockets 1.1 dan Unix. Parameter dwIoControlCode memiliki formulir berikut.
I | O | V | T | Vendor/keluarga alamat | Kode |
---|---|---|---|---|---|
3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
O diatur jika buffer output valid untuk kode, seperti halnya IOC_OUT. Kode kontrol menggunakan buffer input dan output mengatur I dan O.
V diatur jika tidak ada parameter untuk kode, seperti halnya IOC_VOID.
T adalah kuantitas 2-bit yang menentukan jenis IOCTL. Nilai berikut didefinisikan:
0 IOCTL adalah kode IOCTL Unix standar, seperti halnya FIONREAD dan FIONBIO.
1 IOCTL adalah kode IOCTL Windows Sockets 2 generik. Kode IOCTL baru yang ditentukan untuk Windows Sockets 2 akan memiliki T == 1.
2 IOCTL hanya berlaku untuk keluarga alamat tertentu.
3 IOCTL hanya berlaku untuk penyedia vendor tertentu, seperti halnya IOC_VENDOR. Jenis ini memungkinkan perusahaan diberi nomor vendor yang muncul di parameter keluarga Vendor/Alamat . Kemudian, vendor dapat menentukan IOCTL baru khusus untuk vendor tersebut tanpa harus mendaftarkan IOCTL dengan clearinghouse, sehingga memberikan fleksibilitas dan privasi vendor.
Vendor/Keluarga alamat Kuantitas 11-bit yang mendefinisikan vendor yang memiliki kode (jika T == 3) atau yang berisi keluarga alamat yang diterapkan kode (jika T == 2). Jika ini adalah kode Unix IOCTL (T == 0) maka parameter ini memiliki nilai yang sama dengan kode pada Unix. Jika ini adalah Windows Sockets 2 IOCTL generik (T == 1) maka parameter ini dapat digunakan sebagai ekstensi parameter kode untuk memberikan nilai kode tambahan.
Kode Kuantitas 16-bit yang berisi kode IOCTL tertentu untuk operasi.
Kode (perintah) IOCTL Unix berikut didukung.
Perintah Windows Sockets 2 berikut ini didukung.
Jika operasi yang tumpang tindih segera selesai, WSAIoctl mengembalikan nilai nol dan parameter lpcbBytesReturned diperbarui dengan jumlah byte dalam buffer output. Jika operasi yang tumpang tindih berhasil dimulai dan akan selesai nanti, fungsi ini mengembalikan SOCKET_ERROR dan menunjukkan kode kesalahan WSA_IO_PENDING. Dalam hal ini, lpcbBytesReturned tidak diperbarui. Ketika operasi yang tumpang tindih menyelesaikan jumlah data dalam buffer output ditunjukkan baik melalui parameter cbTransferred dalam rutinitas penyelesaian (jika ditentukan), atau melalui parameter lpcbTransfer di WSAGetOverlappedResult.
Ketika dipanggil dengan soket yang tumpang tindih, parameter lpOverlapped harus valid selama operasi yang tumpang tindih. Parameter lpOverlapped berisi alamat struktur WSAOVERLAPPED .
Jika parameter lpCompletionRoutine adalah NULL, parameter hEventdari lpOverlapped diberi sinyal ketika operasi yang tumpang tindih selesai jika berisi handel objek peristiwa yang valid. Aplikasi dapat menggunakan WSAWaitForMultipleEvents atau WSAGetOverlappedResult untuk menunggu atau melakukan polling pada objek peristiwa.
Prototipe rutinitas penyelesaian adalah sebagai berikut:
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine ini adalah tempat penampung untuk fungsi yang ditentukan aplikasi atau yang ditentukan pustaka. Rutinitas penyelesaian dipanggil hanya jika utas dalam keadaan dapat diperingatkan. Untuk menempatkan utas ke dalam status yang dapat diperingatkan, gunakan fungsi WSAWaitForMultipleEvents, WaitForSingleObjectEx, atau WaitForMultipleObjectsEx dengan parameter fAlertable atau bAlertable diatur ke TRUE.
Parameter dwErrordari CompletionRoutine menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh lpOverlapped. Parameter cbTransferred menentukan jumlah byte yang dikembalikan. Saat ini, tidak ada nilai bendera yang ditentukan dan dwFlags akan menjadi nol. Fungsi CompletionRoutine tidak mengembalikan nilai.
Mengembalikan dari fungsi ini memungkinkan pemanggilan rutinitas penyelesaian lain yang tertunda untuk soket ini. Rutinitas penyelesaian dapat dipanggil dalam urutan apa pun, tidak harus dalam urutan yang sama operasi yang tumpang tindih selesai.
Kompatibilitas
Kode IOCTL dengan T == 0 adalah subset dari kode IOCTL yang digunakan dalam soket Berkeley. Secara khusus, tidak ada perintah yang setara dengan FIOASYNC.Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
Target Platform | Windows |
Header | winsock2.h |
Pustaka | Ws2_32.lib |
DLL | Ws2_32.dll |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk