Função de retorno de chamada LPWSPSOCKET (ws2spi.h)
A função LPWSPSocket cria um soquete. Para obter informações sobre a parte desempenhada por LPWSPSocket na criação de um soquete compartilhado, consulte Soquetes compartilhados e soquetes compartilhados no SPI.
Sintaxe
LPWSPSOCKET Lpwspsocket;
SOCKET Lpwspsocket(
[in] int af,
[in] int type,
[in] int protocol,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfo,
[in] GROUP g,
DWORD dwFlags,
[out] LPINT lpErrno
)
{...}
Parâmetros
[in] af
Especificação da família de endereços.
[in] type
Especificação de tipo para o novo soquete.
[in] protocol
Protocolo a ser usado com o soquete específico para a família de endereços indicada.
[in] lpProtocolInfo
Ponteiro para uma estrutura WSAProtocol_Info que define as características do soquete a ser criado.
[in] g
Reservado.
dwFlags
Especificação de atributo de soquete.
[out] lpErrno
Ponteiro para o código de erro.
Retornar valor
Se nenhum erro ocorrer, LPWSPSocket retornará um descritor referenciando o novo soquete. Caso contrário, um valor de INVALID_SOCKET será retornado e um código de erro específico estará disponível em lpErrno.
| Código do erro | Significado |
|---|---|
| O subsistema de rede falhou. | |
| A família de endereços especificada não tem suporte. | |
| O bloqueio da chamada do Windows Sockets está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada. | |
| Nenhum descritor de soquete disponível. | |
| Nenhum espaço de buffer disponível. O soquete não pode ser criado. | |
| Não há suporte para o protocolo especificado. | |
| O protocolo especificado é o tipo errado para esse soquete. | |
| O suporte para o tipo de soquete especificado não tem suporte nessa família de endereços. | |
| O parâmetro g especificado não é válido. |
Comentários
A função LPWSPSocket faz com que um descritor de soquete e todos os recursos relacionados sejam alocados. Por padrão, o soquete criado não terá o atributo sobreposto. Os provedores do Windows Sockets são incentivados a serem realizados como sistemas de arquivos instaláveis do Windows e fornecem identificadores de arquivo do sistema como descritores de soquete. Esses provedores devem chamar WPUModifyIFSHandle antes de retornar dessa função. Para provedores do Windows Sockets que não são do sistema de arquivos, o WPUCreateSocketHandle deve ser usado para adquirir um descritor de soquete exclusivo do Ws2_32.dll antes de retornar dessa função. Consulte
Alocação de descritor para obter mais informações.
Os valores para af, type e protocol são aqueles fornecidos pelo aplicativo no soquete de funções de API correspondente ou WSASocket. Um provedor de serviços é livre para ignorar ou prestar atenção a qualquer um ou a todos esses valores, conforme apropriado para o protocolo específico. No entanto, o provedor deve estar disposto a aceitar o valor de zero para af e tipo, já que o Ws2_32.dll considera esses valores curinga. Além disso, o valor da constante de manifesto FROM_PROTOCOL_INFO deve ser aceito para qualquer af, tipo e protocolo. Esse valor indica que o aplicativo Windows Sockets 2 precisa usar os valores correspondentes da estrutura WSAProtocol_Info (iAddressFamily, iSocketType, iProtocol).
O parâmetro dwFlags pode ser usado para especificar os atributos do soquete usando o operador OR bit a bit com qualquer um dos sinalizadores a seguir.
| Sinalizador | Significado |
|---|---|
| WSA_FLAG_OVERLAPPED | Esse sinalizador faz com que um soquete sobreposto seja criado. Soquetes sobrepostos podem utilizar LPWSPSend, LPWSPSendTo, LPWSPRecv, LPWSPRecvFrom e LPWSPIoctl para operações de E/S sobrepostas, que permitem que várias operações sejam iniciadas e processadas simultaneamente. Todas as funções que permitem operações sobrepostas também dão suporte ao uso não sobreposto em um soquete sobreposto se os valores para parâmetros relacionados à operação sobreposta forem nulos. |
| WSA_FLAG_MULTIPOINT_C_ROOT | Indica que o soquete criado será um c_root em uma sessão de vários pontos. Permitido somente se um painel de controle raiz for indicado na estrutura de WSAProtocol_Info do protocolo. |
| WSA_FLAG_MULTIPOINT_C_LEAF | Indica que o soquete criado será um c_leaf em uma sessão multicast. Permitido somente se XP1_SUPPORT_MULTIPOINT for indicado na estrutura de WSAProtocol_Info do protocolo. |
| WSA_FLAG_MULTIPOINT_D_ROOT | Indica que o soquete criado será um d_root em uma sessão de vários pontos. Permitido somente se um plano de dados com raiz for indicado na estrutura de WSAProtocol_Info do protocolo. |
| WSA_FLAG_MULTIPOINT_D_LEAF | Indica que o soquete criado será um d_leaf em uma sessão de vários pontos. Permitido somente se XP1_SUPPORT_MULTIPOINT for indicado na estrutura de WSAProtocol_Info do protocolo. |
Observação
Para soquetes de vários pontos, é necessário especificar exatamente um WSA_FLAG_MULTIPOINT_C_ROOT ou WSA_FLAG_MULTIPOINT_C_LEAF e exatamente um dos WSA_FLAG_MULTIPOINT_D_ROOT ou WSA_FLAG_MULTIPOINT_D_LEAF deve ser especificado. Consulte Multicast independente de protocolo e multiponto no SPI para obter informações adicionais.
Soquetes orientados à conexão, como SOCK_STREAM fornecem conexões full-duplex e devem estar em um estado conectado antes que todos os dados possam ser enviados ou recebidos neles. Uma conexão com outro soquete é criada com uma chamada LPWSPConnect . Uma vez conectados, os dados podem ser transferidos usando chamadas LPWSPSend e LPWSPRecv . Quando uma sessão for concluída, um LPWSPCloseSocket deverá ser executado.
Os protocolos de comunicação usados para implementar um soquete confiável orientado à conexão garantem que os dados não sejam perdidos ou duplicados. Se os dados para os quais o protocolo par tiver espaço em buffer não puderem ser transmitidos com êxito dentro de um período razoável de tempo, a conexão será considerada interrompida e as chamadas subsequentes falharão com o código de erro definido como WSAETIMEDOUT.
Soquetes orientados a mensagens sem conexão permitem enviar e receber datagramas de e para pares arbitrários usando LPWSPSendTo e LPWSPRecvFrom. Se esse soquete estiver conectado usando LPWSPConnect a um par específico, os datagramas poderão ser enviados para esse par usando LPWSPSend e poderão ser recebidos desse par usando LPWSPRecv.
O suporte para soquetes com o tipo SOCK RAW não é necessário, mas os provedores de serviços são incentivados a dar suporte a soquetes brutos sempre que faz sentido fazê-lo.
Um provedor de serviços em camadas fornece uma implementação dessa função, mas também é um cliente dessa função se e quando chama LPWSPSocket da próxima camada na cadeia de protocolo. Algumas considerações especiais se aplicam ao parâmetro lpProtocolInfo dessa função à medida que ela é propagada pelas camadas da cadeia de protocolo.
Se a próxima camada na cadeia de protocolo for outra camada, quando o LPWSPSocket da próxima camada for chamado, essa camada deverá passar para a próxima camada um lpProtocolInfo que referencie a mesma estrutura de WSAProtocol_Info não modificada com as mesmas informações de cadeia não modificadas. No entanto, se a próxima camada for o protocolo base (ou seja, o último elemento na cadeia), essa camada executará uma substituição ao chamar o LPWSPSocket do provedor base. Nesse caso, a estrutura de WSAPROTOCOL_INFO do provedor base deve ser referenciada pelo parâmetro lpProtocolInfo .
Um benefício vital dessa política é que os provedores de serviços base não precisam estar cientes das cadeias de protocolo.
Essa mesma política de propagação se aplica ao propagar uma estrutura WSAProtocol_Info por meio de uma sequência em camadas de outras funções, como LPWSPAddressToString, LPWSPDuplicateSocket, WSPStartup ou LPWSPStringToAddress.
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 |