Função de retorno de chamada LPWSPEVENTSELECT (ws2spi.h)
A função LPWSPEventSelect especifica um objeto de evento a ser associado ao conjunto fornecido de eventos de rede.
Sintaxe
LPWSPEVENTSELECT Lpwspeventselect;
int Lpwspeventselect(
[in] SOCKET s,
[in] WSAEVENT hEventObject,
[in] long lNetworkEvents,
[out] LPINT lpErrno
)
{...}
Parâmetros
[in] s
Um descritor que identifica o soquete.
[in] hEventObject
O identificador que identifica o objeto de evento a ser associado ao conjunto fornecido de eventos de rede.
[in] lNetworkEvents
Uma máscara de bits que especifica a combinação de eventos de rede em que o cliente SPI do Windows Sockets tem interesse. Construído usando o operador OR bit a bit com qualquer um desses valores.
| Valor | Significado |
|---|---|
|
Emite notificação de preparação para leitura. |
|
Emite a notificação de preparação para gravação. |
|
Emite a notificação da chegada de dados OOB. |
|
Emite a notificação de conexões de entrada. |
|
Emite a notificação de conexão concluída. |
|
Emite a notificação de fechamento do soquete. |
|
Emite a notificação de alterações de soquete (QoS). |
|
Reservado. |
|
Emite a notificação de alterações de interface de roteamento para os destinos especificados. |
|
Emite a notificação de alterações na lista de endereços locais para a família de endereços do soquete. |
[out] lpErrno
Um ponteiro para o código de erro. Consulte a seção Valor retornado para obter mais informações.
Retornar valor
O valor retornado será zero se a especificação do cliente SPI do Windows Sockets dos eventos de rede e o objeto de evento associado tiver sido bem-sucedido. Caso contrário, o valor SOCKET_ERROR será retornado e um número de erro específico estará disponível no lpErrno.
| Código do Erro | Significado |
|---|---|
| O subsistema de rede falhou. | |
| Indica que um dos parâmetros especificados era inválido ou o soquete especificado está em um estado inválido. | |
| 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. | |
| O descritor não é um soquete. |
Comentários
Essa função é usada para especificar um objeto de evento, hEventObject, a ser associado aos eventos de rede selecionados, lNetworkEvents. O soquete para o qual um objeto de evento é especificado é identificado por s. O objeto de evento é definido quando ocorrem qualquer um dos eventos de rede nomeados.
LPWSPEventSelect opera de forma muito semelhante a LPWSPAsyncSelect, a diferença está nas ações executadas quando ocorre um evento de rede nomeado. Enquanto WSPAsyncSelect faz com que uma mensagem windows especificada pelo cliente SPI do Windows seja postada, LPWSPEventSelect define o objeto de evento associado e registra a ocorrência desse evento em um registro de evento de rede interno. Um cliente SPI do Windows Sockets pode usar LPWSPEnumNetworkEvents para recuperar o conteúdo do registro de evento de rede interno e, portanto, determinar qual dos eventos de rede indicados ocorreu.
LPWSPEventSelect é a única função que faz com que a atividade de rede e os erros sejam registrados e recuperáveis por meio de LPWSPEnumNetworkEvents. Confira as descrições de LPWSPSelect e LPWSPAsyncSelect para descobrir como essas funções relatam erros e atividades de rede.
Essa função define automaticamente soquetes como modo sem bloqueio, independentemente do valor de lNetworkEvents.
Emitir um LPWSPEventSelect para um soquete cancela qualquer LPWSPAsyncSelect ou LPWSPEventSelect anterior para o mesmo soquete e limpa o registro de evento de rede interno. Por exemplo, para associar um objeto de evento a eventos de rede de leitura e gravação, o cliente SPI do Windows Sockets deve chamar LPWSPEventSelect com FD_READ e FD_WRITE, assim.
rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);
Não é possível especificar objetos de evento diferentes para eventos de rede diferentes. O código a seguir não funcionará; a segunda chamada cancela os efeitos da primeira e a única associação será o evento de rede FD_WRITE associado a hEventObject2.
// Incorrect example.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE);
Para cancelar a associação e a seleção de eventos de rede em um soquete, defina lNetworkEvents como zero, nesse caso, o parâmetro hEventObject é ignorado.
rc = WSPEventSelect(s, hEventObject, 0);
Fechar um soquete com LPWSPCloseSocket também cancela a associação e a seleção de eventos de rede especificados em LPWSPEventSelect para o soquete. No entanto, o cliente SPI do Windows Sockets ainda deve chamar WSACloseEvent para fechar explicitamente o objeto de evento e liberar todos os recursos.
Como um soquete LPWSPAccept'ed tem as mesmas propriedades que o soquete de escuta usado para aceitá-lo, qualquer associação LPWSPEventSelect e o conjunto de seleção de eventos de rede para o soquete de escuta se aplicam ao soquete aceito. Por exemplo, se um soquete de escuta tiver associação LPWSPEventSelect de hEventObject com FD_ACCEPT, FD_READ e FD_WRITE, qualquer soquete aceito nesse soquete de escuta também terá FD_ACCEPT, FD_READ e FD_WRITE eventos de rede associados ao mesmo hEventObject. Se um hEventObject ou eventos de rede diferentes forem desejados, o cliente SPI do Windows Sockets deverá chamar LPWSPEventSelect, passando o soquete aceito e as novas informações desejadas.
Tendo registrado com êxito a ocorrência do evento de rede e sinalizado o objeto de evento associado, nenhuma outra ação será executada para esse evento de rede até que o cliente SPI do Windows Sockets faça a chamada de função que reabilita implicitamente a configuração desse evento de rede e a sinalização do objeto de evento associado.
| Evento de rede | Função de habilitação novamente |
|---|---|
| FD_READ | LPWSPRecv ou LPWSPRecvFrom |
| FD_WRITE | LPWSPSend ou LPWSPSendTo |
| FD_OOB | LPWSPRecv ou LPWSPRecvFrom |
| FD_ACCEPT | LPWSPAccept, a menos que o código de erro retornado seja WSATRY_AGAIN indicando que a função de condição retornou CF_DEFER |
| FD_CONNECT | Nenhuma |
| FD_CLOSE | Nenhuma |
| FD_QOS | LPWSPIoctl com SIO_GET_QOS |
| FD_GROUP_QOS | Reservado para uso futuro com grupos de soquetes: LPWSPIoctl com SIO_GET_GROUP_QOS |
| FD_ROUTING_INTERFACE_CHANGE | LPWSPIoctl com comando SIO_ROUTING_INTERFACE_CHANGE |
| FD_ADDRESS_LIST_CHANGE | LPWSPIoctl com comando SIO_ADDRESS_LIST_CHANGE |
Qualquer chamada para a rotina de reabilitação, mesmo que falhe, resulta na reabilitação da gravação e da sinalização para o evento de rede relevante e o objeto de evento, respectivamente.
Para eventos de rede FD_READ, FD_OOB e FD_ACCEPT, a gravação de eventos de rede e a sinalização de objeto de evento são disparadas em nível. Isso significa que, se a rotina de reabilitação for chamada e a condição de rede relevante ainda for válida após a chamada, o evento de rede será registrado e o objeto de evento associado será sinalizado. Isso permite que um cliente SPI do Windows Sockets seja controlado por eventos e, ao mesmo tempo, não esteja preocupado com a quantidade de dados que chegam a qualquer momento. Considere a sequência a seguir.
- O provedor de serviços recebe 100 bytes de dados em soquetes, registra o evento de rede FD_READ e sinaliza o objeto de evento associado.
- O cliente SPI do Windows Sockets tem problemas
WSPRecv(s, buffptr, 50, 0)para ler 50 bytes. - O provedor de serviços registra o evento de rede FD_READ e sinaliza o objeto de evento associado novamente, pois ainda há dados a serem lidos.
Com essas semânticas, um cliente SPI do Windows Sockets não precisa ler todos os dados disponíveis em resposta a um evento de rede FD_READ. Em vez disso, um único LPWSPRecv em resposta a cada evento de rede FD_READ é apropriado.
Os eventos FD_QOS e FD_GROUP_QOS são considerados disparados por borda. Uma mensagem será postada exatamente uma vez quando ocorrer uma alteração de qualidade de serviço (QOS). Outras indicações não serão emitidas até que o provedor de serviços detecte uma nova alteração no QOS ou o cliente SPI do Windows Sockets renegocia o QOS para o soquete.
Os eventos FD_ROUTING_INTERFACE_CHANGE e FD_ADDRESS_LIST_CHANGE também são considerados disparados por borda . Uma mensagem será postada exatamente uma vez quando ocorrer uma alteração após o cliente SPI do Windows Sockets solicitar a notificação emitindo WSAIoctl com SIO_ROUTING_INTERFACE_CHANGE ou SIO_ADDRESS_LIST_CHANGE correspondentemente. Outras mensagens não serão enviadas até que o cliente SPI do Windows Sockets reemita o IOCTL e outra alteração seja detectada desde que o IOCTL foi emitido.
Se um evento de rede já tiver acontecido quando o cliente SPI do Windows Sockets chamar LPWSPEventSelect ou quando a função de reabilitação for chamada, um evento de rede será registrado e o objeto de evento associado será sinalizado, conforme apropriado. Por exemplo, considere a sequência a seguir.
- Um cliente SPI do Windows Sockets chama LPWSPListen.
- Uma solicitação de conexão é recebida, mas ainda não aceita.
- O cliente SPI do Windows Sockets chama LPWSPEventSelect especificando que ele está interessado no evento de rede FD_ACCEPT para o soquete. O provedor de serviços registra o evento de rede FD_ACCEPT e sinaliza o objeto de evento associado imediatamente.
O evento de rede FD_WRITE é tratado de maneira ligeiramente diferente. Um evento de rede FD_WRITE é registrado quando um soquete é conectado pela primeira vez com LPWSPConnect ou aceito com LPWSPAccept e depois que um LPWSPSend ou LPWSPSendTo falha com WSAEWOULDBLOCK e o espaço do buffer fica disponível. Portanto, um cliente SPI do Windows Sockets pode assumir que os envios são possíveis a partir do primeiro FD_WRITE configuração de evento de rede e durando até que um envio retorne WSAEWOULDBLOCK. Após essa falha, o cliente SPI do Windows Sockets descobrirá que os envios são novamente possíveis quando um evento de rede FD_WRITE é registrado e o objeto de evento associado é sinalizado.
O evento de rede FD_OOB é usado somente quando um soquete é configurado para receber dados fora de banda separadamente. Se o soquete estiver configurado para receber dados fora de banda em linha, os dados fora de banda (agilizados) serão tratados como dados normais e o cliente SPI do Windows Sockets deverá registrar um interesse e obterá, FD_READ evento de rede, não FD_OOB evento de rede. Um cliente SPI do Windows Sockets pode definir ou inspecionar a maneira como os dados fora de banda devem ser tratados usando LPWSPSetSockOpt ou LPWSPGetSockOpt para a opção SO_OOBINLINE.
O código de erro em um evento de rede FD_CLOSE indica se o fechamento do soquete foi normal ou abortivo. Se o código de erro for 0, o fechamento será normal; se o código de erro for WSAECONNRESET, o circuito virtual do soquete foi redefinido. Isso se aplica somente a soquetes orientados à conexão, como SOCK_STREAM.
O evento de rede FD_CLOSE é registrado quando uma indicação próxima é recebida para o circuito virtual correspondente ao soquete. Em termos TCP, isso significa que o FD_CLOSE é registrado quando a conexão entra nos estados FIN WAIT ou CLOSE WAIT. Isso resulta da extremidade remota executando um LPWSPShutdown no lado de envio ou um LPWSPCloseSocket.
Um provedor de serviços deve registrar apenas um evento de rede FD_CLOSE para indicar o fechamento de um circuito virtual; ele não deve registrar um evento de rede FD_READ para indicar essa condição.
O evento de rede FD_QOS ou FD_GROUP_QOS é registrado quando há uma alteração em qualquer campo na especificação de fluxo associada a soquetes ou ao grupo de soquetes ao qual pertence , respectivamente. Essa alteração deve ser disponibilizada para clientes SPI do Windows Sockets por meio da função LPWSPIoctl com SIO_GET_QOS e/ou SIO_GET_GROUP_QOS para recuperar o QOS atual para soquetes s ou para o grupo de soquetes ao qual s pertence, respectivamente.
O evento de rede FD_ROUTING_INTERFACE_CHANGE é registrado quando a interface local que deve ser usada para alcançar o destino especificado em WSAIoctl com SIO_ROUTING_INTERFACE_CHANGE alterações após a emissão desse IOCTL.
O evento de rede FD_ADDRESS_LIST_CHANGE é registrado quando a lista de endereços da família de protocolos de soquetes à qual o cliente SPI do Windows Sockets pode associar alterações apóso WSAIoctl com SIO_ADDRESS_LIST_CHANGE tiver sido emitido.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 10 Build 20348 |
| Servidor mínimo com suporte | Windows 10 Build 20348 |
| Cabeçalho | ws2spi.h |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de