SIO_QUERY_TRANSPORT_SETTING控制項程式碼

發行項
06/13/2023

描述

SIO_QUERY_TRANSPORT_SETTING控制程式代碼會查詢通訊端上的傳輸設定。

若要執行這項作業，請使用下列參數呼叫 WSAIoctl 或 WSPIoctl 函 式。

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

參數

s

識別通訊端的描述項。

dwIoControlCode

作業的控制程式代碼。使用此作業 SIO_QUERY_TRANSPORT_SETTING 。

lpvInBuffer

輸入緩衝區的指標。此參數包含結構的指標，其中結構的第一個成員是 TRANSPORT_SETTING_ID 結構，可決定要查詢的傳輸設定。

cbInBuffer

輸入緩衝區的大小，以位元組為單位。此參數取決於要查詢的傳輸設定。

lpvOutBuffer

輸出緩衝區的指標。如果 lpOverlapped 和 lpCompletionRoutine 參數為 Null，此參數取決於要查詢的傳輸設定。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。

lmicrosoftBytesReturned

變數的指標，接收儲存在輸出緩衝區中的資料大小，以位元組為單位。

如果輸出緩衝區太小，則呼叫會失敗， WSAGetLastError 會傳回 WSAEINVAL，而 lBytesReturned 參數會指向 零的 DWORD 值。

如果lpOverlapped為Null，則成功呼叫時所傳回之lBytesReturned參數所指向的DWORD值不能為零。

如果重迭通訊端的 lpOverlapped 參數不是 Null ，則無法立即完成的作業將會起始，且稍後會指出完成。由傳回之lBytesReturned參數所指向的DWORD值可能是零，因為儲存的資料大小在重迭作業完成之前無法判斷。當作業完成完成時，可以擷取適當的完成方法時，擷取最終完成狀態。

lpvOverlapped

WSAOVERLAPPED結構的指標。

如果 建立的 通訊端沒有重迭屬性，則會忽略 lpOverlapped 參數。

如果已使用重迭屬性開啟，且 lpOverlapped 參數不是 Null，則會以重迭 (非同步) 作業來執行作業。在此情況下， lpOverlapped 參數必須指向有效的 WSAOVERLAPPED 結構。

對於重迭的作業， WSAIoctl 或 WSPIoctl 函式會立即傳回，並在作業完成時發出適當的完成方法訊號。否則，函式不會在作業完成或發生錯誤之前傳回。

lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

當作業完成時呼叫的完成常式指標， (忽略非重迭通訊端) 。

lpThreadId

提供者後續呼叫WPUQueueApc時要使用的WSATHREADID結構的指標。提供者應該儲存參考的 WSATHREADID 結構， (直到 WPUQueueApc 函式傳回之後，才儲存相同) 的指標。

注意此參數僅適用于 WSPIoctl 函 式。

lpErrno

錯誤碼的指標。

注意此參數僅適用于 WSPIoctl 函 式。

傳回值

如果作業順利完成， WSAIoctl 或 WSPIoctl 函式會傳回零。

如果作業失敗或擱置中， WSAIoctl 或 WSPIoctl 函式會 傳回SOCKET_ERROR。若要取得擴充的錯誤資訊，請呼叫 WSAGetLastError。

錯誤碼	意義
ERROR_INSUFFICIENT_BUFFER	傳遞至系統呼叫的資料區域太小。如果 lpvOutBuffer 參數指向的緩衝區與 cbOutBuffer 參數中傳遞的緩衝區大小太小，就會傳回此錯誤。所需的緩衝區大小將會在 lBytesReturned 參數中傳回。
WSA_IO_PENDING	已成功起始重迭的作業，且稍後將會指出完成。
WSA_OPERATION_ABORTED	因為通訊端關閉或 SIO_FLUSH IOCTL 命令的執行，所以取消重迭的作業。
WSAEFAULT	lpvOutBuffer、lHTTPBytesReturned、lpOverlapped或lpCompletionRoutine參數並未完全包含在使用者位址空間的有效部分中。
WSAEINPROGRESS	當回呼正在進行時，就會叫用函式。
WSAEINTR	封鎖作業已中斷。
WSAEINVAL	dwIoControlCode參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的通訊端類型。
WSAENETDOWN	網路子系統失敗。
WSAENOPROTOOPT	指定的通訊協定不支援通訊端選項。
WSAENOTCONN	通訊端未連接。
WSAENOTSOCK	描述項 s 不是通訊端。
WSAEOPNOTSUPP	不支援指定的 IOCTL 命令。如果傳輸提供者不支援 SIO_QUERY_TRANSPORT_SETTING IOCTL，則會傳回此錯誤。

備註

Windows 8和Windows Server 2012及更新版本的作業系統都支援SIO_QUERY_TRANSPORT_SETTING IOCTL。

SIO_QUERY_TRANSPORT_SETTING IOCTL 是一般 IOCTL，用來查詢通訊端上的傳輸設定。要查詢的傳輸設定是以lpvInBuffer參數中傳遞TRANSPORT_SETTING_ID為基礎。

目前唯一定義的傳輸設定是 TCP 通訊端上的 REAL_TIME_NOTIFICATION_CAPABILITY 功能。

如果傳入lpvInBuffer參數中的TRANSPORT_SETTING_ID已將 Guid 成員設定為REAL_TIME_NOTIFICATION_CAPABILITY，則這是查詢與 ControlChannelTrigger 搭配 ControlChannelTrigger在 Windows 市集應用程式中接收背景網路通知之 TCP 通訊端的即時通知設定的要求。 lpvInBuffer參數應該指向TRANSPORT_SETTING_ID結構。 lpvOutBuffer參數應該指向REAL_TIME_NOTIFICATION_SETTING_OUTPUT結構。此傳輸設定僅適用于 TCP 通訊端。此傳輸設定可讓 WinInet 或類似的網路服務查詢指定的 TCP 通訊端，以判斷 ControlChannelTrigger 狀態。 Windows 市集應用程式不會直接呼叫此 IOCTL。如果 WSAIoctl 或 WSPIoctl 呼叫成功，此 IOCTL 會傳回具有目前狀態 的REAL_TIME_NOTIFICATION_SETTING_OUTPUT 結構。