Función setsockopt (winsock.h)

Artículo
08/27/2023

La función setsockopt establece una opción de socket.

Sintaxis

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

Parámetros

[in] s

Descriptor que identifica un socket.

[in] level

Nivel en el que se define la opción (por ejemplo, SOL_SOCKET).

[in] optname

Opción de socket para la que se va a establecer el valor (por ejemplo, SO_BROADCAST). El parámetro optname debe ser una opción de socket definida dentro del nivel especificado o el comportamiento no está definido.

[in] optval

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

[in] optlen

Tamaño, en bytes, del búfer al que apunta el parámetro optval .

Valor devuelto

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

Código de error	Significado
WSANOTINITIALISED	Debe producirse una llamada WSAStartup correcta antes de usar esta función.
WSAENETDOWN	Error en el subsistema de red.
WSAEFAULT	El búfer al que apunta el parámetro optval no está en una parte válida del espacio de direcciones del proceso o el parámetro optlen es demasiado pequeño.
WSAEINPROGRESS	Una llamada de Bloqueo de Windows Sockets 1.1 está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada.
WSAEINVAL	El parámetro level no es válido o la información del búfer a la que apunta el parámetro optval no es válida.
WSAENETRESET	La conexión ha agotado el tiempo de espera cuando se establece SO_KEEPALIVE .
WSAENOPROTOOPT	La opción es desconocida o no admitida para el proveedor o socket especificados (consulte SO_GROUP_PRIORITY limitaciones).
WSAENOTCONN	La conexión se ha restablecido cuando se establece SO_KEEPALIVE .
WSAENOTSOCK	El descriptor no es un socket.

Comentarios

La función setsockopt establece el valor actual de una opción de socket asociada a un socket de cualquier tipo, en cualquier estado. Aunque las opciones pueden existir en varios niveles de protocolo, siempre están presentes en el nivel de socket superior. Las opciones afectan a las operaciones de socket, como si se reciben datos acelerados (datos OOB por ejemplo) en el flujo de datos normal y si se pueden enviar mensajes de difusión en el socket.

Nota Si se llama a la función setsockopt antes de la función de enlace , las opciones de TCP/IP no se comprobarán mediante TCP/IP hasta que se produzca el enlace . En este caso, la llamada a la función setsockopt siempre se realizará correctamente, pero la llamada de función de enlace puede producir un error debido a un error en la llamada a setsockopt temprana.

Nota Si se abre un socket, se realiza una llamada a setsockopt y, a continuación, se realiza una llamada sendto , Windows Sockets realiza una llamada de función de enlace implícita.

Hay dos tipos de opciones de socket: opciones booleanas que habilitan o deshabilitan una característica o un comportamiento, y opciones que requieren un valor entero o una estructura. Para habilitar una opción booleana, el parámetro optval apunta a un entero distinto de cero. Para deshabilitar la opción optval apunta a un entero igual a cero. El parámetro optlen debe ser igual a sizeof(int) para las opciones booleanas. Para otras opciones, optval apunta a un entero o estructura que contiene el valor deseado para la opción y optlen es la longitud del entero o la estructura.

En las tablas siguientes se enumeran algunas de las opciones comunes admitidas por la función setsockopt . La columna Tipo identifica el tipo de datos direccionado por el parámetro optval . La columna Descripción proporciona información básica sobre la opción de socket. Para obtener listas más completas de opciones de socket e información más detallada (valores predeterminados, por ejemplo), vea los temas detallados en Opciones de socket.

Nivel = SOL_SOCKET

Valor	Tipo	Descripción
SO_BROADCAST	BOOL	Configura un socket para enviar datos de difusión.
SO_CONDITIONAL_ACCEPT	BOOL	Permite que la aplicación acepte o rechace las conexiones entrantes, no por la pila de protocolos.
SO_DEBUG	BOOL	Habilita la salida de depuración. Actualmente, los proveedores de Microsoft no generan ninguna información de depuración.
SO_DONTLINGER	BOOL	No bloquea el cierre a la espera de que se envíen datos no enviados. Establecer esta opción equivale a establecer SO_LINGER con l_onoff establecido en cero.
SO_DONTROUTE	BOOL	Establece si se deben enviar datos salientes en la interfaz a la que está enlazado el socket y no a un enrutado en alguna otra interfaz. Esta opción no se admite en sockets ATM (da como resultado un error).
SO_GROUP_PRIORITY	int	Reservado.
SO_KEEPALIVE	BOOL	Habilita el envío de paquetes keep-alive para una conexión de socket. No se admite en sockets ATM (se produce un error).
SO_LINGER	QUEDARSE	Permanece cerca si hay datos sin sangría presentes.
SO_OOBINLINE	BOOL	Indica que los datos no enlazados deben devolverse en línea con datos normales. Esta opción solo es válida para los protocolos orientados a la conexión que admiten datos fuera de banda. Para obtener una explicación de este tema, consulte Protocol Independent Out-Of-Band Data.
SO_RCVBUF	int	Especifica el espacio total de búfer por socket reservado para las recepciones.
SO_REUSEADDR	BOOL	Permite enlazar el socket a una dirección que ya está en uso. Para obtener más información, consulte enlace. No es aplicable en sockets ATM.
SO_EXCLUSIVEADDRUSE	BOOL	Permite enlazar un socket para obtener acceso exclusivo. No requiere privilegios administrativos.
SO_RCVTIMEO	DWORD	Establece el tiempo de espera, en milisegundos, para bloquear las llamadas de recepción.
SO_SNDBUF	int	Especifica el espacio total de búfer por socket reservado para los envíos.
SO_SNDTIMEO	DWORD	Tiempo de espera, en milisegundos, para bloquear las llamadas de envío.
SO_UPDATE_ACCEPT_CONTEXT	int	Novedades el socket de aceptación con el contexto del socket de escucha.
PVD_CONFIG	Dependiente del proveedor de servicios	Este objeto almacena la información de configuración del proveedor de servicios asociado a sockets. El formato exacto de esta estructura de datos es específico del proveedor de servicios.

Para obtener información más completa y detallada sobre las opciones de socket parala SOL_SOCKET de nivel = , consulte SOL_SOCKET Opciones de 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.

Nivel = NSPROTO_IPX

Valor	Tipo	Descripción
IPX_PTYPE	int	Establece el tipo de paquete IPX.
IPX_FILTERPTYPE	int	Establece el tipo de paquete de filtro de recepción.
IPX_STOPFILTERPTYPE	int	Detiene el filtrado del conjunto de tipos de filtro con IPX_FILTERTYPE
IPX_DSTYPE	int	Establece el valor del campo de flujo de datos en el encabezado SPX en cada paquete enviado.
IPX_EXTENDED_ADDRESS	BOOL	Establece si el direccionamiento extendido está habilitado.
IPX_RECVHDR	BOOL	Establece si el encabezado de protocolo se envía en todos los encabezados de recepción.
IPX_RECEIVE_BROADCAST	BOOL	Indica que es probable que los paquetes de difusión estén en el socket. Establezca en TRUE de forma predeterminada. Las aplicaciones que no usan difusiones deben establecer esto en FALSE para mejorar el rendimiento del sistema.
IPX_IMMEDIATESPXACK	BOOL	Dirige las conexiones SPX a no retrasarse antes de enviar una ACK. Las aplicaciones sin tráfico hacia atrás y hacia delante deben establecer esto en TRUE para aumentar el rendimiento.

Para obtener información más completa y detallada sobre las opciones de socket parael nivel = NSPROTO_IPX, consulte NSPROTO_IPX Opciones de socket.

Las opciones de BSD no se admiten para setsockopt se muestran en la tabla siguiente.

Valor	Tipo	Descripción
SO_ACCEPTCONN	BOOL	Devuelve si un socket está en modo de escucha. Esta opción solo es Válida para protocolos orientados a la conexión. Esta opción de socket no se admite para la configuración.
SO_RCVLOWAT	int	Se incluye una opción de socket de BSD UNIX para la compatibilidad con versiones anteriores. Esta opción establece el número mínimo de bytes que se van a procesar para las operaciones de entrada de socket.
SO_SNDLOWAT	int	Se incluye una opción de socket de BSD UNIX para la compatibilidad con versiones anteriores. Esta opción establece el número mínimo de bytes que se van a procesar para las operaciones de salida de socket.
SO_TYPE	int	Devuelve el tipo de socket para el socket especificado (SOCK_STREAM o SOCK_DGRAM, por ejemplo, esta opción de socket no se admite para la configuración del tipo de socket.

Nota Al emitir una llamada de Winsock de bloqueo como setsockopt, Winsock puede necesitar esperar un evento de red antes de que se pueda completar la llamada. Winsock realiza una espera alertable en esta situación, que se puede interrumpir mediante una llamada de procedimiento asincrónica (APC) programada en el mismo subproceso. La emisión de otra llamada winsock de bloqueo dentro de un APC que interrumpió una llamada de Winsock de bloqueo en curso en el mismo subproceso provocará un comportamiento indefinido y los clientes winsock nunca deben intentarlo.

Código de ejemplo

En el ejemplo siguiente se muestra la función 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 sockets IrDA

Al desarrollar aplicaciones con Windows Sockets para IrDA, tenga en cuenta lo siguiente:

El archivo de encabezado Af_irda.h debe incluirse explícitamente.
IrDA proporciona la siguiente opción de socket:

Valor Tipo Significado

IRLMP_IAS_SET *IAS_SET Establece atributos de IAS

Valor	Tipo	Significado
IRLMP_IAS_SET	*IAS_SET	Establece atributos de IAS

La opción de socket IRLMP_IAS_SET permite a la aplicación establecer un único atributo de una sola clase en el IAS local. La aplicación especifica la clase que se va a establecer, el atributo y el tipo de atributo. Se espera que la aplicación asigne un búfer del tamaño necesario para los parámetros pasados.

IrDA proporciona una base de datos IAS que almacena información basada en IrDA. El acceso limitado a la base de datos IAS está disponible a través de la interfaz de Windows Sockets 2, pero este acceso no lo usan normalmente las aplicaciones y existe principalmente para admitir conexiones a dispositivos que no son windows que no son compatibles con las convenciones irDA de Windows Sockets 2.

La siguiente estructura, IAS_SET, se usa con la opción setockopt de IRLMP_IAS_SET para administrar la base de datos 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;

La siguiente estructura, IAS_QUERY, se usa con la opción setockopt de IRLMP_IAS_QUERY para consultar la base de datos de IAS de un mismo nivel:


// #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;

Muchas opciones de socket de nivel de SO_ no son significativas para IrDA. Solo se admite SO_LINGER 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


Cliente mínimo compatible	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winsock.h (incluya Winsock2.h)
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll