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

Artigo
03/04/2024

A função LPWSPSetSockOpt define uma opção de soquete.

Sintaxe

LPWSPSETSOCKOPT Lpwspsetsockopt;

int Lpwspsetsockopt(
  [in]  SOCKET s,
  [in]  int level,
  [in]  int optname,
  [in]  const char *optval,
  [in]  int optlen,
  [out] LPINT lpErrno
)
{...}

Parâmetros

[in] s

O descritor que identifica um soquete.

[in] level

O nível no qual a opção é definida; os níveis com suporte incluem SOL_SOCKET. Para obter mais informações, consulte Anexos winsock.

[in] optname

A opção de soquete para a qual o valor deve ser definido.

[in] optval

Um ponteiro para o buffer no qual o valor da opção solicitada é fornecido.

[in] optlen

O tamanho, em bytes, do buffer optval .

[out] lpErrno

Um ponteiro para o código de erro.

Retornar valor

Se nenhum erro ocorrer, LPWSPSetSockOpt retornará zero. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico estará disponível em lpErrno.

Código do Erro	Significado
WSAENETDOWN	O subsistema de rede falhou.
WSAEFAULT	O optval não está em uma parte válida do espaço de endereço do processo ou o parâmetro optlen é muito pequeno.
WSAEINPROGRESS	A função é invocada quando um retorno de chamada está em andamento.
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.
WSAEINVAL	O nível não é válido ou as informações em optval não são válidas.
WSAENETRESET	A conexão foi interrompida porque a atividade de manutenção de funcionamento detectou uma falha enquanto a operação estava em andamento.
WSAENOPROTOOPT	A opção é desconhecida ou não tem suporte para o provedor especificado.
WSAENOTCONN	A conexão foi redefinida quando SO_KEEPALIVE está definido.
WSAENOTSOCK	O descritor não é um soquete.

Comentários

A função LPWSPSetSockOpt define o valor atual para uma opção de soquete associada a um soquete de qualquer tipo, em qualquer estado. Embora as opções possam existir em vários níveis de protocolo, elas estão sempre presentes no nível superior do soquete. As opções afetam as operações de soquete, como se as mensagens de difusão podem ser enviadas no soquete.

Há dois tipos de opções de soquete: opções boolianas que habilitam ou desabilitam um recurso ou comportamento e opções que exigem um valor inteiro ou uma estrutura. Para habilitar uma opção booliana, optval aponta para um inteiro diferente de zero. Para desabilitar a opção, optval aponta para um inteiro igual a zero. O parâmetro optlen deve ser igual a sizeof (int) para opções boolianas. Para outras opções, optval aponta para um inteiro ou estrutura que contém o valor desejado para a opção e optlen é o comprimento do inteiro ou estrutura.

Para obter mais informações sobre opções de soquete, consulte Opções de soquete.

level = SOL_SOCKET

Valor	Type	Significado
SO_BROADCAST	BOOL	Habilita a transmissão e o recebimento de mensagens de difusão no soquete.
SO_DEBUG	BOOL	Registra informações de depuração.
SO_DONTLINGER	BOOL	Reservado.
SO_DONTROUTE	BOOL	Roteamento desabilitado: enviar diretamente para uma interface. A definição dessa opção de soquete é bem-sucedida, mas é ignorada em soquetes AF_INET; falha em soquetes AF_INET6 com WSAENOPROTOOPT . Não há suporte para essa opção em soquetes atm (resulta em um erro).
SO_GROUP_PRIORITY	INT	Reservado.
SO_KEEPALIVE	BOOL	Envia keep alives. Sem suporte em soquetes atm (resulta em um erro).
SO_LINGER	struct linger	Permanecerá próximo se os dados não recuos estiverem presentes.
SO_OOBINLINE	BOOL	Recebe dados OOB no fluxo de dados normal.
SO_RCVBUF	INT	Especifica o espaço de buffer por soquete total reservado para recebimentos. Isso não está relacionado a SO_MAX_MSG_SIZE e não corresponde necessariamente ao tamanho da janela de recebimento TCP.
SO_REUSEADDR	BOOL	Permite associar o soquete a um endereço que já está em uso. (Consulte Bind.) Não aplicável em soquetes de caixa eletrônico.
SO_SNDBUF	INT	Especifica o espaço de buffer por soquete total reservado para envios. Isso não está relacionado a SO_MAX_MSG_SIZE e não corresponde necessariamente ao tamanho de uma janela de envio TCP.
PVD_CONFIG	Dependente do Provedor de Serviços	Esse objeto armazena as informações de configuração para o provedor de serviços associado a soquetes s. O formato exato dessa estrutura de dados é específico do provedor de serviços.

Chamar LPWSPGetSockopt com uma opção sem suporte resultará em um código de erro de WSAENOPROTOOPT retornado em lpErrno.

SO_DEBUG

Os provedores de serviços do Windows Sockets são incentivados, mas não necessários, a fornecer informações de depuração de saída se a opção SO_DEBUG for definida por um cliente SPI do Windows Sockets. O mecanismo para gerar as informações de depuração e o formato estão além do escopo dessa especificação.

SO_GROUP_PRIORITY

Reservado.

SO_KEEPALIVE

Um cliente SPI do Windows Sockets pode solicitar que um provedor TCP/IP habilite o uso de pacotes keep alive em conexões TCP ativando a opção de soquete SO_KEEPALIVE . Um provedor do Windows Sockets não precisa dar suporte ao uso de keep alives: se isso acontecer, a semântica precisa é específica da implementação, mas deve estar em conformidade com a seção 4.2.3.6 do RFC 1122: Requisitos para hosts da Internet — Camadas de comunicação. (Esse recurso só pode estar disponível em inglês.) Se uma conexão for descartada como resultado de keep alive, o código de erro WSAENETRESET será retornado a qualquer chamada em andamento no soquete e as chamadas subsequentes falharão com WSAENOTCONN .

SO_LINGER

SO_LINGER controla a ação executada quando dados não solicitados são enfileirados em um soquete e um LPWSPCloseSocket é executado. Consulte LPWSPCloseSocket para obter uma descrição da maneira como as configurações de SO_LINGER afetam a semântica de LPWSPCloseSocket. O cliente SPI do Windows Sockets define o comportamento desejado criando uma estrutura LINGER , apontada pelo parâmetro optval , com os elementos a seguir.

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

Para habilitar SO_LINGER, um cliente SPI do Windows Sockets deve definir l_onoff como um valor diferente de zero, definir l_linger como zero ou o tempo limite desejado, em segundos, e chamar LPWSPSetSockOpt. Para habilitar SO_DONTLINGER, ou seja, desabilitar SO_LINGER, l_onoff deve ser definido como zero e LPWSPSetSockOpt deve ser chamado. Lembre-se de que não é recomendável habilitar SO_LINGER com um tempo limite diferente de zero em um soquete sem bloqueio. Para obter mais informações, consulte LPWSPCloseSocket.

Habilitar SO_LINGER também desabilita SO_DONTLINGER e vice-versa. Lembre-se de que, se SO_DONTLINGER estiver desabilitada (ou seja, SO_LINGER estiver habilitada), nenhum valor de tempo limite será especificado. Nesse caso, o tempo limite usado depende da implementação. Se um tempo limite anterior tiver sido estabelecido para um soquete (habilitando SO_LINGER), esse valor de tempo limite deverá ser restabelecido pelo provedor de serviços.

SO_REUSEADDR

Por padrão, um soquete não pode ser associado (para obter mais informações, consulte LPWSPBind) a um endereço local que já está em uso. Às vezes, no entanto, pode ser desejável reutilizar um endereço dessa forma. Como cada conexão é identificada exclusivamente pela combinação de endereços locais e remotos, não há problema em ter dois soquetes associados ao mesmo endereço local, desde que os endereços remotos sejam diferentes. Para informar ao provedor do Windows Sockets que um LPWSPBind em um soquete deve ter permissão para associar a um endereço local que já está em uso por outro soquete, o cliente SPI do Windows Sockets deve definir a opção de soquete SO_REUSEADDR para o soquete antes de emitir o LPWSPBind. Lembre-se de que a opção é interpretada somente no momento do LPWSPBind: portanto, é desnecessária, mas inofensiva, definir a opção em um soquete que não deve ser associado a um endereço existente e definir ou redefinir a opção depois que o LPWSPBind não tiver efeito sobre esse ou qualquer outro soquete.

SO_SNDBUF

Quando uma implementação do Windows Sockets dá suporte às opções SO_RCVBUF e SO_SNDBUF , um cliente SPI do Windows Sockets pode solicitar tamanhos de buffer diferentes (maiores ou menores). A chamada pode ter êxito mesmo que o provedor de serviços não tenha disponibilizado todo o valor solicitado. Um cliente SPI do Windows Sockets deve chamar LPWSPGetSockopt com a mesma opção para verificar o tamanho do buffer realmente fornecido.

PVD_CONFIG

Esse objeto armazena as informações de configuração para o provedor de serviços associado a soquetes. O formato exato dessa estrutura de dados é específico do provedor de serviços.

Requisitos

Requisito	Valor
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