WSAIoctl 函式 （winsock2.h）
WSAIoctl 函式會控制套接字的模式。
語法
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
);
參數
[in] s
識別套接字的描述項。
[in] dwIoControlCode
要執行的作業控制程式碼。 請參閱 Winsock IOCTLs。
[in] lpvInBuffer
輸入緩衝區的指標。
[in] cbInBuffer
輸入緩衝區的大小，以位元組為單位。
[out] lpvOutBuffer
輸出緩衝區的指標。
[in] cbOutBuffer
輸出緩衝區的大小，以位元組為單位。
[out] lpcbBytesReturned
輸出實際位元組數目的指標。
[in] lpOverlapped
WSAOVERLAPPED 結構的指標（針對非重疊套接字忽略）。
[in] lpCompletionRoutine
類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
傳回值
成功完成時，WSAIoctl 會傳回零。 否則，會傳回 SOCKET_ERROR 的值，而且可以呼叫 WSAGetLastError擷取特定的錯誤碼。
| 錯誤碼 | 意義 |
|---|---|
| 已成功起始重疊的作業，稍後將會指出完成。 | |
| 網路子系統失敗。 | |
| lpvInBuffer、lpvOutBuffer、l、lpOverlapped或 lpCompletionRoutine 參數未完全包含在使用者地址空間的有效部分中， 或 cbInBuffer 或 cbOutBuffer 參數太小。 | |
| dwIoControlCode 參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的套接字類型。 | |
| 當回呼正在進行時，會叫用函式。 | |
| 描述項 s 不是套接字。 | |
| 無法實現指定的 IOCTL 命令。 （例如，無法滿足 SIO_SET_QOS 或 SIO_SET_GROUP_QOS 中指定的 FLOWSPEC 結構。 | |
| 套接字會標示為非封鎖，且要求的作業會封鎖。 | |
| 指定的通訊協定不支援套接字選項。 例如，嘗試在 IPv6 套接字上使用 SIO_GET_BROADCAST_ADDRESS IOCTL，或在數據報套接字上嘗試使用 TCP SIO_KEEPALIVE_VALS IOCTL。 |
言論
WSAIoctl 函式可用來設定或擷取與套接字、傳輸通訊協定或通訊子系統相關聯的作業參數。
如果 lpOverlapped 和 lpCompletionRoutine 都 NULL，則此函式中的套接字將會被視為非重疊的套接字。 對於非重疊的套接字，lpOverlapped 和 lpCompletionRoutine 參數會被忽略，這會導致函式的行為就像標準 ioctlsocket 函式，不同之處在於如果套接字 處於封鎖模式，函式可以封鎖。 如果套接字 處於非封鎖模式，當無法立即完成指定的作業時，此函式可以傳回 WSAEWOULDBLOCK。 在此情況下，應用程式可能會將套接字變更為封鎖模式，然後重新發出要求，或等候對應網路事件（例如 FD_ROUTING_INTERFACE_CHANGE，SIO_ROUTING_INTERFACE_CHANGE 或 SIO_ADDRESS_LIST_CHANGE時FD_ADDRESS_LIST_CHANGE）使用 Windows 訊息（使用 WSAAsyncSelect）型或事件（使用 WSAEventSelect）型通知機制。
對於重疊的套接字，無法立即完成的作業將會起始，稍後將會指出完成。
根據服務提供者的實作而定，任何 IOCTL 都可能會無限期地封鎖。 如果應用程式無法容許在 WSAIoctl 呼叫中封鎖，則特別可能封鎖的 IOCTL 會建議重疊的 I/O，包括：
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
某些通訊協定特定的 IOCTL 也可能特別可能遭到封鎖。 請查看相關的通訊協定特定附件，以取得任何可用資訊。
lpCompletionRoutine 參數所指向之完成例程的原型如下所示：
#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 是應用程式提供函式名稱的佔位符。 dwError 參數會指定重迭作業的完成狀態，如 lpOverlapped 參數所指示。 cbTransferred 參數會指定接收的位元元組數目。 dwFlags 參數不會用於這個 IOCTL。 完成例程不會傳回值。
可以採用編碼配置，以保留目前定義的 ioctlsocket opcodes，同時提供方便的方式，將 opcode 標識符空間分割在 dwIoControlCode 參數中，現在是 32 位實體。 dwIoControlCode 參數是建置，以在新增新的控制碼時允許通訊協定和廠商獨立，同時保留與 Windows Sockets 1.1 和 Unix 控件碼的回溯相容性。 dwIoControlCode 參數的格式如下。
| 我 | O | V | T | 廠商/位址系列 | 法典 |
|---|---|---|---|---|---|
| 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，如同 IOC_OUT。 使用輸入和輸出緩衝區控制程式代碼會同時設定 I 和 O。
如果沒有程式代碼的參數，則會設定 V，如同 IOC_VOID。
T 是定義 IOCTL 類型的 2 位數量。 定義下列值：
0 IOCTL 是標準的 Unix IOCTL 程式代碼，與 FIONREAD 和 FIONBIO一樣。
1 IOCTL 是一般 Windows Sockets 2 IOCTL 程式代碼。 針對 Windows Sockets 2 定義的新 IOCTL 代碼將會有 T == 1。
2 IOCTL 僅適用於特定位址系列。
3 IOCTL 僅適用於特定廠商的提供者，如同 IOC_VENDOR。 此類型可讓公司獲派廠商號碼，該號碼會出現在 Vendor/Address 系列 參數中。 然後，廠商可以定義該廠商特有的新 IOCTL，而不必向清算所註冊 IOCTL，從而提供廠商的彈性和隱私權。
Vendor/Address 系列 一個 11 位數量，定義擁有程式碼的廠商（如果 T == 3），或包含程式代碼套用的位址系列（如果 T == 2）。 如果這是 Unix IOCTL 程式代碼 （T == 0），則此參數的值與 Unix 上的程式代碼相同。 如果這是一般 Windows Sockets 2 IOCTL （T == 1），則可以使用此參數做為程式代碼參數的延伸模組，以提供額外的程式代碼值。
Code 包含作業特定 IOCTL 程式代碼的 16 位數量。
支援下列 Unix IOCTL 程式代碼（命令）。
支援下列 Windows Sockets 2 命令。
如果重疊的作業立即完成，WSAIoctl 會傳回零的值，且 l 參數會更新輸出緩衝區中的位元元組數。 如果重疊的作業已成功起始且稍後會完成，此函式會傳回SOCKET_ERROR，並指出錯誤碼 WSA_IO_PENDING。 在此情況下，ltesReturned 不會更新。 當重疊作業完成輸出緩衝區中的數據量時，會透過完成例程中的 cbTransferred 參數來表示，或透過 WSAGetOverlappedResult中的 lcbTransfer 參數。
使用重疊的套接字呼叫時，lpOverlapped 參數在重迭作業期間必須有效。 lpOverlapped 參數包含 WSAOVERLAPPED 結構的位址。
如果 lpCompletionRoutine 參數 NULL，則當重疊作業包含有效事件物件句柄時，lpOverlapped 的 hEvent 參數會發出訊號。 應用程式可以使用 WSAWaitForMultipleEvents 或 WSAGetOverlappedResult 等候或輪詢事件物件。
完成例程的原型如下所示：
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
這個 CompletionRoutine 是應用程式定義或連結庫定義函式的佔位元。 只有在線程處於可警示狀態時，才會叫用完成例程。 若要將線程置於可警示的狀態， 使用 WSAWaitForMultipleEvents、WaitForSingleObjectEx或 WaitForMultipleObjectsEx 函式搭配 fAlertable 或 bAlertable 参数設定為 TRUE。
CompletionRoutine dwError 參數 會指定重迭作業的完成狀態，如 lpOverlapped所指示。 cbTransferred 參數會指定傳回的位元組數目。 目前未定義旗標值，dwFlags 為零。 CompletionRoutine 函式不會傳回值。
從此函式傳回允許叫用此套接字的另一個擱置完成例程。 完成例程可以依任何順序呼叫，不一定以相同順序完成重疊的作業。
相容性
具有 T == 0 的 IOCTL 程式代碼是 Berkeley 套接字中使用的 IOCTL 程式代碼子集。 特別是沒有相當於 FIOASYNC的命令。Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 和更新版本上支援 Windows 市集應用程式。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | winsock2.h |
| 連結庫 | Ws2_32.lib |
| DLL | Ws2_32.dll |