WSAIoctl 函式 (winsock2.h)

發行項
03/04/2024

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 來擷取特定的錯誤碼。

錯誤碼	意義
WSA_IO_PENDING	已成功起始重疊的作業，稍後將會指出完成。
WSAENETDOWN	網路子系統失敗。
WSAEFAULT	lpvInBuffer、lpvOutBuffer、lcbBytesReturned、lpOverlapped 或 lpCompletionRoutine 參數並未完全包含在用戶位址空間的有效部分，或 cbInBuffer 或 cbOutBuffer 參數太小。
WSAEINVAL	dwIoControlCode 參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的套接字類型。
WSAEINPROGRESS	當回呼正在進行時，會叫用函式。
WSAENOTSOCK	描述項 s 不是套接字。
WSAEOPNOTSUPP	無法實現指定的 IOCTL 命令。 (例如，無法滿足SIO_SET_QOS或SIO_SET_GROUP_QOS中指定的 FLOWSPEC 結構。)
WSAEWOULDBLOCK	套接字標示為非封鎖，而且要求的作業會封鎖。
WSAENOPROTOOPT	指定的通訊協定不支援套接字選項。例如，嘗試在 IPv6 套接字上使用 SIO_GET_BROADCAST_ADDRESS IOCTL，或在數據報套接字上嘗試使用 TCP SIO_KEEPALIVE_VALS IOCTL。

備註

WSAIoctl 函式可用來設定或擷取與套接字、傳輸通訊協定或通訊子系統相關聯的作業參數。

如果 lpOverlapped 和 lpCompletionRoutine 都是 NULL，此函式中的套接字將會被視為非重疊的套接字。對於非重疊的套接字， 會忽略 lpOverlapped 和 lpCompletionRoutine 參數，這會導致函式的行為就像標準 ioctlsocket 函式一樣，不同之處在於，如果套接字處於封鎖模式，函式可以封鎖。如果套接字處於非封鎖模式，當無法立即完成指定的作業時，此函式可以傳回 WSAEWOULDBLOCK。在此情況下，應用程式可能會將套接字變更為封鎖模式，並在使用 WSAEventSel () ect) ) 型通知機制時，重新發出要求或等候對應的網路事件 (，例如 () SIO_ADDRESS_LIST_CHANGESIO_ROUTING_INTERFACE_CHANGE FD_ROUTING_INTERFACE_CHANGE或FD_ADDRESS_LIST_CHANGE。

對於重疊的套接字，無法立即完成的作業將會起始，而且稍後會指出完成。可能會忽略傳回之 lmicrosoftBytesReturned 參數所指向的 DWORD 值。當作業完成時，可以擷取傳回的最終完成狀態和位元組。

根據服務提供者的實作而定，任何 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 opcode，同時提供方便的方式來分割 dwIoControlCode 參數中的 opcode 標識符空間，現在是 32 位實體。 dwIoControlCode 參數是建置，以在新增控制程式代碼時允許通訊協定和廠商獨立，同時保留與 Windows Sockets 1.1 和 Unix 控件代碼的回溯相容性。 dwIoControlCode 參數的格式如下。

I	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

注意數據表中顯示的 dwIoControlCode 參數位必須依數據行從上到下垂直讀取。因此，最左邊的位是位 31，下一個位是位 30，而最右邊的位是位 0。

如果輸入緩衝區對程序代碼有效，則設定為與 IOC_IN相同。

如果輸出緩衝區對程序代碼有效，則設定 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，進而提供廠商的彈性和隱私權。

廠商/位址系列 11 位數量，定義如果 T == 3) 或包含程式代碼套用 (的位址系列，則為 T == 2) ，則定義擁有程式代碼 (廠商。如果這是 Unix IOCTL 程式代碼 (T == 0) ，則此參數的值與 Unix 上的程式碼相同。如果這是一般 Windows Sockets 2 IOCTL (T == 1) 則此參數可作為程式代碼參數的延伸模組，以提供額外的程式代碼值。

代碼包含作業特定 IOCTL 程式代碼的 16 位數量。

支援下列 Unix IOCTL 代碼 (命令) 。

支援下列 Windows Sockets 2 命令。

如果重疊的作業立即完成， WSAIoctl 會傳回零的值，且 lkbBytesReturned 參數會以輸出緩衝區中的位元元組數目更新。如果已成功起始重疊的作業，且稍後會完成，此函式會傳回SOCKET_ERROR，並指出錯誤碼 WSA_IO_PENDING。在此案例中， lHTTPBytesReturned 不會更新。當重疊的作業完成時，輸出緩衝區中的數據量會透過完成例程中的 cbTransferred 參數指示， (如果指定) ，或透過 WSAGetOverlappedResult 中的lTransfer 參數。

使用重疊的套接字呼叫時， lpOverlapped 參數在重疊作業期間必須有效。 lpOverlapped 參數包含 WSAOVERLAPPED 結構的位址。

如果 lpCompletionRoutine 參數為 NULL，當重疊的作業包含有效的事件物件句柄時，lpOverlapped 的 hEvent 參數會發出訊號。應用程式可以使用 WSAWaitForMultipleEvents 或 WSAGetOverlappedResult 來等候或輪詢事件物件。

注意當該線程結束時，指定的線程所起始的所有 I/O 都會取消。對於重疊的套接字，如果線程在作業完成之前關閉，擱置的異步操作可能會失敗。如需詳細資訊，請參閱 ExitThread 。

如果 lpCompletionRoutine 不是 NULL， 則會忽略 hEvent 參數，而且可由應用程式用來將內容資訊傳遞至完成例程。將非 NULLlpCompletionRoutine 和更新版本針對相同重疊 I/O 要求的 WSAGetOverlappedResult 呼叫 WSAGetOverlappedResult 的呼叫端，可能不會將該 WSAGetOverlappedResult 叫用的 fWait 參數設定為 TRUE。在此情況下， 未定義 hEvent 參數的使用方式，而嘗試等候 hEvent 參數會產生無法預期的結果。

完成例程的原型如下所示：


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 代碼是一部分的 IOCTL 程式代碼，用於套接字。特別是沒有相當於 FIOASYNC 的命令。

注意某些 IOCTL 程式代碼需要其他頭檔。例如，使用 SIO_RCVALL IOCTL 需要 Mstcpip.h 頭檔。

Windows Phone 8：Windows Phone 8 和更新版本上 Windows Phone 市集應用程式支援此函式。

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 應用程式]
目標平台	Windows
標頭	winsock2.h
程式庫	Ws2_32.lib
Dll	Ws2_32.dll