SIO_KEEPALIVE_VALS控制項程式碼

發行項
06/13/2023

描述

SIO_KEEPALIVE_VALS控制項程式碼會啟用或停用 TCP keep-alive 選項的個別連線設定，指定 TCP 保持運作逾時和間隔。

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

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // 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_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // 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_KEEPALIVE_VALS 。

lpvInBuffer

輸入緩衝區的指標。此參數應該指向 tcp_keepalive 結構。

cbInBuffer

輸入緩衝區的大小，以位元組為單位。此參數應該等於或大於lpvInBuffer參數所指向之tcp_keepalive結構的大小。

lpvOutBuffer

輸出緩衝區的指標。這個作業未使用此參數。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。此參數必須設定為零。

lmicrosoftBytesReturned

變數的指標，接收儲存在輸出緩衝區中的資料大小，以位元組為單位。這個傳回的參數會指向此作業的 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。

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

備註

Windows 2000 和更新版本的作業系統支援 SIO_KEEPALIVE_VALS IOCTL。

SIO_KEEPALIVE_VALS控制程式代碼會啟用或停用 TCP keep-alive 選項的個別連線設定，指定 TCP keep-alive 逾時和 TCP keep-alive 封包所使用的間隔。如需 keep-alive 選項的詳細資訊，請參閱 IETF 網站上RFC 1122 中指定的通訊層需求一節 4.2.3.6。 (此資源只能以英文提供。)

lpvInBuffer參數應該指向Mstcpip.h標頭檔中定義的tcp_keepalive結構。此結構的定義如下：

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

onoff成員中指定的值會判斷 TCP 保持運作是否已啟用或停用。如果 onoff 成員設定為非零值，則會啟用 TCP keep-alive，並使用結構中的其他成員。 keepalivetime成員會指定逾時，以毫秒為單位，直到傳送第一個保持運作封包為止，沒有活動。 keepaliveinterval成員會指定在未收到通知時，在連續的保持運作封包之間，以毫秒為單位來指定間隔。

SO_KEEPALIVE選項是其中一個SOL_SOCKET通訊端選項，也可用來啟用或停用連線上的 TCP 保持運作，以及查詢此選項的目前狀態。若要查詢通訊端上是否啟用 TCP 保持運作，可以使用 SO_KEEPALIVE 選項呼叫 getsockopt 函式。若要啟用或停用 TCP 保持運作，可以使用SO_KEEPALIVE選項呼叫setsockopt函式。如果 tcp keep-alive 已啟用 SO_KEEPALIVE，則預設 TCP 設定會用於保持運作逾時和間隔，除非這些值已使用 SIO_KEEPALIVE_VALS變更。

keep-alive 逾時的預設全系統值可透過 KeepAliveTime 登錄設定來控制，以毫秒為單位的值。如果未設定金鑰，預設的保持運作逾時為 2 小時。 keep-alive 間隔的預設全系統值可透過 KeepAliveInterval 登錄設定來控制，以毫秒為單位的值。如果未設定索引鍵，預設的 keep-alive 間隔為 1 秒。

在 Windows Vista 和更新版本上， (資料重新傳輸) 的保留探查數目設定為 10 且無法變更。

在 Windows Server 2003、Windows XP 和 Windows 2000 上，保留探查數目的預設設定為 5。可透過 TcpMaxDataRetransmissions 和 PPTPTcpMaxDataRetransmissions 登錄設定來控制保持運作探查的數目。保持運作探查的數目會設定為兩個登錄機碼值中的較大值。如果此數位為 0，則不會傳送 keep-alive 探查。如果這個數位高於 255，則會調整為 255。