função select (winsock2.h)
A função select determina o status de um ou mais soquetes, aguardando, se necessário, para executar E/S síncrona.
Sintaxe
int WSAAPI select(
[in] int nfds,
[in, out] fd_set *readfds,
[in, out] fd_set *writefds,
[in, out] fd_set *exceptfds,
[in] const timeval *timeout
);
Parâmetros
[in] nfds
Ignorado. O parâmetro nfds é incluído apenas para compatibilidade com soquetes berkeley.
[in, out] readfds
Um ponteiro opcional para um conjunto de soquetes a ser verificado quanto à legibilidade.
[in, out] writefds
Um ponteiro opcional para um conjunto de soquetes a serem verificados quanto à capacidade de gravação.
[in, out] exceptfds
Um ponteiro opcional para um conjunto de soquetes a serem verificados quanto a erros.
[in] timeout
O tempo máximo para selecionar aguardar, fornecido na forma de uma estrutura TIMEVAL . Defina o parâmetro de tempo limite como nulo para operações de bloqueio.
Retornar valor
A função select retorna o número total de identificadores de soquete que estão prontos e contidos nas estruturas fd_set , zero se o limite de tempo expirou ou SOCKET_ERROR se ocorreu um erro. Se o valor retornado for SOCKET_ERROR, WSAGetLastError poderá ser usado para recuperar um código de erro específico.
| Código do erro | Significado |
|---|---|
| Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função. | |
| A implementação do Windows Sockets não pôde alocar os recursos necessários para suas operações internas ou os readfds, writefds, exceptfds ou parâmetros timeval não fazem parte do espaço de endereço do usuário. | |
| O subsistema de rede falhou. | |
| O valor de tempo limite não é válido ou todos os três parâmetros de descritor eram nulos. | |
| Uma chamada do Windows Socket 1.1 de bloqueio foi cancelada por meio de WSACancelBlockingCall. | |
| Uma chamada do Windows Sockets 1.1 de bloqueio está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada. | |
| Um dos conjuntos de descritores contém uma entrada que não é um soquete. |
Comentários
A função select é usada para determinar o status de um ou mais soquetes. Para cada soquete, o chamador pode solicitar informações sobre leitura, gravação ou erro status. O conjunto de soquetes para o qual um determinado status é solicitado é indicado por uma estrutura fd_set. Os soquetes contidos nas estruturas de fd_set devem ser associados a um único provedor de serviços. Para fins dessa restrição, soquetes serão considerados do mesmo provedor de serviços se as estruturas de WSAPROTOCOL_INFO que descrevem seus protocolos tiverem o mesmo valor providerId . Após o retorno, as estruturas são atualizadas para refletir o subconjunto desses soquetes que atendem à condição especificada. A função select retorna o número de soquetes que atendem às condições. Um conjunto de macros é fornecido para manipular uma estrutura fd_set . Essas macros são compatíveis com as usadas no software Berkeley, mas a representação subjacente é completamente diferente.
O parâmetro readfds identifica os soquetes que devem ser verificados quanto à legibilidade. Se o soquete estiver atualmente no estado de escuta , ele será marcado como legível se uma solicitação de conexão de entrada tiver sido recebida de modo que uma aceitação seja concluída sem bloqueio. Para outros soquetes, a legibilidade significa que os dados enfileirados estão disponíveis para leitura de modo que uma chamada para recv, WSARecv, WSARecvFrom ou recvfrom não seja bloqueada.
Para soquetes orientados à conexão, a legibilidade também pode indicar que uma solicitação para fechar o soquete foi recebida do par. Se o circuito virtual foi fechado normalmente e todos os dados foram recebidos, um recv retornará imediatamente com zero bytes lidos. Se o circuito virtual tiver sido redefinido, um recv será concluído imediatamente com um código de erro, como WSAECONNRESET. A presença de dados OOB será verificada se a opção de soquete SO_OOBINLINE tiver sido habilitada (consulte setsockopt).
O parâmetro writefds identifica os soquetes que devem ser verificados quanto à capacidade de gravação. Se um soquete estiver processando uma chamada de conexão (sem bloqueio), um soquete será gravável se o estabelecimento de conexão for concluído com êxito. Se o soquete não estiver processando uma chamada de conexão , a gravabilidade significará que um send, sendto ou WSASendto terá êxito . No entanto, eles poderão bloquear em um soquete de bloqueio se o parâmetro len exceder a quantidade de espaço de buffer do sistema de saída disponível. Não é especificado quanto tempo essas garantias podem ser consideradas válidas, especialmente em um ambiente multithread.
O parâmetro exceptfds identifica os soquetes que devem ser verificados quanto à presença de dados OOB ou quaisquer condições de erro excepcionais.
Em resumo, um soquete será identificado em um determinado conjunto quando select retornar se:
readfds:
- Se a escuta tiver sido chamada e uma conexão estiver pendente, accept terá êxito.
- Os dados estarão disponíveis para leitura (inclui dados OOB se SO_OOBINLINE estiver habilitado).
- A conexão foi fechada/redefinida/encerrada.
- Se estiver processando uma chamada de conexão (sem bloqueio), a conexão terá sido bem-sucedida.
- Os dados podem ser enviados.
- Se estiver processando uma chamada de conexão (sem bloqueio), houve falha na tentativa de conexão.
- Os dados OOB estão disponíveis para leitura (somente se SO_OOBINLINE estiver desabilitado).
- FD_ZERO(*set) – Inicializa definido como o conjunto vazio. Um conjunto sempre deve ser limpo antes de usar.
- FD_CLR(s, *set) – remove soquetes do conjunto.
- FD_ISSET(s, *set) – Verifica se s é um membro do conjunto e retorna TRUE se sim.
- FD_SET(s, *set) – adiciona soquetes a serem definidos.
O tempo limite do parâmetro controla quanto tempo a seleção pode levar para ser concluída. Se o tempo limite for um ponteiro nulo , select bloqueará indefinidamente até que pelo menos um descritor atenda aos critérios especificados. Caso contrário, o tempo limite aponta para uma estrutura TIMEVAL que especifica o tempo máximo que a seleção deve aguardar antes de retornar. Quando a seleção é retornada, o conteúdo da estrutura TIMEVAL não é alterado. Se TIMEVAL for inicializado como {0, 0}, selecione retornará imediatamente; isso é usado para sondar o estado dos soquetes selecionados. Se select retornar imediatamente, a chamada de seleção será considerada não desbloqueado e as suposições padrão para o não bloqueio de chamadas se aplicam. Por exemplo, o gancho de bloqueio não será chamado e os Soquetes do Windows não renderão.
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
| Cliente mínimo com suporte | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |