Função setsockopt (winsock.h)

Artigo
08/27/2023

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

Sintaxe

int setsockopt(
  [in] SOCKET     s,
  [in] int        level,
  [in] int        optname,
  [in] const char *optval,
  [in] int        optlen
);

Parâmetros

[in] s

Um descritor que identifica um soquete.

[in] level

O nível no qual a opção é definida (por exemplo, SOL_SOCKET).

[in] optname

A opção de soquete para a qual o valor deve ser definido (por exemplo, SO_BROADCAST). O parâmetro optname deve ser uma opção de soquete definida dentro do nível especificado ou o comportamento é indefinido.

[in] optval

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

[in] optlen

O tamanho, em bytes, do buffer apontado pelo parâmetro optval .

Valor retornado

Se nenhum erro ocorrer, setsockopt retornará zero. Caso contrário, um valor de SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSAEFAULT	O buffer apontado pelo parâmetro 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	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.
WSAEINVAL	O parâmetro de nível não é válido ou as informações no buffer apontado pelo parâmetro optval não são válidas.
WSAENETRESET	A conexão atingiu o tempo limite quando SO_KEEPALIVE está definido.
WSAENOPROTOOPT	A opção é desconhecida ou sem suporte para o provedor ou soquete especificado (consulte limitações de SO_GROUP_PRIORITY).
WSAENOTCONN	A conexão foi redefinida quando SO_KEEPALIVE está definido.
WSAENOTSOCK	O descritor não é um soquete.

Comentários

A função setsockopt 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 os dados agilizados (dados OOB, por exemplo) são recebidos no fluxo de dados normal e se as mensagens de transmissão podem ser enviadas no soquete.

Nota Se a função setsockopt for chamada antes da função de associação , as opções TCP/IP não serão verificadas usando TCP/IP até que a associação ocorra. Nesse caso, a chamada de função setsockopt sempre terá êxito, mas a chamada de função de associação pode falhar devido a uma falha na chamada setsockopt antecipada.

Nota Se um soquete for aberto, uma chamada setsockopt será feita e, em seguida, uma chamada sendto será feita, o Windows Sockets executará uma chamada de função de associação implícita.

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 estrutura. Para habilitar uma opção booliana, o parâmetro optval aponta para um inteiro diferente de zero. Para desabilitar o optval points da opção 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.

As tabelas a seguir listam algumas das opções comuns compatíveis com a função setsockopt . A coluna Tipo identifica o tipo de dados endereçado pelo parâmetro optval . A coluna Descrição fornece algumas informações básicas sobre a opção soquete. Para obter listas mais completas de opções de soquete e informações mais detalhadas (valores padrão, por exemplo), consulte os tópicos detalhados em Opções de soquete.

Nível = SOL_SOCKET

Valor	Tipo	Descrição
SO_BROADCAST	BOOL	Configura um soquete para enviar dados de transmissão.
SO_CONDITIONAL_ACCEPT	BOOL	Permite que as conexões de entrada sejam aceitas ou rejeitadas pelo aplicativo, não pela pilha de protocolo.
SO_DEBUG	BOOL	Habilita a saída de depuração. Atualmente, os provedores da Microsoft não geram nenhuma informação de depuração.
SO_DONTLINGER	BOOL	Não bloqueia o fechamento aguardando o envio de dados não enviados. Definir essa opção é equivalente a definir SO_LINGER com l_onoff definido como zero.
SO_DONTROUTE	BOOL	Define se os dados de saída devem ser enviados na interface à qual o soquete está associado e não um roteado em alguma outra interface. Não há suporte para essa opção em soquetes atm (resulta em um erro).
SO_GROUP_PRIORITY	INT	Reservado.
SO_KEEPALIVE	BOOL	Habilita o envio de pacotes keep alive para uma conexão de soquete. Sem suporte em soquetes atm (resulta em um erro).
SO_LINGER	DEMORAR	Permanecerá próximo se dados não solicitados estiverem presentes.
SO_OOBINLINE	BOOL	Indica que os dados fora do limite devem ser retornados em linha com os dados regulares. Essa opção só é válida para protocolos orientados a conexões que dão suporte a dados fora de banda. Para obter uma discussão sobre este tópico, consulte Dados fora de banda independentes do protocolo.
SO_RCVBUF	INT	Especifica o espaço de buffer por soquete total reservado para recebimentos.
SO_REUSEADDR	BOOL	Permite associar o soquete a um endereço que já está em uso. Para obter mais informações, consulte bind. Não aplicável em soquetes atm.
SO_EXCLUSIVEADDRUSE	BOOL	Permite limitar um soquete para acesso exclusivo. Não requer privilégio administrativo.
SO_RCVTIMEO	DWORD	Define o tempo limite, em milissegundos, para bloquear chamadas de recebimento.
SO_SNDBUF	INT	Especifica o espaço de buffer por soquete total reservado para envios.
SO_SNDTIMEO	DWORD	O tempo limite, em milissegundos, para bloquear chamadas de envio.
SO_UPDATE_ACCEPT_CONTEXT	INT	Atualizações o soquete de aceitação com o contexto do soquete de escuta.
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.

Para obter informações mais completas e detalhadas sobre opções de soquete paraSOL_SOCKET de nível = , consulte Opções de soquete SOL_SOCKET.

Nível = IPPROTO_TCP

Consulte TCP_NODELAY em IPPROTO_TCP opções de soquete. Consulte também esse tópico para obter informações mais completas e detalhadas sobre as opções desoquete para IPPROTO_TCP de nível = .

Nível = NSPROTO_IPX

Valor	Tipo	Descrição
IPX_PTYPE	INT	Define o tipo de pacote IPX.
IPX_FILTERPTYPE	INT	Define o tipo de pacote de filtro de recebimento
IPX_STOPFILTERPTYPE	INT	Interrompe a filtragem do tipo de filtro definido com IPX_FILTERTYPE
IPX_DSTYPE	INT	Define o valor do campo de fluxo de dados no cabeçalho SPX em cada pacote enviado.
IPX_EXTENDED_ADDRESS	BOOL	Define se o endereçamento estendido está habilitado.
IPX_RECVHDR	BOOL	Define se o cabeçalho do protocolo é enviado em todos os cabeçalhos de recebimento.
IPX_RECEIVE_BROADCAST	BOOL	Indica que os pacotes de difusão provavelmente estão no soquete. Defina como TRUE por padrão. Os aplicativos que não usam transmissões devem definir isso como FALSE para melhorar o desempenho do sistema.
IPX_IMMEDIATESPXACK	BOOL	Direciona as conexões SPX para não atrasarem antes de enviar um ACK. Aplicativos sem tráfego de ida e volta devem definir isso como TRUE para aumentar o desempenho.

Para obter informações mais completas e detalhadas sobre opções de soquete paraNSPROTO_IPX de nível = , consulte Opções de soquete NSPROTO_IPX.

As opções BSD sem suporte para setsockopt são mostradas na tabela a seguir.

Valor	Tipo	Descrição
SO_ACCEPTCONN	BOOL	Retorna se um soquete está no modo de escuta. Essa opção é válida apenas para protocolos orientados a conexão. Não há suporte para essa opção de soquete para a configuração.
SO_RCVLOWAT	INT	Uma opção de soquete do BSD UNIX incluída para compatibilidade com versões anteriores. Essa opção define o número mínimo de bytes a serem processados para operações de entrada de soquete.
SO_SNDLOWAT	INT	Uma opção de soquete do BSD UNIX incluída para compatibilidade com versões anteriores. Essa opção define o número mínimo de bytes a serem processados para operações de saída de soquete.
SO_TYPE	INT	Retorna o tipo de soquete para o soquete fornecido (SOCK_STREAM ou SOCK_DGRAM, por exemplo Esta opção de soquete não tem suporte para a configuração do tipo de soquete.

Nota Ao emitir uma chamada winsock de bloqueio, como setsockopt, o 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íncrono) agendada no mesmo thread. A emissão de 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 tentada por clientes Winsock.

Código de exemplo

O exemplo a seguir demonstra a função setsockopt .

#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main()
{

    //---------------------------------------
    // Declare variables
    WSADATA wsaData;

    SOCKET ListenSocket;
    sockaddr_in service;

    int iResult = 0;

    BOOL bOptVal = FALSE;
    int bOptLen = sizeof (BOOL);

    int iOptVal = 0;
    int iOptLen = sizeof (int);

    //---------------------------------------
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"Error at WSAStartup()\n");
        return 1;
    }
    //---------------------------------------
    // Create a listening socket
    ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ListenSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %u\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //---------------------------------------
    // Bind the socket to the local IP address
    // and port 27015
    hostent *thisHost;
    char *ip;
    u_short port;
    port = 27015;
    thisHost = gethostbyname("");
    ip = inet_ntoa(*(struct in_addr *) *thisHost->h_addr_list);

    service.sin_family = AF_INET;
    service.sin_addr.s_addr = inet_addr(ip);
    service.sin_port = htons(port);

    iResult = bind(ListenSocket, (SOCKADDR *) & service, sizeof (service));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"bind failed with error %u\n", WSAGetLastError());
        closesocket(ListenSocket);
        WSACleanup();
        return 1;
    }
    //---------------------------------------
    // Initialize variables and call setsockopt. 
    // The SO_KEEPALIVE parameter is a socket option 
    // that makes the socket send keepalive messages
    // on the session. The SO_KEEPALIVE socket option
    // requires a boolean value to be passed to the
    // setsockopt function. If TRUE, the socket is
    // configured to send keepalive messages, if FALSE
    // the socket configured to NOT send keepalive messages.
    // This section of code tests the setsockopt function
    // by checking the status of SO_KEEPALIVE on the socket
    // using the getsockopt function.

    bOptVal = TRUE;

    iResult = getsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &iOptVal, &iOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"getsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"SO_KEEPALIVE Value: %ld\n", iOptVal);

    iResult = setsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &bOptVal, bOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"setsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"Set SO_KEEPALIVE: ON\n");

    iResult = getsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &iOptVal, &iOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"getsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"SO_KEEPALIVE Value: %ld\n", iOptVal);

    closesocket(ListenSocket);
    WSACleanup();
    return 0;
}

Notas para soquetes IrDA

Ao desenvolver aplicativos usando soquetes do Windows para IrDA, observe o seguinte:

O arquivo de cabeçalho Af_irda.h deve ser incluído explicitamente.
O IrDA fornece a seguinte opção de soquete:

Valor Type Significado

IRLMP_IAS_SET *IAS_SET Define atributos IAS

Valor	Type	Significado
IRLMP_IAS_SET	*IAS_SET	Define atributos IAS

A opção de soquete IRLMP_IAS_SET permite que o aplicativo defina um único atributo de uma única classe no IAS local. O aplicativo especifica a classe a ser definida, o atributo e o tipo de atributo. Espera-se que o aplicativo aloque um buffer do tamanho necessário para os parâmetros passados.

O IrDA fornece um banco de dados IAS que armazena informações baseadas em IrDA. O acesso limitado ao banco de dados IAS está disponível por meio da interface do Windows Sockets 2, mas esse acesso normalmente não é usado por aplicativos e existe principalmente para dar suporte a conexões com dispositivos não Windows que não estão em conformidade com as convenções de IrDA do Windows Sockets 2.

A seguinte estrutura, IAS_SET, é usada com a opção IRLMP_IAS_SET setsockopt para gerenciar o banco de dados IAS local:


// #include <Af_irda.h> for this struct

typedef struct _IAS_SET {
    u_char      irdaClassName[IAS_MAX_CLASSNAME];
    char      irdaAttribName[IAS_MAX_ATTRIBNAME];
    u_long    irdaAttribType;
    union
    {
              LONG irdaAttribInt;
              struct
              {
                   u_long   Len;
                   u_char    OctetSeq[IAS_MAX_OCTET_STRING];
              } irdaAttribOctetSeq;
              struct
              {
                   u_long    Len;
                   u_long    CharSet;
                   u_char    UsrStr[IAS_MAX_USER_STRING];
              } irdaAttribUsrStr;
    } irdaAttribute;
} IAS_SET, *PIAS_SET, FAR *LPIASSET;

A seguinte estrutura, IAS_QUERY, é usada com a opção IRLMP_IAS_QUERY setsockopt para consultar o banco de dados IAS de um par:


// #include <Af_irda.h> for this struct

typedef struct _WINDOWS_IAS_QUERY {
        u_char   irdaDeviceID[4];
        char     irdaClassName[IAS_MAX_CLASSNAME];
        char     irdaAttribName[IAS_MAX_ATTRIBNAME];
        u_long   irdaAttribType;
        union
        {
                  LONG    irdaAttribInt;
                  struct
                  {
                          u_long  Len;
                          u_char  OctetSeq[IAS_MAX_OCTET_STRING];
                  } irdaAttribOctetSeq;
                  struct
                  {
                          u_long  Len;
                          u_long  CharSet;
                          u_char  UsrStr[IAS_MAX_USER_STRING];
                  } irdaAttribUsrStr;
        } irdaAttribute;
} IAS_QUERY, *PIAS_QUERY, FAR *LPIASQUERY;

Muitas SO_ opções de soquete de nível não são significativas para o IrDA. Somente SO_LINGER tem suporte específico.

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

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	winsock.h (inclua Winsock2.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll