função select (winsock2.h)

Artigo
11/15/2023

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
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAEFAULT	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.
WSAENETDOWN	O subsistema de rede falhou.
WSAEINVAL	O valor de tempo limite não é válido ou todos os três parâmetros de descritor eram nulos.
WSAEINTR	Uma chamada do Windows Socket 1.1 de bloqueio foi cancelada por meio de WSACancelBlockingCall.
WSAEINPROGRESS	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.
WSAENOTSOCK	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.

Nota Os dados fora de banda só serão relatados dessa forma se a opção SO_OOBINLINE for FALSE. Se um soquete estiver processando uma chamada de conexão (sem bloqueio), a falha da tentativa de conexão será indicada em exceptfds (o aplicativo deve chamar getsockopt SO_ERROR para determinar o valor do erro para descrever por que a falha ocorreu). Este documento não define quais outros erros serão incluídos.

Qualquer um dos dois parâmetros, readfds, writefds ou exceptfds, pode ser dado como nulo. Pelo menos um deve ser não nulo e qualquer conjunto de descritor não nulo deve conter pelo menos um identificador para um soquete.

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.

writefds:

Se estiver processando uma chamada de conexão (sem bloqueio), a conexão terá sido bem-sucedida.
Os dados podem ser enviados.

exceptfds:

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).

Quatro macros são definidas no arquivo de cabeçalho Winsock2.h para manipular e verificar os conjuntos de descritores. A variável FD_SETSIZE determina o número máximo de descritores em um conjunto. (O valor padrão de FD_SETSIZE é 64, que pode ser modificado definindo FD_SETSIZE para outro valor antes de incluir Winsock2.h.) Internamente, os identificadores de soquete em uma estrutura de fd_set não são representados como sinalizadores de bits como no Berkeley Unix. Sua representação de dados é opaca. O uso dessas macros manterá a portabilidade do software entre diferentes ambientes de soquete. As macros para manipular e marcar conteúdo fd_set são:

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.

Nota A função select não tem efeito sobre a persistência de eventos de soquete registrados com WSAAsyncSelect ou WSAEventSelect.

Nota Ao emitir uma chamada winsock de bloqueio, como selecionar com o parâmetro de tempo limite definido como NULL, Winsock pode precisar aguardar 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.

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

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