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:

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