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

Artigo
08/28/2023

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

Sintaxe

LPWSPSELECT Lpwspselect;

int Lpwspselect(
  [in]      int nfds,
  [in, out] fd_set *readfds,
  [in, out] fd_set *writefds,
  [in, out] fd_set *exceptfds,
  [in]      const timeval *timeout,
  [out]     LPINT lpErrno
)
{...}

Parâmetros

[in] nfds

Ignorado e incluído apenas para fins de compatibilidade.

[in, out] readfds

Ponteiro opcional para um conjunto de soquetes a serem verificados quanto à legibilidade.

[in, out] writefds

Ponteiro opcional para um conjunto de soquetes a serem verificados quanto à capacidade de gravação.

[in, out] exceptfds

Ponteiro opcional para um conjunto de soquetes a serem verificados quanto a erros.

[in] timeout

Tempo máximo para LPWSPSelect aguardar ou nulo para uma operação de bloqueio, na forma de uma estrutura de valor de tempo .

[out] lpErrno

Ponteiro para o código de erro.

Retornar valor

A função LPWSPSelect retorna o número total de descritores prontos e contidos nas estruturas fd_set ou SOCKET_ERROR se ocorreu um erro. Se o valor retornado for SOCKET_ERROR, um código de erro específico estará disponível no lpErrno.

Código do Erro	Significado
WSAEFAULT	O provedor de serviços do Windows Sockets não pôde alocar os recursos necessários para suas operações internas ou os readfds, writefds, exceptfds ou parâmetrostimeval 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 NULL.
WSAEINTR	A chamada (Bloqueio) foi cancelada por meio de LPWSPCancelBlockingCall.
WSAEINPROGRESS	O bloqueio da chamada do Windows Sockets 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

Essa função é 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. Todas as entradas em um fd_set correspondem aos soquetes criados pelo provedor de serviços (ou seja, as estruturas WSAPROTOCOL_INFO que descrevem seus protocolos têm o mesmo valor providerId ). Após o retorno, as estruturas são atualizadas para refletir o subconjunto desses soquetes que atendem à condição especificada e LPWSPSelect retorna o número total de soquetes que atendem às condições. Um conjunto de macros é fornecido para manipular um 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 escutando no momento por meio de LPWSPListen, ele será marcado como legível se uma solicitação de conexão de entrada tiver sido recebida, para que um LPWSPAccept seja concluído sem bloqueio. Para outros soquetes, a legibilidade significa que os dados enfileirados estão disponíveis para leitura para que um LPWSPRecv ou LPWSPRecvFrom não seja bloqueado.

Para soquetes orientados à conexão, a legibilidade também pode indicar que uma solicitação próxima foi recebida do par. Se o circuito virtual tiver sido fechado normalmente, um LPWSPRecv retornará imediatamente com zero bytes lidos. Se o circuito virtual tiver sido redefinido, um LPWSPRecv 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 LPWSPSetSockOpt).

O parâmetro writefds identifica os soquetes que devem ser verificados quanto à gravabilidade:

Se um soquete estiver se conectando por meio de LPWSPConnect, a capacidade de gravação significa que o estabelecimento de conexão foi concluído com êxito.
Se o soquete não estiver no processo de escuta por meio de LPWSPConnect, a capacidade de gravação significa que um LPWSPSend ou LPWSPSendTo tem a garantia de ter êxito.

No entanto, eles podem bloquear em um soquete de bloqueio se o 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 a quaisquer condições de erro excepcionais. Observe que os dados OOB só serão relatados dessa forma se a opção SO_OOBINLINE for FALSE. Se um soquete estiver fazendo uma conexão LPWSPConnect (sem bloqueio), a falha da tentativa de conexão será indicada em exceptfds. Essa especificação não define quais outros erros serão incluídos.

Qualquer um dos readfds, writefds ou exceptfds poderá ser dado como nulo se nenhum descritor for verificado quanto à condição de interesse. Pelo menos um deve ser não nulo e qualquer conjunto de descritor não nulo deve conter pelo menos um descritor de soquete.

Resumo: um soquete será identificado em um determinado conjunto quando LPWSPSelect retornar de acordo com o seguinte.

Parâmetro	Descrição
readfds:	Se LPWSPListen for chamado, uma conexão estará pendente, LPWSPAccept 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 LPWSPConnect (não desbloqueio), a conexão foi bem-sucedida. Os dados podem ser enviados.
exceptfds:	Se LPWSPConnect (não desbloqueio), a tentativa de conexão falhou. Os dados OOB estão disponíveis para leitura (somente se SO_OOBINLINE estiver desabilitado).

Três macros e uma função upcall são definidas no arquivo de cabeçalho Ws2spi.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 por #defining FD_SETSIZE para outro valor antes de #including Ws2spi.h.) Internamente, os identificadores de soquete em um 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_CLR(s, *set): Remove os descritores doconjunto.
FD_SET(s, *set): Adiciona descritores a serem definidos.
FD_ZERO(*set): Inicializa o conjunto como o conjunto nulo .

A função upcall usada para marcar a associação é:

intWPUFDIsSet (SOCKETs, FD_SET far *set);: que retornará diferente de zero se s for um membro do conjunto ou, caso contrário, zero.

O tempo limite do parâmetro controla quanto tempo o LPWSPSelect pode levar para ser concluído. Se o tempo limite for um ponteiro nulo , LPWSPSelect bloqueará indefinidamente até que pelo menos um descritor atenda aos critérios especificados. Caso contrário, o tempo limite aponta para uma estrutura de valor de tempo que especifica o tempo máximo que LPWSPSelect deve aguardar antes de retornar. Quando LPWSPSelect retorna, o conteúdo da estrutura timeval não é alterado. Se timeval for inicializado como {0, 0}, LPWSPSelect retornará imediatamente; isso é usado para sondar o estado dos soquetes selecionados. Se esse for o caso, a chamada LPWSPSelect será considerada não desbloqueado e as suposições padrão para chamadas não desbloqueadas se aplicam. Por exemplo, o gancho de bloqueio não será chamado e o provedor de Soquetes do Windows não produzirá.

Observação

A função LPWSPSelect não tem efeito sobre a persistência de eventos de soquete registrados com LPWSPAsyncSelect ou LPWSPEventSelect.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ws2spi.h