Código de controle SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS
Descrição
O código de controle SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS recupera o registro de redirecionamento para a conexão TCP/IP aceita para uso por um serviço de redirecionamento da Plataforma de Filtragem do Windows (WFP).
Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.
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
);
Parâmetros
s
Um descritor que identifica um soquete.
Dwiocontrolcode
O código de controle da operação. Use SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS para esta operação.
Lpvinbuffer
Um ponteiro para o buffer de entrada. Esse parâmetro não é usado para essa operação.
Cbinbuffer
O tamanho, em bytes, do buffer de entrada. Esse parâmetro não é usado para essa operação.
Lpvoutbuffer
Um ponteiro para o buffer de saída. Esse parâmetro deve apontar para um tipo de dados ULONG se os parâmetros lpOverlapped e lpCompletionRoutine forem NULL.
cbOutBuffer
O tamanho, em bytes, do buffer de saída. Esse parâmetro deve ter pelo menos o tamanho de um tipo de dados ULONG .
Lpcbbytesreturned
Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados armazenados no buffer de saída.
Se o buffer de saída for muito pequeno, a chamada falhará, WSAGetLastError retornará WSAEINVAL e o parâmetro lpcbBytesReturned apontará para um valor DWORD igual a zero.
Se lpOverlapped for NULL, o valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado em uma chamada bem-sucedida não poderá ser zero.
Se o parâmetro lpOverlapped não for NULL para soquetes sobrepostos, as operações que não puderem ser concluídas imediatamente serão iniciadas e a conclusão será indicada posteriormente. O valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado pode ser zero, pois o tamanho dos dados armazenados não pode ser determinado até que a operação sobreposta seja concluída. A conclusão final status pode ser recuperada quando o método de conclusão apropriado é sinalizado quando a operação é concluída.
lpvOverlapped
Um ponteiro para uma estrutura WSAOVERLAPPED .
Se o soquete s tiver sido criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.
Se s tiver sido aberto com o atributo sobreposto e o parâmetro lpOverlapped não for NULL, a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.
Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.
Lpcompletionroutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída (ignorado para soquetes não sobrepostos).
lpThreadId
Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.
Nota Esse parâmetro se aplica somente à função WSPIoctl .
Lperrno
Um ponteiro para o código de erro.
Nota Esse parâmetro se aplica somente à função WSPIoctl .
Valor retornado
Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.
Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.
| Código do erro | Significado |
|---|---|
| ERROR_INSUFFICIENT_BUFFER | A área de dados passada para uma chamada do sistema é muito pequena. Esse erro será retornado se o buffer apontado pelo parâmetro lpvOutBuffer com um tamanho de buffer passado no parâmetro cbOutBuffer for muito pequeno. O tamanho do buffer necessário será retornado no parâmetro lpcbBytesReturned . |
| WSA_IO_PENDING | Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. |
| WSA_OPERATION_ABORTED | Uma operação sobreposta foi cancelada devido ao fechamento do soquete ou à execução do SIO_FLUSH comando IOCTL . |
| WSAEFAULT | O parâmetro lpvOutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário. |
| WSAEINPROGRESS | A função é invocada quando um retorno de chamada está em andamento. |
| WSAEINTR | Uma operação de bloqueio foi interrompida. |
| WSAEINVAL | O parâmetro dwIoControlCode não é um comando válido ou um parâmetro de entrada especificado não é aceitável ou o comando não é aplicável ao tipo de soquete especificado. Esse erro será retornado se o parâmetro cbOutBuffer for menor que o tamanho de um tipo de dados ULONG . |
| WSAENETDOWN | O subsistema de rede falhou. |
| WSAENOPROTOOPT | Não há suporte para a opção de soquete no protocolo especificado. |
| WSAENOTCONN | O soquete s não está conectado. |
| WSAENOTSOCK | O descritor s não é um soquete. |
| WSAEOPNOTSUPP | Não há suporte para o comando IOCTL especificado. Esse erro será retornado se o SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL não tiver suporte do provedor de transporte. |
Comentários
O SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL tem suporte em Windows 8 e Windows Server 2012 e versões posteriores do sistema operacional.
O WFP permite o acesso ao caminho de processamento de pacotes TCP/IP, no qual os pacotes de saída e de entrada podem ser examinados ou alterados antes de permitir que eles sejam processados ainda mais. Ao tocar no caminho de processamento TCP/IP, os ISVs (fornecedores independentes de software) podem criar mais facilmente firewalls, software antivírus, software de diagnóstico e outros tipos de aplicativos e serviços. O WFP fornece componentes do modo de usuário e do modo kernel para que OS ISVs de terceiros possam participar das decisões de filtragem que ocorrem em várias camadas na pilha de protocolos TCP/IP e em todo o sistema operacional. O recurso de redirecionamento de conexão WFP permite que um driver de kernel de texto explicativo WFP redirecione uma conexão localmente para um processo de modo de usuário, execute a inspeção de conteúdo no modo de usuário e encaminhe o conteúdo inspecionado usando uma conexão diferente com o destino original.
O SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL e vários outros IOCTLS relacionados são componentes do modo de usuário usados para permitir que vários aplicativos proxy de conexão baseados em WFP inspecionem o mesmo fluxo de tráfego de maneira cooperativa. Cada agente de inspeção pode inspecionar novamente com segurança o tráfego de rede que já foi inspecionado por outro agente de inspeção. Com a presença de vários proxies (desenvolvidos por DIFERENTES ISVs, por exemplo), a conexão usada por um proxy para se comunicar com o destino final poderia, por sua vez, ser redirecionada por um segundo proxy e essa nova conexão poderia ser redirecionada novamente pelo proxy original. Sem o rastreamento de conexão, a conexão original pode nunca chegar ao destino final, pois ela fica presa em um loop de proxy infinito.
O SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL é usado para fornecer controle de conexão com proxie em conexões de soquete redirecionadas. Esse recurso do WFP facilita o acompanhamento de registros de redirecionamento do redirecionamento inicial de uma conexão para a conexão final com o destino.
O SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL é usado por um serviço de redirecionamento baseado em WFP para recuperar o registro de redirecionamento da conexão de pacote TCP/IP aceita (o soquete conectado para um soquete TCP ou um soquete UDP, por exemplo) redirecionado para ele pelo texto explicativo do modo kernel complementar registrado em camadas ALE_CONNECT_REDIRECT em um driver no modo kernel. O SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL é usado por um serviço de redirecionamento baseado em WFP para recuperar o contexto de redirecionamento de um registro de redirecionamento da conexão de pacote TCP/IP aceita (o soquete conectado para um soquete TCP ou um soquete UDP, por exemplo) redirecionado para ele por seu texto explicativo complementar registrado em camadas ALE_CONNECT_REDIRECT . O contexto de redirecionamento é um contexto opcional alocado pelo driver usado se o estado de redirecionamento atual de uma conexão é que a conexão foi redirecionada pelo serviço de redirecionamento de chamada ou a conexão foi redirecionada anteriormente pelo serviço de redirecionamento de chamada, mas posteriormente redirecionada novamente por um serviço de redirecionamento diferente. Para uma conexão de proxy TCP, o serviço de redirecionamento transfere o registro de redirecionamento recuperado para o soquete TCP que ele usa para fazer proxy do conteúdo original usando o SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.
Quando o serviço de redirecionamento está redirecionando um UDP (soquete não TCP, por exemplo), os registros de redirecionamento retornados pelo SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL indicam isso para o serviço de redirecionamento usando a estrutura WSAMSG usada com a função LPFN_WSARECVMSG (WSARecvMsg). O membro Control da estrutura WSAMSG teria uma cmsg_type na estrutura WSACMSGHDR definida como IP_CONNECTION_REDIRECT_RECORD. O parâmetro LPFN_WSARECVMSG (WSARecvMsg) deve ser fornecido pelo serviço de redirecionamento ao aceitar redirecionamentos não TCP.
Para tráfego não TCP, o registro de redirecionamento é encaminhado usando a estrutura WSAMSG com a função WSASendMsg .
Observe que, para tráfego não TCP, somente o pacote de criação de fluxo carregará o IP_CONNECTION_REDIRECT_RECORD. Como resultado, somente o primeiro pacote com proxie precisa incluir essas informações usando a função LPFN_WSARECVMSG (WSARecvMsg).
Como o registro de redirecionamento do WFP é um blob de dados de comprimento variável, o chamador pode fornecer um buffer de saída grande (um buffer de 1.024 bytes apontado pelo parâmetro lpvOutBuffer , por exemplo) ou pode passar um tamanho de buffer de saída no parâmetro cbOutBuffer de 0 para consultar o tamanho do buffer necessário para manter o blob retornado. Se o tamanho do buffer de saída não for suficiente para manter os dados, as funções WSAIoctl ou WSPIoctl retornarão ERROR_INSUFFICIENT_BUFFER e o tamanho do buffer necessário será retornado em valor apontado pelo parâmetro lpcbBytesReturned .
O aplicativo que chama o SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT não precisa entender o blob que contém o contexto de redirecionamento recuperado. Esse é um blob opaco de dados que o aplicativo precisa recuperar e passar de volta para o novo soquete.