Função WPUModifyIFSHandle (ws2spi.h)

Artigo
08/28/2023

A função WPUModifyIFSHandle recebe um identificador IFS (possivelmente) modificado de Ws2_32.dll.

Sintaxe

SOCKET WPUModifyIFSHandle(
  [in]  DWORD  dwCatalogEntryId,
  [in]  SOCKET ProposedHandle,
  [out] LPINT  lpErrno
);

Parâmetros

[in] dwCatalogEntryId

Descritor que identifica o provedor de serviços de chamada.

[in] ProposedHandle

Identificador IFS alocado pelo provedor.

[out] lpErrno

Ponteiro para o código de erro.

Retornar valor

Se nenhum erro ocorrer, WPUModifyIFSHandle retornará o identificador de soquete modificado. Caso contrário, ele retornará INVALID_SOCKET e um código de erro específico estará disponível no lpErrno.

Código do erro	Significado
WSAEINVAL	O identificador proposto é inválido.

Comentários

O identificador WPUModifyIFSHandle permite que o WS2_32.dll simplifique suas operações internas retornando uma versão possivelmente modificada do identificador IFS fornecido. O identificador retornado tem a garantia de ser indistinguível do identificador proposto no que diz respeito ao sistema operacional. Os provedores IFS devem chamar essa função antes de retornar qualquer descritor de soquete recém-criado para um provedor de serviços. O provedor de serviços usará apenas o identificador modificado para quaisquer operações de soquete subsequentes. Essa rotina só é usada por provedores IFS cujos descritores de soquete são identificadores IFS reais.

**Considerações sobre o provedor de serviços em camadas**

Esse procedimento também pode ser usado por um provedor em camadas que está em camadas sobre um provedor de IFS base e deseja expor os identificadores de soquete do provedor base como seus próprios, em vez de criá-los com uma chamada WPUCreateSocketHandle . Um provedor em camadas que deseja "passar" o soquete IFS que ele recebe da próxima camada da cadeia pode chamar WPUModifyIFSHandle, passando sua própria ID de entrada de catálogo como dwCatalogEntryId. Isso informa à DLL do Windows Sockets que essa camada, e não a próxima camada, deve ser o destino para chamadas SPI envolvendo esse identificador de soquete.

Há várias limitações que um provedor em camadas deve observar se ele adota essa abordagem.

O provedor deve expor pontos de entrada do provedor base para LPWSPSend e LPWSPRecv na tabela de expedição de procedimento retornada no momento do WSPStartup para garantir que o acesso do cliente SPI do Windows Sockets a essas funções seja o mais eficiente possível.
O provedor não pode confiar em suas funções LPWSPSend e LPWSPRecv sendo invocadas para todas as E/S, especialmente no caso das funções do sistema de E/S ReadFile e WriteFile. Essas funções ignorariam o provedor em camadas e invocariam diretamente a implementação do provedor de IFS base, mesmo que o provedor em camadas coloque seus próprios pontos de entrada para essas funções na tabela de expedição do procedimento.
O provedor não pode depender de qualquer capacidade de E/S sobreposta pós-processo usando LPWSPSend, LPWSPSendTo, LPWSPRecv, LPWSPRecvFrom ou LPWSPIoctl. A notificação pós-processamento pode ocorrer por meio de portas de conclusão e ignorar totalmente o provedor em camadas. Um provedor em camadas não tem como determinar se uma porta de conclusão foi usada ou determinar qual porta ela é. O provedor em camadas não tem como se inserir na sequência de notificação.
O provedor deve passar todas as solicitações de E/S sobrepostas diretamente ao provedor base usando os parâmetros sobrepostos originais (por exemplo, a estrutura WSAOVERLAPPED e o ponteiro de rotina de conclusão). O provedor deve expor o ponto de entrada do provedor base para WSPGetOverlappedResult. Como algumas solicitações de E/S sobrepostas podem ignorar completamente o provedor em camadas, o provedor em camadas não pode marcar de forma confiável estruturas WSAOVERLAPPED para determinar para quais elas podem relatar os resultados e quais teriam que ser passadas para o WSPGetOverlappedResult do provedor subjacente. Isso significa efetivamente que LPWSPIoctl precisa ser uma operação de passagem para o provedor subjacente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ws2spi.h