Função getsockopt (winsock.h)

A função getsockopt recupera uma opção de soquete.

Sintaxe

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

Parâmetros

[in] s

Um descritor que identifica um soquete.

[in] level

O nível no qual a opção é definida. Exemplo: SOL_SOCKET.

[in] optname

A opção de soquete para a qual o valor deve ser recuperado. Exemplo: SO_ACCEPTCONN. O valor optname deve ser uma opção de soquete definida dentro do nível especificado ou o comportamento é indefinido.

[out] optval

Um ponteiro para o buffer no qual o valor da opção solicitada deve ser retornado.

[in, out] optlen

Um ponteiro para o tamanho, em bytes, do buffer optval .

Retornar valor

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

Comentários

A função getsockopt recupera o valor atual de uma opção de soquete associada a um soquete de qualquer tipo, em qualquer estado, e armazena o resultado em optval. As opções podem existir em vários níveis de protocolo, mas estão sempre presentes no nível superior do soquete. As opções afetam as operações de soquete, como o roteamento de pacotes e a transferência de dados OOB.

O valor associado à opção selecionada é retornado no valor ideal do buffer. O inteiro apontado por optlen deve conter originalmente o tamanho desse buffer; no retorno, ele será definido como o tamanho do valor retornado. Para SO_LINGER, esse será o tamanho de uma estrutura LINGER . Para a maioria das outras opções, será o tamanho de um inteiro.

O aplicativo é responsável por alocar qualquer espaço de memória apontado direta ou indiretamente por qualquer um dos parâmetros especificados.

Se a opção nunca tiver sido definida com setsockopt, getsockopt retornará o valor padrão da opção.

As opções a seguir têm suporte para getsockopt. A coluna Tipo identifica o tipo de dados endereçados por optval.

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

A tabela de valor a seguir para o parâmetro optname é válida quando o parâmetro level é definido como 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 = .  

A tabela de valor a seguir para o parâmetro optname é válida quando o parâmetro level é definido como NSPROTO_IPX.

A tabela a seguir lista o valor para o nome optname que representa as opções de soquete BSD que não são compatíveis com a função getsockopt .

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

Informações mais detalhadas sobre algumas das opções de soquete para o parâmetro optname compatível com a função getsockopt estão listadas abaixo.

SO_CONNECT_TIME

Essa opção retorna o número de segundos em que um soquete foi conectado. Essa opção é válida somente para protocolos orientados a conexão.

A opção SO_CONNECT_TIME pode ser usada com a função getsockopt para marcar se uma conexão foi estabelecida. Essa opção também pode ser usada enquanto uma chamada de função ConnectEx está em andamento. Se uma conexão for estabelecida, a opção SO_CONNECT_TIME poderá determinar por quanto tempo a conexão foi estabelecida. Se o soquete não estiver conectado, o getsockopt retornará SOCKET_ERROR. Verificar uma conexão como essa é necessário para ver se as conexões que foram estabelecidas por um tempo, sem enviar dados. É recomendável que os aplicativos encerrem essas conexões.

SO_DEBUG

Nota Os provedores de serviços do Windows Sockets são incentivados (mas não são necessários) a fornecer informações de depuração de saída se a opção SO_DEBUG for definida por um aplicativo. O mecanismo para gerar as informações de depuração e o formulário que ele toma estão além do escopo deste documento.

 

SO_ERROR

A opção SO_ERROR retorna e redefine o código de erro baseado em soquete, que é diferente do código de erro baseado em thread que é tratado usando as chamadas de função WSAGetLastError e WSASetLastError . Uma chamada bem-sucedida usando o soquete não redefine o código de erro baseado em soquete retornado pela opção SO_ERROR.

SO_EXCLUSIVEADDRUSE

Impede que qualquer outro soquete seja associado ao mesmo endereço e porta. Essa opção deve ser definida antes de chamar a função bind . Consulte a referência SO_EXCLUSIVEADDRUSE para obter mais informações.

SO_GROUP_ID

Nota Essa opção é reservada. Essa opção também é exclusiva para getsockopt; o valor deve ser NULL.

 

SO_GROUP_PRIORITY

Essa opção é reservada. A prioridade do grupo indica a prioridade do soquete especificado em relação a outros soquetes dentro do grupo de soquetes. Os valores são inteiros não negativos, com zero correspondente à prioridade mais alta. Os valores de prioridade representam uma dica para o provedor de serviços subjacente sobre como os recursos potencialmente escassos devem ser alocados. Por exemplo, sempre que dois ou mais soquetes estiverem prontos para transmitir dados, o soquete de prioridade mais alta (valor mais baixo para SO_GROUP_PRIORITY) deverá ser atendido primeiro, com o restante atendido de acordo com suas prioridades relativas.

O código de erro WSAENOPROTOOPT é indicado para soquetes que não são de grupo ou para provedores de serviços que não dão suporte a soquetes de grupo.

SO_KEEPALIVE

Um aplicativo pode solicitar que um provedor de serviços TCP/IP habilite o uso de pacotes keep alive em conexões TCP ativando a opção de soquete SO_KEEPALIVE. Essa opção consulta o valor atual da opção keep alive em um soquete. Um provedor do Windows Sockets não precisa dar suporte ao uso de keep alive: 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 nos Requisitos para Hosts da Internet — Camadas de Comunicação especificadas no RFC 1122 disponíveis no site do IETF. Se uma conexão for descartada como resultado de keep alives, o código de erro WSAENETRESET será retornado para todas as chamadas em andamento no soquete e todas as chamadas subsequentes falharão com WSAENOTCONN. SO_KEEPALIVE não tem suporte em soquetes atm e solicitações para habilitar o uso de pacotes keep alive em um soquete atm resulta em um erro retornado pelo soquete.

SO_LINGER

SO_LINGER controla a ação executada quando dados não criptografados são enfileirados em um soquete e um closesocket é executado. Consulte closesocket para obter uma descrição da maneira como as configurações de SO_LINGER afetam a semântica de closesocket. O aplicativo obtém o comportamento atual recuperando uma estrutura LINGER (apontada pelo parâmetro optval ).

SO_MAX_MSG_SIZE

Essa é uma opção de soquete somente get que indica o tamanho máximo de saída (envio) de uma mensagem para tipos de soquete orientados a mensagens (por exemplo, SOCK_DGRAM) conforme implementado por um provedor de serviços específico. Ele não tem significado para soquetes orientados a fluxo de bytes. Não há nenhum provisionamento para descobrir o tamanho máximo da mensagem de entrada.

SO_PROTOCOL_INFO

Essa é uma opção somente get que fornece a estrutura WSAPROTOCOL_INFO associada a esse soquete. Consulte WSAEnumProtocols para obter mais informações sobre essa estrutura.

SO_SNDBUF

Quando uma implementação do Windows Sockets dá suporte às opções SO_RCVBUF e SO_SNDBUF, um aplicativo pode solicitar tamanhos de buffer diferentes (maiores ou menores). A chamada para setsockopt poderá ser bem-sucedida mesmo que a implementação não tenha fornecido todo o valor solicitado. Um aplicativo deve chamar essa função com a mesma opção para marcar o tamanho do buffer realmente fornecido.

SO_REUSEADDR

Por padrão, um soquete não pode ser associado (consulte associação) a um endereço local que já está em uso. Às vezes, no entanto, pode ser necessário reutilizar um endereço dessa maneira. 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 uma associação em um soquete não deve ser proibida porque o endereço desejado já está em uso por outro soquete, o aplicativo deve definir a opção de soquete SO_REUSEADDR para o soquete antes de emitir a associação. Observe que a opção é interpretada somente no momento da associação: portanto, é desnecessário (mas inofensivo) 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 a associação não tem efeito sobre este ou qualquer outro soquete. SO_REUSEADDR não é aplicável a soquetes de caixa eletrônico e, embora as solicitações de reutilização e endereço não resultem em um erro, elas não têm efeito sobre quando um soquete de caixa eletrônico está em uso.

PVD_CONFIG

Essa opção recupera um objeto de estrutura de dados opaco do provedor de serviços associado a soquetes s. Esse objeto armazena as informações de configuração atuais do provedor de serviços. O formato exato dessa estrutura de dados é específico do provedor de serviços.

TCP_NODELAY

A opção TCP_NODELAY é específica para provedores de serviços TCP/IP. O algoritmo Nagle será desabilitado se a opção TCP_NODELAY estiver habilitada (e vice-versa). O algoritmo Nagle (descrito em RFC 896) é muito eficaz na redução do número de pacotes pequenos enviados por um host. O processo envolve o envio de dados de envio em buffer quando há dados não reconhecidos já em versão de pré-lançamento ou envio de dados em buffer até que um pacote de tamanho completo possa ser enviado. É altamente recomendável que as implementações do Windows Sockets habilitem o Algoritmo nagle por padrão porque, para a grande maioria dos protocolos de aplicativo, o Algoritmo Nagle pode fornecer aprimoramentos significativos de desempenho. No entanto, para alguns aplicativos, esse algoritmo pode impedir o desempenho e setsockopt com a mesma opção pode ser usado para desativá-lo. Esses são aplicativos para onde muitas mensagens pequenas são enviadas e os atrasos de tempo entre as mensagens são mantidos.

Código de exemplo

#include <stdio.h>
#include "winsock2.h"
#include <windows.h>

void main() {

  //---------------------------------------
  // Declare variables
  WSADATA wsaData;
  SOCKET ListenSocket;
  sockaddr_in service;

  //---------------------------------------
  // Initialize Winsock
  int iResult = WSAStartup( MAKEWORD(2,2), &wsaData );
  if( iResult != NO_ERROR )
    printf("Error at WSAStartup\n");

  //---------------------------------------
  // Create a listening socket
  ListenSocket = socket( AF_INET, SOCK_STREAM, IPPROTO_TCP );
  if (ListenSocket == INVALID_SOCKET) {
    printf("Error at socket()\n");
    WSACleanup();
    return;
  }

  //---------------------------------------
  // 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);
 
  if ( bind( ListenSocket,(SOCKADDR*) &service, sizeof(service) )  == SOCKET_ERROR ) {
    printf("bind failed\n");
    closesocket(ListenSocket);
    return;
  }

  //---------------------------------------
  // Initialize variables and call getsockopt. 
  // The SO_ACCEPTCONN parameter is a socket option 
  // that tells the function to check whether the 
  // socket has been put in listening mode or not. 
  // The various socket options return different
  // information about the socket. This call should
  // return 0 to the optVal parameter, since the socket
  // is not in listening mode.
  int optVal;
  int optLen = sizeof(int);

  if (getsockopt(ListenSocket, 
    SOL_SOCKET, 
    SO_ACCEPTCONN, 
    (char*)&optVal, 
    &optLen) != SOCKET_ERROR)
    printf("SockOpt Value: %ld\n", optVal);

  //---------------------------------------
  // Put the listening socket in listening mode.
  if (listen( ListenSocket, 100 ) == SOCKET_ERROR) {
    printf("error listening\n");
  } 

  //---------------------------------------
  // Call getsockopt again to verify that 
  // the socket is in listening mode.
  if (getsockopt(ListenSocket, 
    SOL_SOCKET, 
    SO_ACCEPTCONN, 
    (char*)&optVal, 
    &optLen) != SOCKET_ERROR)
    printf("SockOpt Value: %ld\n", optVal);

  WSACleanup();
  return;
}

Notas para soquetes IrDA

• O arquivo de cabeçalho Af_irda.h deve ser incluído explicitamente.
• O Windows retorna WSAENETDOWN para indicar que o driver de transceptor subjacente falhou ao inicializar com a pilha de protocolo IrDA.
• O IrDA dá suporte a várias opções especiais de soquete:

  Valor	Type	Significado
  IRLMP_ENUMDEVICES	*DEVICELIST	Descreve os dispositivos no intervalo.
  IRLMP_IAS_QUERY	*IAS_QUERY	Recuperar atributos IAS.

   

Antes que uma conexão de soquete IrDA possa ser iniciada, um endereço de dispositivo deve ser obtido executando uma chamada de função getsockopt(,,IRLMP_ENUMDEVICES,,), que retorna uma lista de todos os dispositivos IrDA disponíveis. Um endereço de dispositivo retornado da chamada de função é copiado para uma estrutura SOCKADDR_IRDA , que, por sua vez, é usada por uma chamada subsequente para a chamada de função de conexão .

A descoberta pode ser executada de duas maneiras:

1. Primeiro, executar uma chamada de função getsockopt com a opção IRLMP_ENUMDEVICES faz com que uma única descoberta seja executada em cada adaptador ocioso. A lista de dispositivos descobertos e dispositivos armazenados em cache (em adaptadores ativos) é retornada imediatamente.

   O código a seguir demonstra essa abordagem.

   #include <winsock2.h>
   #include <ws2tcpip.h>
   #include <af_irda.h>
   #include <stdio.h>
   #include <windows.h>
   
   // link with Ws2_32.lib
   
   int __cdecl main()
   {
   
       //-----------------------------------------
       // Declare and initialize variables
       WSADATA wsaData;
   
       int iResult;
       int i;
       DWORD dwError;
   
       SOCKET Sock = INVALID_SOCKET;
   
   #define DEVICE_LIST_LEN    10
   
   
       SOCKADDR_IRDA DestSockAddr = { AF_IRDA, 0, 0, 0, 0, "SampleIrDAService" };
   
       unsigned char DevListBuff[sizeof (DEVICELIST) -
                                 sizeof (IRDA_DEVICE_INFO) +
                                 (sizeof (IRDA_DEVICE_INFO) * DEVICE_LIST_LEN)];
   
       int DevListLen = sizeof (DevListBuff);
       PDEVICELIST pDevList;
   
       pDevList = (PDEVICELIST) & DevListBuff;
   
       // Initialize Winsock
       iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
       if (iResult != 0) {
           printf("WSAStartup failed: %d\n", iResult);
           return 1;
       }
   
       Sock = socket(AF_IRDA, SOCK_STREAM, 0);
       if (Sock == INVALID_SOCKET) {
           dwError = WSAGetLastError();
           printf
               ("socket failed trying to create an AF_IRDA socket with error %d\n",
                dwError);
   
           if (dwError == WSAEAFNOSUPPORT) {
               printf("Check that the local computer has an infrared device\n");
               printf
                   ("and a device driver is installed for the infrared device\n");
           }
           WSACleanup();
           return 1;
       }
       // Sock is not in connected state
       iResult = getsockopt(Sock, SOL_IRLMP, IRLMP_ENUMDEVICES,
                            (char *) pDevList, &DevListLen);
       if (iResult == SOCKET_ERROR) {
           printf("getsockopt failed with error %d\n", WSAGetLastError());
           WSACleanup();
           return 1;
       }
   
       if (pDevList->numDevice == 0) {
           // no devices discovered or cached
           // not a bad idea to run a couple of times
           printf("No IRDA devices were discovered or cached\n");
       } else {
           // one per discovered device
           for (i = 0; i < (int) pDevList->numDevice; i++) {
               // typedef struct _IRDA_DEVICE_INFO
               // {
               //     u_char    irdaDeviceID[4];
               //     char      irdaDeviceName[22];
               //     u_char    irdaDeviceHints1;
               //     u_char    irdaDeviceHints2;
               //     u_char    irdaCharSet;
               // } _IRDA_DEVICE_INFO;
   
               // pDevList->Device[i]. see _IRDA_DEVICE_INFO for fields
               // display the device names and let the user select one
           }
       }
   
       // assume the user selected the first device [0]
       memcpy(&DestSockAddr.irdaDeviceID[0], &pDevList->Device[0].irdaDeviceID[0],
              4);
   
       iResult = connect(Sock, (const struct sockaddr *) &DestSockAddr,
                         sizeof (SOCKADDR_IRDA));
       if (iResult == SOCKET_ERROR) {
           printf("connect failed with error %d\n", WSAGetLastError());
       } else
           printf("connect to first IRDA device was successful\n");
   
       WSACleanup();
       return 0;
   }
   
   

2. A segunda abordagem para executar a descoberta de endereços de dispositivo IrDA é executar uma descoberta lenta; nessa abordagem, o aplicativo não será notificado até que a lista de dispositivos descobertos seja alterada da última descoberta executada pela pilha.

A estrutura IAS_QUERY mostrada na coluna Tipo na tabela anterior é usada para recuperar um único atributo de uma única classe do banco de dados IAS de um dispositivo par. O aplicativo especifica o dispositivo e a classe a serem consultados e o atributo e o tipo de atributo. Observe que o dispositivo teria sido obtido anteriormente por uma chamada para getsockopt(IRLMP_ENUMDEVICES). Espera-se que o aplicativo aloque um buffer, do tamanho necessário, para os parâmetros retornados.

Muitas opções de soquete de nível não são significativas para o IrDA; há suporte apenas para SO_LINGER e SO_DONTLINGER.

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

Confira também

Opções de soquete IPPROTO_IP

Opções de soquete IPPROTO_IPV6

Opções de soquete IPPROTO_RM

Opções de soquete IPPROTO_TCP

Opções de soquete IPPROTO_UDP

Opções de soquete NSPROTO_IPX

Opções de soquete SOL_APPLETALK

Opções de soquete SOL_IRLMP

Opções de soquete SOL_SOCKET

Opções de soquete

WSAAsyncSelect

Wsaconnect

Wsagetlasterror

Wsaioctl

WSASetLastError

Funções Winsock

Ioctlsocket

Recv

Setsockopt

socket