SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS 控制碼

發行項
06/12/2023

Description

SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS控制程式代碼會將重新導向記錄設定為用於連線到最終目的地的新 TCP 通訊端，以供 Windows 篩選平台 () 重新導向服務使用。

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

int WSAIoctl(
  (socket) s,                              // descriptor identifying a socket
  SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  (LPVOID) lpvInputBuffer,                 // lpvInBuffer
  (DWORD) cbInputBuffer,                   // cbInBuffer
  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_SET_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  (LPVOID) lpvInputBuffer,                 // lpvInBuffer
  (DWORD) cbInputBuffer,                   // cbInBuffer
  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_SET_WFP_CONNECTION_REDIRECT_RECORDS 。

lpvInBuffer

輸入緩衝區的指標。這個參數包含與通訊端相關聯之一些的一筆資料重新導向記錄指標。

cbInBuffer

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

lpvOutBuffer

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

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。

錯誤碼	意義
WSA_IO_PENDING	重迭的 I/O 作業正在進行中。如果成功起始重迭的作業，且稍後將會指出完成，則會傳回此值。
WSA_OPERATION_ABORTED	由於執行緒結束或應用程式的要求，因此已經中止 I/O 作業。如果因為通訊端關閉或執行 SIO_FLUSH IOCTL 命令而取消重迭的作業，就會傳回此錯誤。
WSAEACCES	嘗試以其存取權限禁止的方式存取通訊端。此錯誤會在數個包含下列情況的情況下傳回：使用者缺少本機電腦上的必要系統管理許可權，或應用程式未在增強的殼層中執行，因為內建的 Administrator (`RunAs administrator`) 。
WSAEFAULT	系統在嘗試在呼叫中使用指標引數時偵測到不正確指標位址。這個錯誤會傳回 lpvInBuffer、 lpvoutBuffer、 lBytesReturned、 lpOverlapped 或 lpCompletionRoutine 參數，完全不包含在使用者位址空間的有效部分中。
WSAEINPROGRESS	正在執行封鎖作業。如果在回呼進行中時叫用函式，就會傳回此錯誤。
WSAEINTR	封鎖作業因呼叫 WSACancelBlockingCall而中斷。如果封鎖作業中斷，就會傳回此錯誤。
WSAEINVAL	提供的引數無效。如果 dwIoControlCode 參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的通訊端類型，就會傳回此錯誤。
WSAENETDOWN	通訊端作業遇到停止的網路。如果網路子系統失敗，就會傳回此錯誤。
WSAENOTSOCK	嘗試在不是通訊端的內容上執行作業。如果描述元 s 不是通訊端，則會傳回此錯誤。
WSAEOPNOTSUPP	所參考物件的類型不支援嘗試的作業。如果不支援指定的 IOCTL 命令，則會傳回此錯誤。如果傳輸提供者不支援 SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL，也會傳回此錯誤。

備註

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

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

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

SIO_SET_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 通訊端，以使用 SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 來 Proxy 原始內容。

呼叫 SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 的應用程式不需要瞭解包含所設定重新導向記錄的 Blob。這是應用程式需要傳回至新通訊端的不透明資料 Blob。