SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT-Steuerelementcode

Artikel
06/12/2023

Beschreibung

Der SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT-Steuerelementcode ruft den Umleitungskontext für einen Umleitungsdatensatz ab, der von einem WFP-Umleitungsdienst (Windows Filtering Platform) verwendet wird.

Rufen Sie zum Ausführen dieses Vorgangs die Funktion WSAIoctl oder WSPIoctl mit den folgenden Parametern auf.

  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT, // 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 WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT, // 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
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure 
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameter

s

Ein Deskriptor, der einen Socket identifiziert.

dwIoControlCode

Der Steuerelementcode für den Vorgang. Verwenden Sie für diesen Vorgang SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT .

lpvInBuffer

Ein Zeiger auf den Eingabepuffer. Dieser Parameter wird für diesen Vorgang nicht verwendet.

cbInBuffer

Die Größe des Eingabepuffers in Bytes. Dieser Parameter wird für diesen Vorgang nicht verwendet.

lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer. Dieser Parameter sollte auf einen ULONG-Datentyp verweisen, wenn die Parameter lpOverlapped und lpCompletionRoutineNULL sind.

cbOutBuffer

Die Größe des Ausgabepuffers in Bytes. Dieser Parameter muss mindestens die Größe eines ULONG-Datentyps aufweisen.

lpcbBytesReturned

Ein Zeiger auf eine Variable, die die Größe der im Ausgabepuffer gespeicherten Daten in Bytes empfängt.

Wenn der Ausgabepuffer zu klein ist, schlägt der Aufruf fehl, WSAGetLastError gibt WSAEINVAL zurück, und der lpcbBytesReturned-Parameter verweist auf einen DWORD-Wert von 0.

Wenn lpOverlappedNULL ist, kann der DWORD-Wert , auf den der parameter lpcbBytesReturned verweist, der bei einem erfolgreichen Aufruf zurückgegeben wird, nicht 0 sein.

Wenn der lpOverlapped-Parameter für überlappende Sockets nicht NULL ist, werden Vorgänge initiiert, die nicht sofort abgeschlossen werden können, und die Vervollständigung wird zu einem späteren Zeitpunkt angezeigt. Der vom zurückgegebenen parameter lpcbBytesReturned angegebene DWORD-Wert kann 0 sein, da die Größe der gespeicherten Daten erst bestimmt werden kann, wenn der überlappende Vorgang abgeschlossen ist. Die endgültige Vervollständigung status kann abgerufen werden, wenn die entsprechende Vervollständigungsmethode signalisiert wird, wenn der Vorgang abgeschlossen ist.

lpvOverlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur .

Wenn Socket s ohne das überlappende Attribut erstellt wurde, wird der lpOverlapped-Parameter ignoriert.

Wenn s mit dem überlappenden Attribut geöffnet wurde und der lpOverlapped-Parameter nicht NULL ist, wird der Vorgang als überlappender (asynchroner) Vorgang ausgeführt. In diesem Fall muss der lpOverlapped-Parameter auf eine gültige WSAOVERLAPPED-Struktur verweisen.

Bei überlappenden Vorgängen wird die WSAIoctl - oder WSPIoctl-Funktion sofort zurückgegeben, und die entsprechende Vervollständigungsmethode wird nach Abschluss des Vorgangs signalisiert. Andernfalls wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde oder ein Fehler auftritt.

lpCompletionRoutine

Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ein Zeiger auf die Vervollständigungsroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde (bei nicht überlappenden Sockets ignoriert).

lpThreadId

Ein Zeiger auf eine WSATHREADID-Struktur , die vom Anbieter in einem nachfolgenden Aufruf von WPUQueueApc verwendet werden soll. Der Anbieter sollte die WSATHREADID-Struktur (nicht den Zeiger auf dieselbe) speichern, bis die WPUQueueApc-Funktion zurückgegeben wird.

Hinweis Dieser Parameter gilt nur für die WSPIoctl-Funktion .

lpErrno

Ein Zeiger auf den Fehlercode.

Hinweis Dieser Parameter gilt nur für die WSPIoctl-Funktion .

Rückgabewert

Wenn der Vorgang erfolgreich abgeschlossen wurde, gibt die WSAIoctl - oder WSPIoctl-Funktion null zurück.

Wenn der Vorgang fehlschlägt oder aussteht, gibt die WSAIoctl - oder WSPIoctl-FunktionSOCKET_ERROR zurück. Rufen Sie WSAGetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Fehlercode	Bedeutung
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich eingeleitet, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
WSA_OPERATION_ABORTED	Ein überlappender Vorgang wurde aufgrund des Schließens des Sockets oder der Ausführung des SIO_FLUSH IOCTL-Befehls abgebrochen.
WSAEFAULT	Der Parameter lpvOutBuffer, lpcbBytesReturned, lpOverlapped oder lpCompletionRoutine ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten.
WSAEINPROGRESS	Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird.
WSAEINTR	Ein Blockierungsvorgang wurde unterbrochen.
WSAEINVAL	Der dwIoControlCode-Parameter ist kein gültiger Befehl, oder ein angegebener Eingabeparameter ist nicht akzeptabel, oder der Befehl gilt nicht für den angegebenen Sockettyp. Dieser Fehler wird zurückgegeben, wenn der cbOutBuffer-Parameter kleiner als die Größe eines ULONG-Datentyps ist.
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENOPROTOOPT	Die Socketoption wird für das angegebene Protokoll nicht unterstützt.
WSAENOTCONN	Der Socket s ist nicht verbunden.
WSAENOTSOCK	Der Deskriptor s ist kein Socket.
WSAEOPNOTSUPP	Der angegebene IOCTL-Befehl wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL vom Transportanbieter nicht unterstützt wird.

Bemerkungen

Die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL wird unter Windows 8 und Windows Server 2012 und höheren Versionen des Betriebssystems unterstützt.

WFP ermöglicht den Zugriff auf den TCP/IP-Paketverarbeitungspfad, wobei ausgehende und eingehende Pakete untersucht oder geändert werden können, bevor sie weiter verarbeitet werden können. Durch Das Erschließen des TCP/IP-Verarbeitungspfads können unabhängige Softwareanbieter (INDEPENDENT Software Vendors, ISVs) leichter Firewalls, Antivirensoftware, Diagnosesoftware und andere Arten von Anwendungen und Diensten erstellen. WFP stellt Benutzermodus- und Kernelmoduskomponenten bereit, sodass IsVs von Drittanbietern an den Filterentscheidungen teilnehmen können, die auf mehreren Ebenen im TCP/IP-Protokollstapel und im gesamten Betriebssystem stattfinden. Die WFP-Verbindungsumleitung ermöglicht es einem WFP-Callout-Kerneltreiber, eine Verbindung lokal an einen Benutzermodusprozess umzuleiten, Inhaltsüberprüfungen im Benutzermodus durchzuführen und den überprüften Inhalt mit einer anderen Verbindung an das ursprüngliche Ziel weiterzuleiten.

Die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL und mehrere andere verwandte IOCTLS sind Benutzermoduskomponenten, die verwendet werden, um es mehreren WFP-basierten Verbindungsproxyanwendungen zu ermöglichen, denselben Datenverkehrsfluss kooperativ zu überprüfen. Jeder Inspektions-Agent kann den Netzwerkdatenverkehr, der bereits von einem anderen Inspektions-Agent überprüft wurde, sicher erneut überprüfen. Wenn mehrere Proxys vorhanden sind (z. B. von verschiedenen ISVs entwickelt), könnte die Verbindung, die von einem Proxy für die Kommunikation mit dem endgültigen Ziel verwendet wird, wiederum von einem zweiten Proxy umgeleitet werden, und diese neue Verbindung könnte erneut vom ursprünglichen Proxy umgeleitet werden. Ohne Die Verbindungsnachverfolgung erreicht die ursprüngliche Verbindung möglicherweise nie ihr endgültiges Ziel, da sie in einer endlosen Proxyschleife hängen bleibt.

Die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL wird verwendet, um es mehreren WFP-basierten Verbindungsproxyanwendungen zu ermöglichen, denselben Datenverkehrsfluss kooperativ zu überprüfen. Jeder Inspektions-Agent kann den Netzwerkdatenverkehr, der bereits von einem anderen Inspektions-Agent überprüft wurde, sicher erneut überprüfen. Wenn mehrere Proxys vorhanden sind (z. B. von verschiedenen ISVs entwickelt), könnte die Verbindung, die von einem Proxy für die Kommunikation mit dem endgültigen Ziel verwendet wird, wiederum von einem zweiten Proxy umgeleitet werden, und diese neue Verbindung könnte erneut vom ursprünglichen Proxy umgeleitet werden. Ohne Die Verbindungsnachverfolgung erreicht die ursprüngliche Verbindung möglicherweise nie ihr endgültiges Ziel, da sie in einer endlosen Proxyschleife hängen bleibt. Die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL wird verwendet, um die Nachverfolgung von Verbindungen mit umgeleiteten Sockets zu ermöglichen. Dieses WFP-Feature erleichtert die Nachverfolgung von Umleitungsdatensätzen von der anfänglichen Umleitung einer Verbindung bis zur endgültigen Verbindung zum Ziel.

Die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL wird von einem WFP-basierten Umleitungsdienst verwendet, um den Umleitungsdatensatz von der akzeptierten TCP/IP-Paketverbindung (z. B. dem verbundenen Socket für einen TCP-Socket oder einem UDP-Socket) abzurufen, der von der zugehörigen Kernelmodus-Legende, die auf ALE_CONNECT_REDIRECT Ebenen in einem Kernelmodustreiber registriert ist, an ihn umgeleitet wird. Die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL wird von einem WFP-basierten Umleitungsdienst verwendet, um den Umleitungskontext für einen Umleitungsdatensatz von der akzeptierten TCP/IP-Paketverbindung abzurufen (z. B. der verbundene Socket für einen TCP-Socket oder einen UDP-Socket), der von der Begleitbeschriftung, die auf ALE_CONNECT_REDIRECT Ebenen registriert ist, an ihn umgeleitet wird. Der Umleitungskontext ist optional und wird verwendet, wenn der aktuelle Umleitungsstatus einer Verbindung darin besteht, dass die Verbindung vom aufrufenden Umleitungsdienst umgeleitet wurde oder die Verbindung zuvor vom aufrufenden Umleitungsdienst umgeleitet wurde, später aber wieder von einem anderen Umleitungsdienst umgeleitet wurde. Der Umleitungsdienst überträgt den abgerufenen Umleitungsdatensatz an den TCP-Socket, den er verwendet, um den ursprünglichen Inhalt mithilfe des SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL zu proxyn.

Da der WFP-Umleitungskontext ein Datenblob mit variabler Länge ist, das vom Umleitungsdienst festgelegt wurde, kann der Aufrufer entweder einen großen Ausgabepuffer bereitstellen (z. B. einen 1K-Puffer, auf den der lpvOutBuffer-Parameter verweist) oder als Ausgabepuffergröße im cbOutBuffer-Parameter von 0 übergeben, um die Puffergröße abzufragen, die zum Speichern des zurückgegebenen Blobs erforderlich ist. Wenn die Ausgabepuffergröße nicht ausreicht, um die Daten zu halten, geben die Funktionen WSAIoctl oder WSPIoctlERROR_INSUFFICIENT_BUFFER zurück, und die erforderliche Puffergröße wird als Wert zurückgegeben, auf den der lpcbBytesReturned-Parameter verweist.

Die Anwendung, die die SIO_QUERY_WF\P_CONNECTION_REDIRECT_RECORDS IOCTL aufruft, muss das Blob nicht verstehen, das die abgerufenen Umleitungsdatensätze enthält. Dies ist ein undurchsichtiges Datenblob, das die Anwendung abrufen und an den neuen Socket zurückgeben muss.