Fungsi WSAIoctl (winsock2.h)
Fungsi WSAIoctl mengontrol mode soket.
Sintaksis
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
[in] lpCompletionRoutine
Jenis: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Mengembalikan nilai
Setelah berhasil diselesaikan, WSAIoctl mengembalikan nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.
| Kode kesalahan | Arti |
|---|---|
| Operasi tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu. | |
|
Subsistem jaringan gagal. |
| lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, atau parameter lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian yang valid dari ruang alamat pengguna, 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 s bukan soket. |
|
Perintah IOCTL yang ditentukan tidak dapat direalisasikan. (Misalnya, struktur |
|
| Soket ditandai sebagai non-pemblokiran dan operasi yang diminta akan diblokir. | |
|
Opsi soket tidak didukung pada protokol yang ditentukan. Misalnya, upaya untuk menggunakan SIO_GET_BROADCAST_ADDRESS IOCTL dilakukan pada soket IPv6 atau upaya untuk menggunakan TCP SIO_KEEPALIVE_VALS IOCTL dibuat pada soket datagram. |
Komentar
Fungsi WSAIoctl
Jika lpOverlapped dan lpCompletionRoutineNULL, soket dalam fungsi ini akan diperlakukan sebagai soket yang tidak tumpang tindih. Untuk soket yang tidak tumpang tindih, parameter lpOverlapped dan lpCompletionRoutine diabaikan, yang menyebabkan fungsi bertingkah seperti fungsi ioctlsocket standar kecuali bahwa fungsi dapat memblokir jika soket s dalam mode pemblokiran. Jika soket s berada 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 kembali 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 WSAEventSelect)-based notification mechanism.
Untuk soket yang tumpang tindih, operasi yang tidak dapat segera diselesaikan akan dimulai, dan penyelesaian akan ditunjukkan di lain waktu. Nilai DWORD
IOCTL apa pun dapat memblokir tanpa batas waktu, tergantung pada implementasi penyedia layanan. Jika aplikasi tidak dapat mentolerir pemblokiran dalam panggilan WSAIoctl
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
#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
Dimungkinkan untuk mengadopsi skema pengodean yang mempertahankan ioctlsocket yang saat ini ditentukan opcode sambil menyediakan cara mudah untuk mempartisi ruang pengidentifikasi opcode sebanyak parameter dwIoControlCode sekarang menjadi entitas 32-bit. Parameter dwIoControlCode
| Saya | 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
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
Vendor/Keluarga alamat Kuantitas 11-bit yang menentukan vendor yang memiliki kode (jika T == 3) atau yang berisi keluarga alamat tempat kode diterapkan (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.
Code Kuantitas 16-bit yang berisi kode IOCTL tertentu untuk operasi.
Kode (perintah) Unix IOCTL berikut didukung.
Perintah Windows Sockets 2 berikut ini didukung.
Jika operasi yang tumpang tindih segera selesai,
Ketika dipanggil dengan soket yang tumpang tindih, parameter lpOverlapped harus valid selama durasi operasi yang tumpang tindih. Parameter
Jika parameter lpCompletionRoutine
Prototipe rutinitas penyelesaian adalah sebagai berikut:
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine
Parameter
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 pada Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Persyaratan
| Syarat | 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] |
| Platform Target |
Windows |
| Header |
winsock2.h |
| Pustaka |
Ws2_32.lib |
| DLL |
Ws2_32.dll |
Lihat juga
Opsi Soket
WSASocket
Referensi
setsockopt
soket