SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS控制項程式碼

發行項
06/13/2023

描述

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS控制程式代碼會擷取已接受 TCP/IP 連線的重新導向記錄，以供 WINDOWS 篩選平臺 (一次) 重新導向服務使用。

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // 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 WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

參數

s

識別通訊端的描述項。

dwIoControlCode

作業的控制程式代碼。針對此作業使用 SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS 。

lpvInBuffer

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

cbInBuffer

輸入緩衝區的大小，以位元組為單位。這個作業未使用此參數。

lpvOutBuffer

輸出緩衝區的指標。如果lpOverlapped和lpCompletionRoutine參數為Null，此參數應該指向ULONG資料類型。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。此參數必須至少是 ULONG 資料類型的大小。

lBytesReturned

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

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

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

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

lpvOverlapped

WSAOVERLAPPED結構的指標。

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

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

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

lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

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

lpThreadId

WSATHREADID結構的指標，供提供者在後續呼叫WPUQueueApc時使用。提供者應該儲存參考的 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、lmicrosoftBytesReturned、lpOverlapped或lpCompletionRoutine參數並未完全包含在使用者位址空間的有效部分。
WSAEINPROGRESS	當回呼正在進行時，會叫用函式。
WSAEINTR	封鎖作業已中斷。
WSAEINVAL	dwIoControlCode參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的通訊端類型。如果 cbOutBuffer 參數小於 ULONG 資料類型的大小，就會傳回此錯誤。
WSAENETDOWN	網路子系統失敗。
WSAENOPROTOOPT	指定的通訊協定不支援通訊端選項。
WSAENOTCONN	通訊端未連線。
WSAENOTSOCK	描述項 s 不是通訊端。
WSAEOPNOTSUPP	不支援指定的 IOCTL 命令。如果傳輸提供者不支援 SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL，就會傳回此錯誤。

備註

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

其允許存取 TCP/IP 封包處理路徑，其中可以檢查或變更傳入封包，再進一步處理這些封包。藉由點選 TCP/IP 處理路徑，獨立軟體廠商 (ISV) 可以更輕鬆地建立防火牆、防毒軟體、診斷軟體，以及其他類型的應用程式和服務。其提供使用者模式和核心模式元件，讓協力廠商 ISV 可以參與在 TCP/IP 通訊協定堆疊和整個作業系統中數層發生的篩選決策。「計畫」連線重新導向功能可讓一個與原始目的地不同的連線，將連線重新導向至使用者模式程式、在使用者模式中執行內容檢查，以及將檢查的內容轉送至原始目的地。

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 和其他數個相關的 IOCTLS 是使用者模式元件，可用來允許多個以一種合作方式檢查相同的流量流量。每個檢查代理程式都可以安全地重新檢查其他檢查代理程式已檢查的網路流量。因為有多個 Proxy (由不同的 ISV 所開發，例如，) 一個 Proxy 用來與最終目的地通訊的連線可能會由第二個 Proxy 重新導向，而且原始 Proxy 可以再次重新導向新的連線。如果沒有連線追蹤，原始連線可能永遠不會到達其最終目的地，因為它停滯在無限 Proxy 迴圈中。

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 可用來提供重新導向通訊端連線的 Proxy 連線追蹤。此「計畫」功能可協助追蹤從連線的初始重新導向到目的地最終連線的重新導向記錄。

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 是由一個以其隨附的核心模式圖說文字，從接受的 TCP/IP 封包連線擷取重新導向記錄， (TCP 通訊端或 UDP 通訊端的連線通訊端，例如，) 由其在核心模式驅動程式的ALE_CONNECT_REDIRECT層註冊的隨附核心模式圖說文字來擷取重新導向記錄。 SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL 是由一個以一個以一個為以一個原則為基礎的重新導向服務使用，從接受的 TCP/IP 封包連線擷取重新導向記錄的重新導向內容， (TCP 通訊端或 UDP 通訊端的連線通訊端，例如) 由其在ALE_CONNECT_REDIRECT層註冊的隨附圖說文字重新導向至它。重新導向內容是選擇性的驅動程式配置內容，如果連線的目前重新導向狀態是呼叫重新導向服務重新導向連線，或先前由呼叫重新導向服務重新導向連線，但稍後會由不同的重新導向服務重新導向。針對 TCP Proxy 連線，重新導向服務會將擷取的重新導向記錄傳輸至它用來使用 SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL Proxy 原始內容的 TCP 通訊端。

當重新導向服務重新導向非 TCP 通訊端 (UDP 時，例如) ，SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 傳回的重新導向記錄會使用搭配LPFN_WSARECVMSG (WSARecvMsg) 函式使用的 WSAMSG結構，向重新導向服務表示。 WSAMSG結構的 Control 成員會在WSACMSGHDR結構中設定為IP_CONNECTION_REDIRECT_RECORD cmsg_type。接受非 TCP 重新導向時，必須由重新導向服務提供 LPFN_WSARECVMSG (WSARecvMsg) 參數。

針對非 TCP 流量，會使用 WSAMSG 結構搭配 WSASendMsg 函式轉送重新導向記錄。

請注意，對於非 TCP 流量，只有流程建立封包會包含 IP_CONNECTION_REDIRECT_RECORD。因此，只有第一個 Proxy 的封包需要使用 LPFN_WSARECVMSG (WSARecvMsg) 函式來包含此資訊。

由於其為可變長度的資料 Blob，因此呼叫端可以提供大型輸出緩衝區， (lpvOutBuffer 參數指向的 1，024 位元組緩衝區，例如) ，或可以在 0 的 cbOutBuffer 參數中傳遞輸出緩衝區大小，以查詢保存傳回 Blob 所需的緩衝區大小。如果輸出緩衝區大小不足以保存資料，則 WSAIoctl 或 WSPIoctl函式會傳回ERROR_INSUFFICIENT_BUFFER，而且所需的緩衝區大小會以lHTTPBytesReturned參數所指向的值傳回。

呼叫 SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT 的應用程式不需要瞭解包含所擷取之重新導向內容的 Blob。這是應用程式需要擷取並傳回至新通訊端的不透明資料 Blob。