Função WPUCreateSocketHandle (ws2spi.h)

Artigo
08/28/2023

A função WPUCreateSocketHandle cria um novo identificador de soquete.

Sintaxe

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

Parâmetros

[in] dwCatalogEntryId

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

[in] dwContext

Valor de contexto a ser associado ao novo identificador de soquete.

[out] lpErrno

Ponteiro para o código de erro.

Valor retornado

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

Código do erro	Significado
WSAENOBUFS	Não há buffers suficientes disponíveis para criar o identificador de soquete.

Comentários

A função WPUCreateSocketHandle cria um novo identificador de soquete para o provedor especificado. Os identificadores criados por WPUCreateSocketHandle são indistinguíveis de identificadores de sistema de arquivos verdadeiros. Isso é significativo em dois aspectos. Primeiro, a arquitetura do Windows Socket 2 cuida do redirecionamento das funções do sistema de arquivos ReadFile e WriteFile para as funções LPWSPRecv e LPWSPSend desse provedor de serviços, respectivamente. Em segundo lugar, em sistemas operacionais que dão suporte a portas de conclusão, a arquitetura do Windows Sockets 2 dá suporte à associação de uma porta de conclusão com o identificador de soquete e ao usá-la para relatar a conclusão de E/S sobreposta.

**Observação** O mecanismo para redirecionar ReadFile e WriteFile envolve necessariamente uma transição de usuário para kernel para chegar ao redirecionador, seguido por uma transição de kernel para usuário para acessar [LPWSPRecv](nc-ws2spi-lpwsprecv.md) ou [LPWSPSend](nc-ws2spi-lpwspsend.md). No retorno, essas transições são retraídas ao contrário. Isso pode ser uma penalidade de desempenho significativa. Qualquer provedor de serviços que use **WPUCreateSocketHandle** para criar seus identificadores de soquete não deve definir XP1_IFS_HANDLES em sua estrutura WSAProtocol_Info . Os clientes devem usar a ausência de XP1_IFS_HANDLES como diretrizes para evitar o uso de **ReadFile** e **WriteFile**.

**Observação** Não há nenhuma penalidade de desempenho excepcional para usar o mecanismo de porta de conclusão com identificadores de soquete criados com **WPUCreateSocketHandle**. Um provedor de serviços deve usar WPUCompleteOverlappedRequest para anunciar a conclusão de operações de E/S sobrepostas que podem envolver uma porta de conclusão. Os clientes podem usar livremente funções do sistema operacional para criar, associar e usar uma porta de conclusão para notificação de conclusão (por exemplo, CreateIoCompletionPort, GetQueuedCompletionStatus, consulte a documentação relevante do sistema operacional para obter detalhes). Observe que as portas de conclusão não são integradas aos outros mecanismos de notificação assíncrona oferecidos pelo Windows Sockets 2. Ou seja, um cliente pode fazer uma espera múltipla que inclui vários eventos e retornos de chamada de conclusão, mas não há uma maneira predefinida para que a espera múltipla inclua portas de conclusão.

**Considerações do provedor de serviços em camadas**

Esse procedimento é de particular interesse para provedores de serviços em camadas. Um provedor de serviços em camadas pode usar esse procedimento, em vez de WPUModifyIFSHandle para criar os identificadores de soquete expostos ao cliente. A vantagem de usar esse procedimento é que todas as solicitações de E/S que envolvem o soquete podem ser garantidas para passar por esse provedor de serviços. Isso é verdadeiro mesmo que o cliente assuma que os soquetes são identificadores do sistema de arquivos e chama as funções do sistema de arquivos ReadFile e WriteFile (embora ele pague uma penalidade de desempenho por essa suposição).

A garantia de que toda a E/S passa por essa camada é um requisito para camadas que precisam processar o fluxo de E/S antes ou depois da operação de E/S real. Criar identificadores de soquete usando WPUCreateSocketHandle e especificar uma tabela de expedição de procedimento de interface do provedor de serviços apropriada no momento do WSPStartup garante que a camada tenha a chance de se envolver na inicialização de cada operação de E/S. Quando o cliente solicita operações de E/S sobrepostas, essa camada do provedor de serviços geralmente terá que organizar para entrar no caminho da notificação de conclusão de E/S também.

Para ver por que isso é verdadeiro, considere o que acontece se o cliente associar uma porta de conclusão ao identificador de soquete para fins de notificação de conclusão de E/S sobreposta. A porta está associada ao identificador de soquete exposto por essa camada, não ao identificador de soquete da próxima camada. Não há como essa camada determinar se uma porta de conclusão foi associada ou qual é a porta. Quando essa camada chama a operação de E/S da próxima camada, ela usa o identificador de soquete da próxima camada. O identificador de soquete da próxima camada não terá a mesma associação de porta de conclusão. A notificação de porta de conclusão esperada do cliente não ocorrerá sem ajuda extra.

A maneira usual como um provedor de serviços em camadas cuida disso é substituir uma estrutura de E/S sobreposta diferente e diferentes parâmetros de E/S sobrepostos ao invocar uma operação de E/S na próxima camada. A estrutura de E/S sobreposta substituta faz referência à estrutura e aos parâmetros sobrepostos armazenados do cliente. A invocação da próxima camada configura uma notificação de retorno de chamada. Quando a notificação de retorno de chamada ocorre, essa camada executa qualquer pós-processamento desejado, recupera as informações de E/S sobrepostas armazenadas em nome do cliente, descarta as estruturas substitutas e encaminha uma notificação de conclusão apropriada para o cliente.

Requisitos


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