Compartilhar via

Função de retorno de chamada LPWSPASYNCSELECT (ws2spi.h)

  • Artigo

A função LPWSPAsyncSelect solicita a notificação de evento baseada em mensagem do Windows de eventos de rede para um soquete.

Sintaxe

LPWSPASYNCSELECT Lpwspasyncselect;

int Lpwspasyncselect(
  [in]  SOCKET s,
  [in]  HWND hWnd,
  [in]  unsigned int wMsg,
  [in]  long lEvent,
  [out] LPINT lpErrno
)
{...}

Parâmetros

[in] s

Descritor que identifica o soquete para o qual a notificação de evento é necessária.

[in] hWnd

Manipule a identificação da janela que deve receber uma mensagem quando ocorrer um evento de rede.

[in] wMsg

Mensagem a ser enviada quando ocorrer um evento de rede.

[in] lEvent

Máscara de bits que especifica uma combinação de eventos de rede em que o cliente SPI (interface do provedor de serviços) do Windows Sockets está interessado. Construído usando o operador OR bit a bit com qualquer um desses valores.

Valor Significado
FD_READ
Emite notificação de preparação para leitura.
FD_WRITE
Emite notificação de preparação para gravação.
FD_OOB
Emite a notificação da chegada dos dados do OOB.
FD_ACCEPT
Emite a notificação de conexões de entrada.
FD_CONNECT
Emite a notificação de conexões concluídas.
FD_CLOSE
Emite a notificação de fechamento do soquete.
FD_QOS
Emite a notificação de alterações de QoS (qualidade do serviço) do soquete.
FD_GROUP_QOS
Reservado.
FD_ROUTING_INTERFACE_CHANGE
Emite a notificação de alteração da interface de roteamento para o destino especificado.
FD_ADDRESS_ LIST_CHANGE
Emite a notificação da alteração da lista de endereços local para a família de protocolos do soquete.

[out] lpErrno

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 declaração de interesse do cliente SPI do Windows Sockets no conjunto de eventos de rede tiver sido bem-sucedida. Caso contrário, o valor SOCKET_ERROR será retornado e um código de erro específico estará disponível em lpErrno.

Código de erro Significado
WSAENETDOWN
 O subsistema de rede falhou.
WSAEINVAL
 Indica que um dos parâmetros especificados era inválido, como o identificador de janela que não se refere a uma janela existente ou o soquete especificado está em um estado inválido.
WSAEINPROGRESS
 Uma chamada de bloqueio do Windows Sockets está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAENOTSOCK
 O descritor não é um soquete.

Consulte Comentários para obter informações sobre códigos de erro adicionais que podem ser definidos (na palavra alta de lParam dentro da mensagem) quando uma janela do aplicativo recebe uma mensagem.

Observações

Essa função é usada para solicitar que o provedor de serviços envie uma mensagem do Windows para a janela do cliente hWnd sempre que o provedor de serviços detectar qualquer um dos eventos de rede especificados pelo argumento lEvent. O provedor de serviços deve usar a função WPUPostMessage para postar a mensagem. A mensagem a ser enviada é especificada pelo parâmetro wMsg. O soquete para o qual a notificação é necessária é identificado pelodo .

Essa função define automaticamente o soquete para o modo sem bloqueio, independentemente do valor de lEvent. Consulte LPWSPIoctl sobre como definir o soquete de volta para o modo de bloqueio.

Invocar LPWSPAsyncSelect para um soquete cancela qualquer LPWSPAsyncSelect anterior ou LPWSPEventSelect para o mesmo soquete. Por exemplo, para receber notificação para leitura e gravação, o cliente SPI do Windows Sockets deve chamar LPWSPAsyncSelect com FD_READ e FD_WRITE, assim.

rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);

Não é possível especificar mensagens diferentes para eventos 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 associado ao wMsg2.

// Incorrect example.
rc = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);

Para cancelar toda a notificação (ou seja, para indicar que o provedor de serviços não deve enviar mais mensagens relacionadas a eventos de rede no soquete), defina lEvent como zero.

rc = WSPAsyncSelect(s, hWnd, 0, 0, &error);

Como um LPWSPAcceptsoquete ed tem as mesmas propriedades que o soquete de escuta usado para aceitá-lo, qualquer LPWSPAsyncSelect eventos definidos para o soquete de escuta se aplicam ao soquete aceito. Por exemplo, se um soquete de escuta tiver LPWSPAsyncSelect eventos FD_ACCEPT, FD_READ e FD_WRITE, qualquer soquete aceito nesse soquete de escuta também terá eventos FD_ACCEPT, FD_READ e FD_WRITE com o mesmo valor de wMsg usado para mensagens. Se um wMsg ou eventos diferentes forem desejados, o cliente SPI do Windows Sockets deverá chamar LPWSPAsyncSelect, passando o soquete aceito e as novas informações desejadas.

Quando um dos eventos de rede nomeados ocorre no soquete especificado , o provedor de serviços usa WPUPostMessage para enviar mensagens wMsg para a janela do cliente SPI do Windows Sockets hWnd. Na mensagem postada, o argumento wParam identifica o soquete no qual ocorreu um evento de rede. A palavra baixa de lParam especifica o evento de rede que ocorreu. Os possíveis códigos de evento de rede que podem ser indicados são os seguintes.

Valor Significado
FD_READ O do soquete está pronto para leitura
FD_WRITE O do soquete está pronto para gravação
FD_OOB Os dados fora de banda estão prontos para leitura no soquete
FD_ACCEPT O do soquete está pronto para aceitar uma nova conexão de entrada
FD_CONNECT A conexão iniciada no soquete foi concluída
FD_CLOSE A conexão identificada pelo soquete foi fechada
FD_QOS A qualidade do serviço associado ao do soquete foi alterada
FD_GROUP_QOS Reservado para uso futuro com grupos de soquetes: a qualidade do serviço associada ao grupo de soquetes ao qual pertence o soquete foi alterada
FD_ROUTING_INTERFACE_CHANGE A interface local que deve ser usada para enviar para o destino especificado foi alterada
FD_ADDRESS_LIST_CHANGE A lista de endereços da família de protocolos do soquete à qual o cliente SPI do Windows Sockets pode associar foi alterada

A palavra alta de lParam contém qualquer código de erro (ele pode ser extraído usando a macro WSAGETSELECTERROR). O código de erro é qualquer erro conforme definido em ws2spi.h. Códigos de erro possíveis para cada evento de rede são listados na tabela a seguir.

Evento : FD_CONNECT

Código de erro Significado
WSAEAFNOSUPPORT
 Os endereços na família especificada não podem ser usados com esse soquete.
WSAECONNREFUSED
 A tentativa de conexão foi rejeitada.
WSAENETUNREACH
 A rede não pode ser acessada desse host no momento.
WSAEFAULT
 O parâmetro namelen é inválido.
WSAEINVAL
 O soquete já está associado a um endereço.
WSAEISCONN
 O soquete já está conectado.
WSAEMFILE
 Não há mais descritores de arquivo disponíveis.
WSAENOBUFS
 Nenhum espaço de buffer está disponível. O soquete não pode ser conectado.
WSAENOTCONN
 O soquete não está conectado.
WSAETIMEDOUT
 Tente se conectar com o tempo limite sem estabelecer uma conexão.

Evento : FD_CLOSE

Código de erro Significado
WSAENETDOWN
 O subsistema de rede falhou.
WSAECONNRESET
 A conexão foi redefinida pelo lado remoto.
WSAECONNABORTED
 A conexão foi encerrada devido a um tempo limite ou outra falha.

evento ...: FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE

Código de erro Significado
WSAENETDOWN
 O subsistema de rede falhou.

Evento : FD_ROUTING_INTERFACE_CHANGE

Código de erro Significado
WSAENETUNREACH
 O destino especificado não é mais acessível.
WSAENETDOWN
 O subsistema de rede falhou.

Embora LPWSPAsyncSelect possa ser chamado com interesse em vários eventos, o provedor de serviços emite a mesma mensagem do Windows para cada evento.

Um provedor do Windows Sockets 2 não deve inundar continuamente um cliente SPI do Windows Sockets com mensagens para um evento de rede específico. Depois de postar com êxito a notificação de um evento específico em uma janela do cliente SPI do Windows Sockets, nenhuma mensagem adicional para esse evento de rede será postada na janela do cliente SPI do Windows Sockets até que o cliente SPI do Windows Sockets faça a chamada de função que habilita implicitamente a notificação desse evento de rede.

Evento de rede Função de reabilitação
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 NENHUM
FD_CLOSE NENHUM
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 SIO_ROUTING_INTERFACE_CHANGE de comando
FD_ADDRESS_LIST_CHANGE LPWSPIoctl com SIO_ADDRESS_LIST_CHANGE de comando

Qualquer chamada para a rotina de reabilitação, mesmo que falhe, resulta na reabilitação da postagem de mensagens para o evento relevante.

Para eventos FD_READ, FD_OOB e FD_ACCEPT, a postagem de mensagens é disparada em nível. Isso significa que, se a rotina de reabilitação for chamada e a condição relevante ainda for atendida após a chamada, uma mensagem LPWSPAsyncSelect será postada no cliente SPI do Windows Sockets.

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. Outras mensagens não serão enviadas até que o provedor detecte uma alteração adicional no QOS ou o cliente SPI do Windows Sockets renegociará 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 algum evento já tiver acontecido quando o cliente SPI do Windows Sockets chamar LPWSPAsyncSelect ou quando a função de reabilitação for chamada, uma mensagem será postada 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 LPWSPAsyncSelect especificando que ele deseja receber mensagens FD_ACCEPT para o soquete. Devido à persistência de eventos, o provedor de serviços do WinSock posta uma mensagem de FD_ACCEPT imediatamente.

O evento FD_WRITE é tratado de forma ligeiramente diferente. Uma mensagem FD_WRITE é postada quando um soquete é conectado pela primeira vez com LPWSPConnect (após FD_CONNECT, se também estiver registrado) ou aceito com LPWSPAccept e depois que um LPWSPSend ou LPWSPSendTo falhar com WSAEWOULDBLOCK e o espaço de buffer ficar disponível. Portanto, um cliente SPI do Windows Sockets pode assumir que os envios são possíveis a partir do primeiro FD_WRITE mensagem e duração até que um envio retorne WSAEWOULDBLOCK. Após essa falha, o cliente SPI do Windows Sockets será notificado de que os envios são novamente possíveis com uma mensagem FD_WRITE.

O evento 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 interesse em eventos FD_READ, não FD_OOB eventos.

O código de erro em uma mensagem de 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 só se aplica a soquetes orientados à conexão, como SOCK_STREAM.

A mensagem FD_CLOSE é postada quando uma indicação próxima é recebida para o circuito virtual correspondente ao soquete. Em termos TCP, isso significa que o FD_CLOSE é postado quando a conexão entra nos estados TIME WAIT ou CLOSE WAIT. Isso resulta do final remoto executando um LPWSPShutdown no lado de envio ou um LPWSPCloseSocket. É correto que FD_CLOSE sejam postados somente depois que todos os dados forem lidos de um soquete.

No caso de um fechamento normal, o provedor de serviços deve enviar uma mensagem FD_CLOSE para indicar o fechamento do circuito virtual somente depois que todos os dados recebidos tiverem sido lidos. Ele não deve enviar uma mensagem FD_READ para indicar essa condição.

A mensagem FD_QOS ou FD_GROUP_QOS é postada 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. O provedor de serviços deve atualizar as informações de QOS disponíveis para o cliente por meio de LPWSPIoctl com SIO_GET_QOS e/ou SIO_GET_GROUP_QOS.

A mensagem FD_ROUTING_INTERFACE_CHANGE é postada quando a interface local que deve ser usada para alcançar o destino especificado em LPWSPIoctl com alterações SIO_ROUTING_INTERFACE_CHANGE após esse IOCTL tiver sido emitido.

A mensagem FD_ADDRESS_LIST_CHANGE é postada quando a lista de endereços aos quais o cliente SPI do Windows Sockets pode associar alterações após LPWSPIoctl com SIO_ADDRESS_LIST_CHANGE foi emitida.

Aqui está um resumo de eventos e condições para cada mensagem de notificação assíncrona.

FD_READ

  1. Quando LPWSPAsyncSelect é chamado, se houver dados disponíveis para receber no momento.
  2. Quando os dados chegarem, se ainda não FD_READ postados.
  3. Após LPWSPRecv ou LPWSPRecvFrom for chamado (com ou sem MSG_PEEK), se os dados ainda estiverem disponíveis para receber.

Quando SO_OOBINLINE LPWSPSetSockOpt está habilitado, de dados inclui dados normais e dados OOB (fora de banda) nas instâncias indicadas acima.

FD_WRITE

  1. Quando LPWSPAsyncSelect é chamado, se um LPWSPSend ou LPWSPSendTo for possível.
  2. Depois de LPWSPConnect ou LPWSPAccept é chamado, quando a conexão é estabelecida.
  3. Após LPWSPSend ou LPWSPSendTo falhar com O WSAEWOULDBLOCK, quando LPWSPSend ou LPWSPSendTo provavelmente terá êxito.
  4. Depois de LPWSPBind em um soquete sem conexão. FD_WRITE pode ou não ocorrer neste momento (dependente da implementação). De qualquer forma, um soquete sem conexão é sempre gravável imediatamente após LPWSPBind .

FD_OOB (válido somente quando SO_OOBINLINE LPWSPSetSockOpt estiver desabilitado (padrão))

  1. Quando LPWSPAsyncSelect é chamado, se houver dados OOB disponíveis no momento para receber com o sinalizador MSG_OOB.
  2. Quando os dados do OOB chegarem, se ainda não FD_OOB postados.
  3. Após LPWSPRecv ou LPWSPRecvFrom é chamado com ou sem sinalizador de MSG_OOB, se os dados OOB ainda estiverem disponíveis para receber.

FD_ACCEPT

  1. Quando LPWSPAsyncSelect é chamado, se houver atualmente uma solicitação de conexão disponível para aceitar.
  2. Quando uma solicitação de conexão chega, se ainda não FD_ACCEPT postado.
  3. Depois de LPWSPAccept é chamado, se houver outra solicitação de conexão disponível para aceitar.

FD_CONNECT

  1. Quando LPWSPAsyncSelect é chamado, se houver uma conexão estabelecida no momento.
  2. Depois de LPWSPConnect é chamado, quando a conexão é estabelecida (mesmo quando LPWSPConnect é bem-sucedida imediatamente, como é típico com um soquete de datagram) e mesmo quando ela falha imediatamente).
  3. Após WSPJoinLeaf é chamado, quando a operação de junção é concluída.
  4. Depois que de conexão, WSAConnect ou WSPJoinLeaf foi chamado com um soquete sem bloqueio orientado à conexão. A operação inicial retornou com um erro específico de WSAEWOULDBLOCK, mas a operação de rede foi adiante. Se a operação eventualmente tiver êxito ou não, quando o resultado tiver sido determinado, FD_CONNECT ocorrerá. O cliente deve verificar o código de erro para determinar se o resultado foi um êxito ou uma falha.

FD_CLOSE (válido somente em soquetes orientados à conexão (por exemplo, SOCK_STREAM))

  1. Quando LPWSPAsyncSelect for chamado, se a conexão do soquete tiver sido fechada.
  2. Depois que o sistema remoto iniciou um fechamento normal, quando nenhum dado está disponível no momento para receber (se os dados tiverem sido recebidos e estiverem aguardando para serem lidos quando o sistema remoto iniciar um fechamento normal, o FD_CLOSE não será entregue até que todos os dados pendentes sejam lidos).
  3. Depois que o sistema local inicia um fechamento normal com LPWSPShutdown e o sistema remoto respondeu com uma notificação de de fim de dados (como o TCP FIN), quando nenhum dado está disponível para receber no momento.
  4. Quando o sistema remoto anula a conexão (por exemplo, enviou TCP RST) e lParam conterá o valor de erro WSAECONNRESET.

FD_CLOSE não é postado depois que LPWSPCloseSocket é chamado.

FD_QOS

  1. Quando LPWSPAsyncSelect é chamado, se o QOS associado ao soquete tiver sido alterado.
  2. Depois de LPWSPIoctl com SIO_GET_QOS é chamado, quando o QOS é alterado.

FD_GROUP_QOS

Reservado para uso futuro com grupos de soquetes:

  1. Quando LPWSPAsyncSelect é chamado, se o grupo QOS associado ao soquete tiver sido alterado.
  2. Depois de LPWSPIoctl com SIO_GET_GROUP_QOS é chamado, quando o grupo QOS é alterado.

FD_ROUTING_INTERFACE_CHANGE

  1. depois de LPWSPIoctl com SIO_ROUTING_INTERFACE_CHANGE é chamado, quando a interface local que deve ser usada para alcançar o destino especificado nas alterações IOCTL.

FD_ADDRESS_LIST_CHANGE

  1. após LPWSPIoctl com SIO_ADDRESS_LIST_CHANGE é chamada, quando a lista de endereços locais aos quais o cliente SPI do Windows Sockets pode associar alterações.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows 10 Build 20348
servidor com suporte mínimo Windows 10 Build 20348
cabeçalho ws2spi.h

Consulte também

função de retorno de chamada LPWSPAsyncSelect