Función getsockopt (winsock.h)

La función getsockopt recupera una opción de socket.

Sintaxis

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

Parámetros

[in] s

Descriptor que identifica un socket.

[in] level

Nivel en el que se define la opción. Ejemplo: SOL_SOCKET.

[in] optname

Opción de socket para la que se va a recuperar el valor. Ejemplo: SO_ACCEPTCONN. El valor optname debe ser una opción de socket definida dentro del nivel especificado o el comportamiento no está definido.

[out] optval

Puntero al búfer en el que se va a devolver el valor de la opción solicitada.

[in, out] optlen

Puntero al tamaño, en bytes, del búfer optval .

Valor devuelto

Si no se produce ningún error, getsockopt devuelve cero. De lo contrario, se devuelve un valor de SOCKET_ERROR y se puede recuperar un código de error específico llamando a WSAGetLastError.

Comentarios

La función getsockopt recupera el valor actual de una opción de socket asociada a un socket de cualquier tipo, en cualquier estado y almacena el resultado en optval. Las opciones pueden existir en varios niveles de protocolo, pero siempre están presentes en el nivel de socket superior. Las opciones afectan a las operaciones de socket, como el enrutamiento de paquetes y la transferencia de datos OOB.

El valor asociado a la opción seleccionada se devuelve en la optval del búfer. El entero al que apunta optlen debe contener originalmente el tamaño de este búfer; al devolverlo, se establecerá en el tamaño del valor devuelto. Para SO_LINGER, será el tamaño de una estructura LINGER . Para la mayoría de las demás opciones, será el tamaño de un entero.

La aplicación es responsable de asignar cualquier espacio de memoria al que apunte directa o indirectamente cualquiera de los parámetros especificados.

Si la opción nunca se estableció con setsockopt, getsockopt devuelve el valor predeterminado de la opción.

Se admiten las siguientes opciones para getockopt. La columna Tipo identifica el tipo de datos direccionado por optval.

Para obtener más información sobre las opciones de socket, consulte Opciones de socket.

La siguiente tabla de valor para el parámetro optname es válida cuando el parámetro level se establece en SOL_SOCKET.

Nivel = IPPROTO_TCP

Consulte TCP_NODELAY en IPPROTO_TCP opciones de socket. Consulte también ese tema para obtener información más completa y detallada sobre las opciones de socket para el nivel = IPPROTO_TCP.  

La siguiente tabla de valor para el parámetro optname es válida cuando el parámetro level se establece en NSPROTO_IPX.

En la tabla siguiente se muestra el valor de optname que representa las opciones de socket BSD que no son compatibles con la función getsockopt .

Al llamar a getsockopt con una opción no admitida, se devolverá un código de error de WSAENOPROTOOPT desde WSAGetLastError.

A continuación se muestra información más detallada sobre algunas de las opciones de socket para el parámetro optname admitido por la función getsockopt .

SO_CONNECT_TIME

Esta opción devuelve el número de segundos que se ha conectado un socket. Esta opción solo es válida para los protocolos orientados a la conexión.

La opción SO_CONNECT_TIME se puede usar con la función getsockopt para comprobar si se ha establecido una conexión. Esta opción también se puede usar mientras una llamada de función ConnectEx está en curso. Si se establece una conexión, la opción SO_CONNECT_TIME puede determinar cuánto tiempo se ha establecido la conexión. Si el socket no está conectado, getsockopt devuelve SOCKET_ERROR. Comprobar una conexión como esta es necesaria para ver si las conexiones que se han establecido durante un tiempo, sin enviar datos. Se recomienda que las aplicaciones finalicen estas conexiones.

SO_DEBUG

Nota Se recomienda a los proveedores de servicios de Windows Sockets (pero no necesarios) proporcionar información de depuración de salida si una aplicación establece la opción SO_DEBUG. El mecanismo para generar la información de depuración y el formulario que toma están fuera del ámbito de este documento.

 

SO_ERROR

La opción SO_ERROR devuelve y restablece el código de error basado en socket, que es diferente del código de error basado en subprocesos que se controla mediante las llamadas a la función WSAGetLastError y WSASetLastError . Una llamada correcta mediante el socket no restablece el código de error basado en socket devuelto por la opción SO_ERROR.

SO_EXCLUSIVEADDRUSE

Impide que cualquier otro socket se enlace a la misma dirección y puerto. Esta opción debe establecerse antes de llamar a la función bind . Consulte la referencia de SO_EXCLUSIVEADDRUSE para obtener más información.

SO_GROUP_ID

Nota Esta opción está reservada. Esta opción también es exclusiva de getsockopt; el valor debe ser NULL.

 

SO_GROUP_PRIORITY

Esta opción está reservada. La prioridad de grupo indica la prioridad del socket especificado en relación con otros sockets dentro del grupo de sockets. Los valores son enteros no negativo, con cero correspondiente a la prioridad más alta. Los valores de prioridad representan una sugerencia al proveedor de servicios subyacente sobre cómo se deben asignar recursos potencialmente escasos. Por ejemplo, cada vez que dos o más sockets están listos para transmitir datos, el socket de prioridad más alto (valor más bajo para SO_GROUP_PRIORITY) se debe atender primero, con el resto con servicio a su vez según sus prioridades relativas.

El código de error WSAENOPROTOOPT se indica para sockets que no son de grupo o para proveedores de servicios que no admiten sockets de grupo.

SO_KEEPALIVE

Una aplicación puede solicitar que un proveedor de servicios TCP/IP habilite el uso de paquetes keep-alive en las conexiones TCP activando la opción de socket SO_KEEPALIVE. Esta opción consulta el valor actual de la opción keep-alive en un socket. Un proveedor de Windows Sockets no necesita admitir el uso de keep-alive: si lo hace, la semántica precisa es específica de la implementación, pero debe ajustarse a la sección 4.2.3.6 en los Requisitos para hosts de Internet: capas de comunicación especificadas en RFC 1122 disponibles en el sitio web de IETF. Si se quita una conexión como resultado de keep-alives, el código de error WSAENETRESET se devuelve a cualquier llamada en curso en el socket y se producirá un error en las llamadas posteriores con WSAENOTCONN. SO_KEEPALIVE no se admite en sockets ATM, y las solicitudes para habilitar el uso de paquetes keep-alive en un socket ATM producen un error devuelto por el socket.

SO_LINGER

SO_LINGER controla la acción realizada cuando los datos no enviados se ponen en cola en un socket y se realiza un closesocket . Consulte closesocket para obtener una descripción de la forma en que la configuración de SO_LINGER afecta a la semántica de closesocket. La aplicación obtiene el comportamiento actual recuperando una estructura LINGER (apuntada por el parámetro optval ).

SO_MAX_MSG_SIZE

Se trata de una opción de socket de solo obtención que indica el tamaño máximo de salida (envío) de un mensaje para los tipos de socket orientados a mensajes (por ejemplo, SOCK_DGRAM) implementados por un proveedor de servicios determinado. No tiene ningún significado para los sockets orientados a flujos de bytes. No hay ningún aprovisionamiento para averiguar el tamaño máximo de los mensajes entrantes.

SO_PROTOCOL_INFO

Se trata de una opción de solo obtención que proporciona la estructura WSAPROTOCOL_INFO asociada a este socket. Consulte WSAEnumProtocols para obtener más información sobre esta estructura.

SO_SNDBUF

Cuando una implementación de Windows Sockets admite las opciones de SO_RCVBUF y SO_SNDBUF, una aplicación puede solicitar tamaños de búfer diferentes (mayores o más pequeños). La llamada a setsockopt puede realizarse correctamente incluso si la implementación no proporcionó toda la cantidad solicitada. Una aplicación debe llamar a esta función con la misma opción para comprobar el tamaño del búfer realmente proporcionado.

SO_REUSEADDR

De forma predeterminada, un socket no se puede enlazar (vea enlazar) a una dirección local que ya está en uso. Sin embargo, en ocasiones, puede ser necesario reutilizar una dirección de esta manera. Dado que cada conexión se identifica de forma única mediante la combinación de direcciones locales y remotas, no hay ningún problema al tener dos sockets enlazados a la misma dirección local siempre que las direcciones remotas sean diferentes. Para informar al proveedor de Windows Sockets de que no se debe denegar un enlace en un socket porque la dirección deseada ya está en uso por otro socket, la aplicación debe establecer la opción de socket SO_REUSEADDR para el socket antes de emitir el enlace. Tenga en cuenta que la opción solo se interpreta en el momento del enlace: por lo tanto, no es necesario (pero inofensivo) establecer la opción en un socket que no se va a enlazar a una dirección existente y establecer o restablecer la opción después de que el enlace no tenga ningún efecto en este o en cualquier otro socket. SO_REUSEADDR no es aplicable a los sockets ATM, y aunque las solicitudes de reutilización y dirección no producen un error, no tienen ningún efecto en cuando un socket ATM está en uso.

PVD_CONFIG

Esta opción recupera un objeto de estructura de datos opaco del proveedor de servicios asociado a sockets. Este objeto almacena la información de configuración actual del proveedor de servicios. El formato exacto de esta estructura de datos es específico del proveedor de servicios.

TCP_NODELAY

La opción TCP_NODELAY es específica de los proveedores de servicios TCP/IP. El algoritmo nagle está deshabilitado si la opción TCP_NODELAY está habilitada (y viceversa). El algoritmo nagle (descrito en RFC 896) es muy eficaz para reducir el número de paquetes pequeños enviados por un host. El proceso implica almacenar en búfer los datos de envío cuando ya hay datos no reconocidos en vuelo o almacenamiento en búfer que envían datos hasta que se pueda enviar un paquete de tamaño completo. Se recomienda encarecidamente que las implementaciones de Windows Sockets habiliten el algoritmo de Nagle de forma predeterminada porque, para la gran mayoría de los protocolos de aplicación, el algoritmo nagle puede ofrecer mejoras de rendimiento significativas. Sin embargo, para algunas aplicaciones, este algoritmo puede impedir el rendimiento y setockopt con la misma opción se puede usar para desactivarlo. Se trata de aplicaciones en las que se envían muchos mensajes pequeños y se mantienen los retrasos de tiempo entre los mensajes.

Código de ejemplo

#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 sockets IrDA

• El archivo de encabezado Af_irda.h debe incluirse explícitamente.
• Windows devuelve WSAENETDOWN para indicar que el controlador transceptor subyacente no se pudo inicializar con la pila del protocolo IrDA.
• IrDA admite varias opciones de socket especiales:

  Valor	Tipo	Significado
  IRLMP_ENUMDEVICES	*DEVICELIST	Describe los dispositivos en el intervalo.
  IRLMP_IAS_QUERY	*IAS_QUERY	Recuperar atributos de IAS.

   

Para poder iniciar una conexión de socket IrDA, se debe obtener una dirección de dispositivo mediante la realización de una llamada de función getockopt(,,IRLMP_ENUMDEVICES,,), que devuelve una lista de todos los dispositivos IrDA disponibles. Una dirección de dispositivo devuelta desde la llamada de función se copia en una estructura de SOCKADDR_IRDA , que a su vez se usa mediante una llamada posterior a la llamada a la función connect .

La detección se puede realizar de dos maneras:

1. En primer lugar, realizar una llamada de función getockopt con la opción IRLMP_ENUMDEVICES hace que se ejecute una sola detección en cada adaptador inactivo. La lista de dispositivos detectados y dispositivos almacenados en caché (en adaptadores activos) se devuelve inmediatamente.

   En el código siguiente se muestra este enfoque.

   #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. El segundo enfoque para realizar la detección de direcciones de dispositivo IrDA es realizar una detección diferida; en este enfoque, la aplicación no se notifica hasta que la lista de dispositivos detectados cambie de la última detección ejecutada por la pila.

La estructura IAS_QUERY que se muestra en la columna Tipo de la tabla anterior se usa para recuperar un único atributo de una sola clase de una base de datos IAS de un dispositivo del mismo nivel. La aplicación especifica el dispositivo y la clase que se van a consultar y el atributo y el tipo de atributo. Tenga en cuenta que el dispositivo se habría obtenido anteriormente mediante una llamada a getockopt(IRLMP_ENUMDEVICES). Se espera que la aplicación asigne un búfer, del tamaño necesario, para los parámetros devueltos.

Muchas opciones de socket de nivel no son significativas para IrDA; solo se admiten SO_LINGER y SO_DONTLINGER específicamente.

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos

Consulte también

Opciones de socket de IPPROTO_IP

Opciones de socket de IPPROTO_IPV6

Opciones de socket de IPPROTO_RM

Opciones de socket de IPPROTO_TCP

Opciones de socket de IPPROTO_UDP

Opciones de socket de NSPROTO_IPX

Opciones de socket de SOL_APPLETALK

Opciones de socket de SOL_IRLMP

Opciones de socket de SOL_SOCKET

Opciones de socket

WSAAsyncSelect

WSAConnect

WSAGetLastError

WSAIoctl

WSASetLastError

Funciones winsock

ioctlsocket

recv

setsockopt

socket