Fungsi WSAIoctl (winsock2.h)

  • Artikel

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_

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

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
WSA_IO_PENDING
 Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSAENETDOWN
 Subsistem jaringan gagal.
WSAEFAULT
 Parameter lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, atau lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid, atau parameter cbInBuffer atau cbOutBuffer terlalu kecil.
WSAEINVAL
 Parameter dwIoControlCode bukan perintah yang valid, atau parameter input tertentu tidak dapat diterima, atau perintah tidak berlaku untuk jenis soket yang ditentukan.
WSAEINPROGRESS
 Fungsi ini dipanggil ketika panggilan balik sedang berlangsung.
WSAENOTSOCK
 Deskriptor bukan soket.
WSAEOPNOTSUPP
 Perintah IOCTL yang ditentukan tidak dapat direalisasikan. (Misalnya, struktur FLOWSPEC yang ditentukan dalam SIO_SET_QOS atau SIO_SET_GROUP_QOS tidak dapat dipenuhi.)
WSAEWOULDBLOCK
 Soket ditandai sebagai non-pemblokiran dan operasi yang diminta akan memblokir.
WSAENOPROTOOPT
 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
 
Catatan Bit dalam parameter dwIoControlCode yang ditampilkan dalam tabel harus dibaca secara vertikal dari atas ke bawah menurut kolom. Jadi bit paling kiri adalah bit 31, bit berikutnya adalah bit 30, dan bit paling kanan adalah bit 0.
 
Saya diatur jika buffer input valid untuk kode, seperti halnya IOC_IN.

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.

Catatan Semua I/O yang dimulai oleh utas tertentu dibatalkan ketika utas tersebut keluar. Untuk soket yang tumpang tindih, operasi asinkron yang tertunda dapat gagal jika utas ditutup sebelum operasi selesai. Lihat ExitThread untuk informasi selengkapnya.
 
Jika lpCompletionRoutine bukan NULL, parameter hEvent diabaikan dan dapat digunakan oleh aplikasi untuk meneruskan informasi konteks ke rutinitas penyelesaian. Penelepon yang melewati lpCompletionRoutinenon-NULL dan kemudian memanggil WSAGetOverlappedResult untuk permintaan I/O yang tumpang tindih yang sama mungkin tidak mengatur parameter fWait untuk pemanggilan WSAGetOverlappedResult ke TRUE. Dalam hal ini, penggunaan parameter hEvent tidak terdefinisi, dan mencoba menunggu parameter hEvent akan menghasilkan hasil yang tidak dapat diprediksi.

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.
Catatan Beberapa kode IOCTL memerlukan file header tambahan. Misalnya, penggunaan SIO_RCVALL IOCTL memerlukan file header Mstcpip.h.
 
Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

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

Opsi Soket SOL_SOCKET

WSASocket

Fungsi Winsock

Referensi Winsock

getsockopt

ioctlsocket

setsockopt

soket