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

Artigo
03/15/2023

A função LPWSPAccept aceita condicionalmente uma conexão com base no valor retornado de uma função de condição.

Sintaxe

LPWSPACCEPT Lpwspaccept;

SOCKET Lpwspaccept(
  [in]      SOCKET s,
  [out]     sockaddr *addr,
  [in, out] LPINT addrlen,
  [in]      LPCONDITIONPROC lpfnCondition,
  [in]      DWORD_PTR dwCallbackData,
  [out]     LPINT lpErrno
)
{...}

Parâmetros

[in] s

Descritor que identifica um soquete que está escutando conexões após um LPWSPListen.

[out] addr

Ponteiro opcional para um buffer que recebe o endereço da entidade de conexão, conforme conhecido pelo provedor de serviços. O formato exato do parâmetro addr é determinado pela família de endereços estabelecida quando o soquete na estrutura sockaddr foi criado.

[in, out] addrlen

Ponteiro opcional para um inteiro que contém o comprimento do parâmetro addr , em bytes.

[in] lpfnCondition

Endereço da instância de procedimento de uma função de condição opcional fornecida pelo Windows Sockets. Essa função é usada na decisão de aceitar ou rejeitar com base nas informações do chamador passadas como parâmetros.

[in] dwCallbackData

Dados de retorno de chamada a serem passados de volta para o cliente do Windows Socket 2 como o valor do parâmetro dwCallbackData da função de condição. Esse parâmetro não é interpretado pelo provedor de serviços.

[out] lpErrno

Ponteiro para o código de erro.

Valor retornado

Se nenhum erro ocorrer, LPWSPAccept retornará um valor do tipo SOCKET que é um descritor para o soquete aceito. Caso contrário, um valor de INVALID_SOCKET será retornado e um código de erro específico estará disponível em lpErrno.

Código do Erro	Significado
WSAECONNREFUSED	A solicitação de conexão foi rejeitada com força, conforme indicado no valor retornado da função de condição (CF_REJECT).
WSAECONNRESET	Uma conexão de entrada foi indicada, mas foi posteriormente encerrada pelo par remoto antes de aceitar a chamada.
WSAENETDOWN	O subsistema de rede falhou.
WSAEFAULT	O parâmetro addrlen é muito pequeno ou o parâmetro lpfnCondition não faz parte do espaço de endereço do usuário.
WSAEINTR	Uma chamada (bloqueio) foi cancelada por meio de LPWSPCancelBlockingCall.
WSAEINPROGRESS	Uma chamada de Bloqueio do Windows Sockets está em andamento.
WSAEINVAL	LPWSPListen não foi invocado antes de LPWSPAccept, o parâmetro g especificado na função de condição não é um valor válido, o valor retornado da função condição não é válido ou qualquer caso em que o soquete especificado esteja em um estado inválido.
WSAEMFILE	A fila não é vazia após a entrada para LPWSPAccept e não há descritores de soquete disponíveis.
WSAENOBUFS	Nenhum espaço de buffer disponível.
WSAENOTSOCK	O descritor não é um soquete.
WSAEOPNOTSUPP	O soquete referenciado não é um tipo que dá suporte ao serviço orientado à conexão.
WSATRY_AGAIN	A aceitação da solicitação de conexão foi adiada conforme indicado no valor retornado da função de condição (CF_DEFER).
WSAEWOULDBLOCK	O soquete é marcado como não desbloqueio e nenhuma conexão está presente para ser aceita.
WSAEACCES	A solicitação de conexão oferecida atingiu o tempo limite ou foi retirada.

Comentários

A função LPWSPAccept extrai a primeira conexão na fila de conexões pendentes no soquete s e verifica-a em relação à função de condição, desde que a função de condição seja especificada (ou seja, não nula). A função de condição deve ser executada no mesmo thread que essa rotina. Se a função de condição retornar CF_ACCEPT, LPWSPAccept criará um novo soquete.

Soquetes recém-criados têm as mesmas propriedades que os soquetes, incluindo eventos de rede registrados com LPWSPAsyncSelect ou com LPWSPEventSelect. Conforme descrito em DescriptorAllocation, quando novos descritores de soquete são alocados, os provedores IFS devem chamar WPUModifyIFSHandle e provedores não IFS devem chamar WPUCreateSocketHandle.

Se a função de condição retornar CF_REJECT, LPWSPAccept rejeitará a solicitação de conexão. Se a decisão de aceitação/rejeição do aplicativo não puder ser tomada imediatamente, a função de condição retornará CF_DEFER para indicar que nenhuma decisão foi tomada. Nenhuma ação sobre essa solicitação de conexão deve ser executada pelo provedor de serviços. Quando o aplicativo estiver pronto para executar uma ação na solicitação de conexão, ele invocará LPWSPAccept novamente e retornará CF_ACCEPT ou CF_REJECT como um valor retornado da função de condição.

Para soquetes que estão no modo de bloqueio (padrão), se nenhuma conexão pendente estiver presente na fila, LPWSPAccept bloqueará o chamador até que uma conexão esteja presente. Para soquetes no modo sem bloqueio, se essa função for chamada quando nenhuma conexão pendente estiver presente na fila, LPWSPAccept retornará o código de erro WSAEWOULDBLOCK. O soquete aceito não pode ser usado para aceitar mais conexões. O soquete original permanece aberto.

O complemento de parâmetro é um parâmetro de resultado que é preenchido com o endereço da entidade de conexão, conforme conhecido pelo provedor de serviços. O formato exato do parâmetro addr é determinado pela família de endereços na qual a comunicação está ocorrendo. O addrlen é um parâmetro value-result; inicialmente, ele conterá a quantidade de espaço apontada pelo complemento. No retorno, ele deve conter o comprimento real (em bytes) do endereço retornado pelo provedor de serviços. Essa chamada é usada com tipos de soquete orientados à conexão, como SOCK_STREAM. Se addr e/ou addrlen forem iguais a nulo, nenhuma informação sobre o endereço remoto do soquete aceito será retornada. Caso contrário, esses dois parâmetros deverão ser preenchidos independentemente de a função condição ser especificada ou o que ela retorna.

O protótipo da função de condição é o seguinte.

int CALLBACK 
ConditionFunc( 
  IN     LPWSABUF    lpCallerId, 
  IN     LPWSABUF    lpCallerData, 
  IN OUT LPQOS       lpSQOS, 
  IN OUT LPQOS       lpGQOS,
  IN     LPWSABUF    lpCalleeId, 
  IN     LPWSABUF    lpCalleeData, 
  OUT    GROUP FAR * g, 	
  IN     DWORD_PTR   dwCallbackData
);

O lpCallerId e o lpCallerData são parâmetros de valor que devem conter o endereço da entidade de conexão e todos os dados de usuário que foram enviados junto com a solicitação de conexão. Se nenhum identificador de chamador ou dados de chamador estiverem disponíveis, o parâmetro correspondente será nulo. Muitos protocolos de rede não dão suporte a dados de chamadas em tempo de conexão. Espera-se que a maioria dos protocolos de rede convencionais dê suporte a informações de identificador de chamador no momento da solicitação de conexão. A parte buf do WSABUF apontada por lpCallerId aponta para um sockaddr. O sockaddr é interpretado de acordo com sua família de endereços (normalmente convertendo o sockaddr em algum tipo específico para a família de endereços).

O parâmetro lpSQOS faz referência às especificações de fluxo para soquetes especificados pelo chamador, um para cada direção, seguido por quaisquer parâmetros adicionais específicos do provedor. Os valores de especificação de fluxo de envio ou recebimento serão ignorados conforme apropriado para quaisquer soquetes unidirecionais. Um valor nulo para lpSQOS indica que não há QoS fornecido pelo chamador e que nenhuma negociação é possível. Um ponteiro lpSQOS não NULL indica que uma negociação de QoS deve ocorrer ou que o provedor está preparado para aceitar a solicitação de QoS sem negociação.

O lpCalleeId é um parâmetro de valor que contém o endereço local da entidade conectada. A parte buf do WSABUF apontada por lpCalleeId aponta para um sockaddr. O sockaddr é interpretado de acordo com sua família de endereços (normalmente convertendo o sockaddr em algum tipo específico para a família de endereços).

O lpCalleeData é um parâmetro de resultado usado pela função de condição para fornecer dados do usuário de volta à entidade de conexão. O armazenamento para esses dados deve ser fornecido pelo provedor de serviços. O lpCalleeData-len> contém inicialmente o comprimento do buffer alocado pelo provedor de serviços e apontado por lpCalleeData-buf.> Um valor igual a zero significa não há suporte para a passagem de dados do usuário de volta para o chamador. A função condition copiará até lpCalleeData-len> bytes de dados em lpCalleeData-buf> e, em seguida, atualizará lpCalleeData-len> para indicar o número real de bytes transferidos. Se nenhum dado do usuário for passado de volta para o chamador, a função de condição definirá lpCalleeData-len> como zero. O formato de todos os dados de endereço e usuário é específico para a família de endereços à qual o soquete pertence.

O valor do parâmetro dwCallbackData passado para a função condition é o valor passado como o parâmetro dwCallbackData na chamada LPWSPAccept original. Esse valor é interpretado apenas pelo cliente do Windows Sockets 2. Isso permite que um cliente passe algumas informações de contexto do site de chamada LPWSPAccept para a função de condição, que fornece à função de condição quaisquer informações adicionais necessárias para determinar se a conexão deve ser aceita. Um uso típico é passar um ponteiro (conversão adequada) para uma estrutura de dados que contém referências a objetos definidos pelo aplicativo com os quais esse soquete está associado.

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]
Plataforma de Destino	Windows
Cabeçalho	ws2spi.h