Código de controle SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT

Artigo
06/12/2023

Descrição

O código de controle SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT recupera o contexto de redirecionamento para um registro de redirecionamento usado 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.

  (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.
);

Parâmetros

s

Um descritor que identifica um soquete.

Dwiocontrolcode

O código de controle da operação. Use SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT 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
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_CONTEXT IOCTL não tiver suporte do provedor de transporte.

Comentários

O SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT 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_CONTEXT IOCTL e vários outros IOCTLS relacionados são componentes de 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_CONTEXT IOCTL é usado 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_CONTEXT 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 é opcional e é 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. 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.

Como o contexto de redirecionamento do WFP é um blob de dados de comprimento variável definido pelo serviço de redirecionamento, o chamador pode fornecer um buffer de saída grande (um buffer de 1K apontado pelo parâmetro lpvOutBuffer , por exemplo) ou pode passar como 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, 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_WF\P_CONNECTION_REDIRECT_RECORDS IOCTL não precisa entender o blob que contém os registros de redirecionamento recuperados. Esse é um blob opaco de dados que o aplicativo precisa recuperar e passar de volta para o novo soquete.