codice di controllo SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS
Descrizione
Il codice di controllo SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS recupera il record di reindirizzamento per la connessione TCP/IP accettata per l'uso da parte di un servizio di reindirizzamento di Windows Filtering Platform (WFP).
Per eseguire questa operazione, chiamare la funzione WSAIoctl o WSPIoctl con i parametri seguenti.
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
);
Parametri
s
Descrittore che identifica un socket.
dwIoControlCode
Codice di controllo per l'operazione. Usare SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS per questa operazione.
lpvInBuffer
Puntatore al buffer di input. Questo parametro non è usato per questa operazione.
cbInBuffer
Dimensione, in byte, del buffer di input. Questo parametro non è usato per questa operazione.
lpvOutBuffer
Puntatore al buffer di output. Questo parametro deve puntare a un tipo di dati ULONG se i parametri lpOverlapped e lpCompletionRoutine sono NULL.
cbOutBuffer
Dimensione, in byte, del buffer di output. Questo parametro deve avere almeno le dimensioni di un tipo di dati ULONG .
lpcbBytesReturned
Puntatore a una variabile che riceve le dimensioni, in byte, dei dati archiviati nel buffer di output.
Se il buffer di output è troppo piccolo, la chiamata non riesce, WSAGetLastErrorrestituisce WSAEINVAL e il parametro lpcbBytesReturned punta a un valore DWORD pari a zero.
Se lpOverlapped è NULL, il valore DWORD a cui punta il parametro lpcbBytesReturned restituito in una chiamata riuscita non può essere zero.
Se il parametro lpOverlapped non è NULL per i socket sovrapposti, le operazioni che non possono essere completate immediatamente verranno avviate e il completamento verrà indicato in un secondo momento. Il valore DWORD a cui punta il parametro lpcbBytesReturned restituito può essere zero perché le dimensioni dei dati archiviati non possono essere determinate fino al completamento dell'operazione sovrapposta. Lo stato di completamento finale può essere recuperato quando viene segnalato il metodo di completamento appropriato al termine dell'operazione.
lpvOverlapped
Puntatore a una struttura WSAOVERLAPPED .
Se socket s è stato creato senza l'attributo sovrapposto, il parametro lpOverlapped viene ignorato.
Se s è stato aperto con l'attributo sovrapposto e il parametro lpOverlapped non è NULL, l'operazione viene eseguita come operazione sovrapposta (asincrona). In questo caso, il parametro lpOverlapped deve puntare a una struttura WSAOVERLAPPED valida.
Per le operazioni sovrapposte, la funzione WSAIoctl o WSPIoctl restituisce immediatamente e il metodo di completamento appropriato viene segnalato al termine dell'operazione. In caso contrario, la funzione non restituisce finché l'operazione non è stata completata o si verifica un errore.
lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Puntatore alla routine di completamento chiamata quando l'operazione è stata completata (ignorata per socket non sovrapposti).
lpThreadId
Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID a cui si fa riferimento (non il puntatore allo stesso) fino a quando non viene restituita la funzione WPUQueueApc .
Nota Questo parametro si applica solo alla funzione WSPIoctl .
lpErrno
Puntatore al codice di errore.
Nota Questo parametro si applica solo alla funzione WSPIoctl .
Valore restituito
Se l'operazione viene completata correttamente, la funzione WSAIoctl o WSPIoctl restituisce zero.
Se l'operazione ha esito negativo o è in sospeso, la funzione WSAIoctl o WSPIoctl restituisce SOCKET_ERROR. Per ottenere informazioni estese sull'errore, chiamare WSAGetLastError.
| Codice di errore | Significato |
|---|---|
| ERROR_INSUFFICIENT_BUFFER | L'area dati passata a una chiamata di sistema è troppo piccola. Questo errore viene restituito se il buffer a cui punta il parametro lpvOutBuffer con una dimensione del buffer passata nel parametro cbOutBuffer è troppo piccola. Le dimensioni del buffer necessarie verranno restituite nel parametro lpcbBytesReturned . |
| WSA_IO_PENDING | Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento. |
| WSA_OPERATION_ABORTED | Un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando SIO_FLUSH IOCTL. |
| WSAEFAULT | Il parametro lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio indirizzi utente. |
| WSAEINPROGRESS | La funzione viene richiamata quando è in corso un callback. |
| WSAEINTR | Un'operazione di blocco è stata interrotta. |
| WSAEINVAL | Il parametro dwIoControlCode non è un comando valido o un parametro di input specificato non è accettabile oppure il comando non è applicabile al tipo di socket specificato. Questo errore viene restituito se il parametro cbOutBuffer è minore delle dimensioni di un tipo di dati ULONG . |
| WSAENETDOWN | Il sottosistema di rete non è riuscito. |
| WSAENOPROTOOPT | L'opzione socket non è supportata nel protocollo specificato. |
| WSAENOTCONN | Il socket s non è connesso. |
| WSAENOTSOCK | Il descrittore s non è un socket. |
| WSAEOPNOTSUPP | Il comando IOCTL specificato non è supportato. Questo errore viene restituito se il SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL non è supportato dal provider di trasporto. |
Commenti
Il SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL è supportato in Windows 8 e Windows Server 2012 e versioni successive del sistema operativo.
IL WFP consente l'accesso al percorso di elaborazione dei pacchetti TCP/IP, in cui i pacchetti in uscita e in ingresso possono essere esaminati o modificati prima di poterli elaborare ulteriormente. Grazie al percorso di elaborazione TCP/IP, i fornitori di software indipendenti (ISV) possono creare più facilmente firewall, software antivirus, software di diagnostica e altri tipi di applicazioni e servizi. WFP fornisce componenti in modalità utente e in modalità kernel, in modo che gli ISV di terze parti possano partecipare alle decisioni di filtro che si svolgono a diversi livelli nello stack di protocolli TCP/IP e in tutto il sistema operativo. La funzionalità di reindirizzamento della connessione WFP consente a un driver kernel di callout WFP di reindirizzare una connessione in locale a un processo in modalità utente, eseguire l'ispezione del contenuto in modalità utente e inoltrare il contenuto controllato usando una connessione diversa alla destinazione originale.
I SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL e molti altri IOCTLS correlati sono componenti in modalità utente usati per consentire a più applicazioni proxy di connessione basate sul WFP di controllare lo stesso flusso di traffico in modo cooperativo. Ogni agente di ispezione può controllare di nuovo il traffico di rete già controllato da un altro agente di ispezione. Con la presenza di più proxy (sviluppati da ISV diversi, ad esempio) la connessione usata da un proxy per comunicare con la destinazione finale potrebbe essere reindirizzata a sua volta da un secondo proxy e tale nuova connessione potrebbe essere nuovamente reindirizzata dal proxy originale. Senza il rilevamento delle connessioni, la connessione originale potrebbe non raggiungere mai la destinazione finale perché rimane bloccata in un ciclo proxy infinito.
Il SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL viene usato per fornire il rilevamento della connessione proxy sulle connessioni socket reindirizzate. Questa funzionalità DEL WFP facilita il rilevamento dei record di reindirizzamento dal reindirizzamento iniziale di una connessione alla connessione finale alla destinazione.
Il SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL viene usato da un servizio di reindirizzamento basato su WFP per recuperare il record di reindirizzamento dalla connessione di pacchetto TCP/IP accettata (il socket connesso per un socket TCP o un socket UDP, ad esempio) reindirizzato a esso dal callout in modalità kernel complementare registrato a ALE_CONNECT_REDIRECT livelli in un driver in modalità kernel. Il SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL viene usato da un servizio di reindirizzamento basato su WFP per recuperare il contesto di reindirizzamento per un record di reindirizzamento dalla connessione di pacchetto TCP/IP accettata (il socket connesso per un socket TCP o un socket UDP, ad esempio) reindirizzato a esso dal callout complementare registrato a livelli ALE_CONNECT_REDIRECT . Il contesto di reindirizzamento è un contesto facoltativo allocato dal driver utilizzato se lo stato di reindirizzamento corrente di una connessione è che la connessione è stata reindirizzata dal servizio di reindirizzamento chiamante o la connessione è stata reindirizzata in precedenza dal servizio di reindirizzamento chiamante ma successivamente reindirizzata di nuovo da un servizio di reindirizzamento diverso. Per una connessione proxy TCP, il servizio di reindirizzamento trasferisce il record di reindirizzamento recuperato al socket TCP usato per proxyre il contenuto originale usando il SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.
Quando il servizio di reindirizzamento reindirizza un socket non TCP (UDP, ad esempio), i record di reindirizzamento restituiti dal SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL indicano questo valore al servizio di reindirizzamento usando la struttura WSAMSG usata con la funzione LPFN_WSARECVMSG WSARecvMsg (WSARecvMsg). Il membro Control della struttura WSAMSG avrà un cmsg_type nella struttura WSACMSGHDR impostata su IP_CONNECTION_REDIRECT_RECORD. Il parametro LPFN_WSARECVMSG (WSARecvMsg) deve essere fornito dal servizio di reindirizzamento quando si accettano reindirizzamenti non TCP.
Per il traffico non TCP, il record di reindirizzamento viene inoltrato usando la struttura WSAMSG con la funzione WSASendMsg .
Si noti che per il traffico non TCP, solo il pacchetto di creazione del flusso conterrà il IP_CONNECTION_REDIRECT_RECORD. Di conseguenza, solo il primo pacchetto proxied deve includere queste informazioni usando la funzione LPFN_WSARECVMSG (WSARecvMsg).
Poiché il record di reindirizzamento WFP è un BLOB di dati a lunghezza variabile, il chiamante può fornire un buffer di output di grandi dimensioni (un buffer di 1.024 byte a cui punta il parametro lpvOutBuffer , ad esempio) o può passare una dimensione del buffer di output nel parametro cbOutBuffer di 0 per eseguire una query sulle dimensioni del buffer necessarie per contenere il BLOB restituito. Se le dimensioni del buffer di output non sono sufficienti per contenere i dati, le funzioni WSAIoctl o WSPIoctl restituiranno ERROR_INSUFFICIENT_BUFFER e le dimensioni del buffer necessarie verranno restituite nel valore a cui punta il parametro lpcbBytesReturned .
L'applicazione che chiama il SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT non deve comprendere il BLOB contenente il contesto di reindirizzamento recuperato. Si tratta di un BLOB opaco di dati che l'applicazione deve recuperare e passare di nuovo al nuovo socket.