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.

[out] lpErrno

Um ponteiro para o código de erro. Consulte a seção Valor retornado para obter mais informações.

Valor de retorno

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 em lpErrno.

Observações

Essa função é usada para especificar um objeto de evento, hEventObject, para ser associado aos eventos de rede selecionados, lNetworkEvents. O soquete para o qual um objeto de evento é especificado é identificado pelodo . 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 do 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 quais dos eventos de rede nomeados ocorreram.

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. Consulte as descrições de LPWSPSelect e LPWSPAsyncSelect para descobrir como essas funções relatam erros e atividades de rede.

Essa função define automaticamente o soquete para o modo de não desbloqueio, independentemente do valor de lNetworkEvents.

A emissão de um LPWSPEventSelect para um soquete cancela qualquer LPWSPAsyncSelect ou LPWSPEventSelect 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á a FD_WRITE evento de rede associado ao 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, você deve definir 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 LPWSPAccept'soquete ed tem as mesmas propriedades que o soquete de escuta usado para aceitá-lo, qualquer LPWSPEventSelect associação e 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 eventos de rede FD_WRITE 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 habilita implicitamente a configuração desse evento de rede e a sinalização do objeto de evento associado.

Qualquer chamada para a rotina de reabilitação, mesmo uma que falha, 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.

1. O provedor de serviços recebe 100 bytes de dados no soquete , registra o evento de rede FD_READ e sinaliza o objeto de evento associado.
2. O cliente SPI do Windows Sockets WSPRecv(s, buffptr, 50, 0) ler 50 bytes.
3. 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 QOS (qualidade do serviço). Outras indicações não serão emitidas até que o provedor de serviços detecte uma alteração adicional 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 reissua 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 chama LPWSPEventSelectou quando a função de reabilitação é chamada, um evento de rede é registrado e o objeto de evento associado é sinalizado, conforme apropriado. Por exemplo, considere a sequência a seguir.

1. Um cliente SPI do Windows Sockets chama LPWSPListen.
2. Uma solicitação de conexão é recebida, mas ainda não aceita.
3. 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 imediatamente o objeto de evento associado.

O evento de rede FD_WRITE é tratado de forma ligeiramente diferente. Um evento de rede FD_WRITE é registrado quando um soquete é conectado pela primeira vez com LPWSPConnect ou aceito com LPWSPAccept e depois de um LPWSPSend ou LPWSPSendTo falha com WSAEWOULDBLOCK e o espaço de 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 duração 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 (acelerados) 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 anulativo. 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 do final remoto executando um LPWSPShutdown no lado de envio ou umLPWSPCloseSocket .

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 gravar 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 aodo soquete 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 parade de soquete ou para o grupo de soquetes ao qual 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 esse IOCTL tiver sido emitido.

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ós WSAIoctl com SIO_ADDRESS_LIST_CHANGE tiver sido emitido.

Requisitos

Consulte também

LPWSPEnumNetworkEvents