Função WSAPoll (winsock2.h)

A função WSAPoll determina status de um ou mais soquetes.

Sintaxe

int WSAAPI WSAPoll(
  [in, out] LPWSAPOLLFD fdArray,
  [in]      ULONG       fds,
  [in]      INT         timeout
);

Parâmetros

[in, out] fdArray

Uma matriz de uma ou mais estruturas POLLFD especificando o conjunto de soquetes para o qual status é solicitado. A matriz deve conter pelo menos uma estrutura com um soquete válido. Após o retorno, esse parâmetro recebe os soquetes atualizados com os revents status membro flags definidos em cada um que corresponda aos critérios de consulta status.

[in] fds

O número de estruturas WSAPOLLFD em fdarray. Esse não é necessariamente o número de soquetes para os quais status é solicitado.

[in] timeout

Um valor que especifica o comportamento de espera, com base nos valores a seguir.

Valor	Significado
Maior que zero	O tempo, em milissegundos, para esperar.
Zero	Retornar imediatamente.
Menor que zero	Aguarde indefinidamente.

Retornar valor

Retorna um dos valores a seguir.

Valor retornado	Descrição
Zero	Nenhum soquete estava no estado consultado antes do temporizador expirar.
Maior que zero	O número de elementos em fdarray para os quais um membro revents da estrutura POLLFD é diferente de zero.
SOCKET_ERROR	Ocorreu um erro. Chame a função WSAGetLastError para recuperar o código de erro estendido.

 

Código de erro estendido	Significado
WSAENETDOWN	O subsistema de rede falhou.
WSAEFAULT	Ocorreu uma exceção ao ler parâmetros de entrada do usuário.
WSAEINVAL	Um parâmetro inválido foi passado. Esse erro será retornado se as estruturas WSAPOLLFD apontadas pelo parâmetro fdarray ao solicitar status de soquete. Esse erro também será retornado se nenhum dos soquetes especificados no membro fd de qualquer uma das estruturas WSAPOLLFD apontadas pelo parâmetro fdarray forem válidos.
WSAENOBUFS	A função não pôde alocar memória suficiente.

Comentários

A função WSAPoll é definida no Windows Vista e posterior.

As estruturas WSAPOLLFD . Um aplicativo define os sinalizadores apropriados no membro de eventos da estrutura WSAPOLLFD para especificar o tipo de status solicitado para cada soquete correspondente. A função WSAPoll retorna o status de um soquete no membro revents da estrutura WSAPOLLFD.

Para cada soquete, um chamador pode solicitar informações sobre status de leitura ou gravação. As condições de erro sempre são retornadas, portanto, as informações sobre elas não precisam ser solicitadas.

A estrutura WSAPOLLFD apontada pelo parâmetro fdarray . Todos os soquetes que não atendem a esses critérios e não têm nenhuma condição de erro terão o membro revents correspondente definido como 0.

Uma combinação dos seguintes sinalizadores pode ser definida na estrutura WSAPOLLFD para um determinado soquete ao solicitar status para esse soquete:

Sinalizador	Descrição
POLLPRI	Os dados prioritários podem ser lidos sem bloqueio. Esse sinalizador não é compatível com o provedor do Microsoft Winsock.
POLLRDBAND	Os dados de banda prioritária (fora de banda) podem ser lidos sem bloqueio.
POLLRDNORM	Os dados normais podem ser lidos sem bloqueio.
POLLWRNORM	Dados normais podem ser gravados sem bloqueio.

 

O sinalizador POLLIN é definido como a combinação dos valores de sinalizador POLLRDNORM e POLLRDBAND . O sinalizador POLLOUT é definido como o mesmo que o valor do sinalizador POLLWRNORM .

A estrutura WSAPOLLFD deve conter apenas uma combinação dos sinalizadores acima compatíveis com o provedor Winsock. Quaisquer outros valores são considerados erros e WSAPoll retornará SOCKET_ERROR. Uma chamada subsequente para a função WSAGetLastError recuperará o código de erro estendido de WSAEINVAL. Se o sinalizador POLLPRI estiver definido em um soquete para o provedor do Microsoft Winsock, a função WSAPoll falhará.

Quando as estruturas WSAPOLLFD apontadas pelo parâmetro fdarray para indicar o soquete status:

Sinalizador	Descrição
POLLERR	Ocorreu um erro.
POLLHUP	Uma conexão orientada a fluxo foi desconectada ou anulada.
POLLNVAL	Um soquete inválido foi usado.
POLLPRI	Os dados prioritários podem ser lidos sem bloqueio. Esse sinalizador não é retornado pelo provedor do Microsoft Winsock.
POLLRDBAND	Os dados de banda prioritária (fora de banda) podem ser lidos sem bloqueio.
POLLRDNORM	Os dados normais podem ser lidos sem bloqueio.
POLLWRNORM	Dados normais podem ser gravados sem bloqueio.

 

Em relação aos soquetes TCP e UDP:

• Estrutura WSAPOLLFD como dados normais como POLLRDNORM.
• Estrutura WSAPOLLFD , uma operação de recv subsequente tem a garantia de ser concluída sem bloqueio.
• Estrutura WSAPOLLFD por POLLWRNORM.
• Estrutura WSAPOLLFD por POLLRDNORM. Uma chamada subsequente a aceitar tem a garantia de ser concluída sem bloqueio.
• Estrutura WSAPOLLFD por POLLRDBAND.
• Estrutura WSAPOLLFD quando um par remoto desliga uma operação de envio (um FIN TCP foi recebido). Uma solicitação de função recv subsequente retornará zero bytes.
• Estrutura WSAPOLLFD quando o par remoto inicia uma desconexão normal.
• Estrutura WSAPOLLFD retornada quando um par remoto se desconecta repentinamente.
• Estrutura WSAPOLLFD quando o soquete local é fechado.

O número de elementos (não soquetes) em fdarray é indicado por nfds. Os membros da fdarray que têm seu membro fd definido como um valor negativo são ignorados e seus revents serão definidos como POLLNVAL após o retorno. Esse comportamento é útil para um aplicativo que mantém uma alocação de fdarray fixa e não compacta a matriz para remover entradas não utilizados ou realocar a memória. Não é necessário limpar revents para qualquer elemento antes de chamar WSAPoll.

O argumento timeout especifica quanto tempo a função deve aguardar antes de retornar. Um valor positivo contém o número de milissegundos a aguardar antes de retornar. Um valor zero força wsapoll a retornar imediatamente, e um valor negativo indica que WSAPoll deve esperar indefinidamente.

Nota Ao emitir uma chamada winsock de bloqueio, como WSAPoll , com o parâmetro de tempo limite definido como um número negativo, Winsock pode precisar esperar por um evento de rede antes que a chamada possa ser concluída. O Winsock executa uma espera alertável nessa situação, que pode ser interrompida por uma APC (chamada de procedimento assíncrona) agendada no mesmo thread. Emitir outra chamada winsock de bloqueio dentro de um APC que interrompeu uma chamada Winsock de bloqueio contínuo no mesmo thread levará a um comportamento indefinido e nunca deve ser tentado pelos clientes winsock.

 

Nota A partir de Windows 10 versão 2004, quando um soquete TCP falha ao se conectar, (POLLHUP \| POLLERR \| POLLWRNORM) é indicado.

 

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winsock2.h (inclua Winsock2.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll

Confira também

Wsagetlasterror

WSAPOLLFD