Función de devolución de llamada LPWSPSETSOCKOPT (ws2spi.h)

Artículo
08/28/2023

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

Sintaxis

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

Descriptor que identifica un socket.

[in] level

Nivel en el que se define la opción; los niveles admitidos incluyen SOL_SOCKET. Para obtener más información, vea Anexos de Winsock.

[in] optname

Opción de socket para la que se va a establecer el valor.

[in] optval

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

[in] optlen

Tamaño, en bytes, del búfer optval .

[out] lpErrno

Puntero al código de error.

Valor devuelto

Si no se produce ningún error, LPWSPSetSockOpt devuelve cero. De lo contrario, se devuelve un valor de SOCKET_ERROR y hay disponible un código de error específico en lpErrno.

Código de error	Significado
WSAENETDOWN	Error en el subsistema de red.
WSAEFAULT	La optval no está en una parte válida del espacio de direcciones del proceso o el parámetro optlen es demasiado pequeño.
WSAEINPROGRESS	La función se invoca cuando una devolución de llamada está en curso.
WSAEINPROGRESS	El bloqueo de la llamada a Windows Sockets está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada.
WSAEINVAL	El nivel no es válido o la información en optval no es válida.
WSAENETRESET	Se ha interrumpido la conexión debido a que la actividad para mantener activa la conexión detectó un error durante la operación.
WSAENOPROTOOPT	La opción es desconocida o no es compatible con el proveedor especificado.
WSAENOTCONN	La conexión se ha restablecido cuando se establece SO_KEEPALIVE .
WSAENOTSOCK	El descriptor no es un socket.

Comentarios

La función LPWSPSetSockOpt 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 pueden enviar mensajes de difusión en el socket.

Hay dos tipos de opciones de socket: opciones booleanas que habilitan o deshabilitan una característica o comportamiento, y opciones que requieren un valor o estructura enteros. Para habilitar una opción booleana, 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.

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

level = SOL_SOCKET

Valor	Tipo	Significado
SO_BROADCAST	BOOL	Habilita la transmisión y recepción de mensajes de difusión en el socket.
SO_DEBUG	BOOL	Registra información de depuración.
SO_DONTLINGER	BOOL	Reservado.
SO_DONTROUTE	BOOL	Enrutamiento deshabilitado: enviar directamente a una interfaz. Establecer esta opción de socket se realiza correctamente, pero se omite en AF_INET sockets; produce un error en AF_INET6 sockets con WSAENOPROTOOPT . Esta opción no se admite en sockets ATM (produce un error).
SO_GROUP_PRIORITY	int	Reservado.
SO_KEEPALIVE	BOOL	Envía keep-alives. No se admite en sockets ATM (se produce un error).
SO_LINGER	estructura persistente	Permanece cerca si hay datos sin enviar.
SO_OOBINLINE	BOOL	Recibe datos de OOB en el flujo de datos normal.
SO_RCVBUF	int	Especifica el espacio total de búfer por socket reservado para las recepciones. Esto no está relacionado con SO_MAX_MSG_SIZE y no se corresponde necesariamente con el tamaño de la ventana de recepción TCP.
SO_REUSEADDR	BOOL	Permite enlazar el socket a una dirección que ya está en uso. (Consulte Bind).) No aplicable en sockets ATM.
SO_SNDBUF	int	Especifica el espacio total de búfer por socket reservado para los envíos. Esto no está relacionado con SO_MAX_MSG_SIZE y no se corresponde necesariamente con el tamaño de una ventana de envío TCP.
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.

Al llamar a LPWSPGetSockopt con una opción no admitida, se producirá un código de error de WSAENOPROTOOPT devuelto en lpErrno.

SO_DEBUG

Se recomienda a los proveedores de servicios de Windows Sockets, pero no necesarios, proporcionar información de depuración de salida si un cliente SPI de Windows Sockets establece la opción SO_DEBUG . El mecanismo para generar la información de depuración y el formato están fuera del ámbito de esta especificación.

SO_GROUP_PRIORITY

Reservado.

SO_KEEPALIVE

Un cliente SPI de Windows Sockets puede solicitar que un proveedor TCP/IP habilite el uso de paquetes keep-alive en conexiones TCP activando la opción de socket SO_KEEPALIVE . Un proveedor de Windows Sockets no necesita admitir el uso de keep-alives: si lo hace, la semántica precisa es específica de la implementación, pero debe cumplir la sección 4.2.3.6 de RFC 1122: Requisitos para hosts de Internet: capas de comunicación. (Este recurso solo puede estar disponible en inglés). Si se quita una conexión como resultado de keep-alive, 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_LINGER

SO_LINGER controla la acción realizada cuando los datos no enviados se ponen en cola en un socket y se realiza un LPWSPCloseSocket . Consulte LPWSPCloseSocket para obtener una descripción de la forma en que la configuración de SO_LINGER afecta a la semántica de LPWSPCloseSocket. El cliente SPI de Windows Sockets establece el comportamiento deseado mediante la creación de una estructura LINGER , a la que apunta el parámetro optval , con los siguientes elementos.

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

Para habilitar SO_LINGER, un cliente SPI de Windows Sockets debe establecer l_onoff en un valor distinto de cero, establezca l_linger en cero o el tiempo de espera deseado, en segundos, y llame a LPWSPSetSockOpt. Para habilitar SO_DONTLINGER, es decir, deshabilitar SO_LINGER, se debe establecer l_onoff en cero y se debe llamar a LPWSPSetSockOpt . Tenga en cuenta que no se recomienda habilitar SO_LINGER con un tiempo de espera distinto de cero en un socket sin bloqueo. Para obtener más información, consulte LPWSPCloseSocket.

Al habilitar SO_LINGER también se deshabilitan los SO_DONTLINGER y viceversa. Tenga en cuenta que si SO_DONTLINGER está deshabilitado (es decir, SO_LINGER está habilitado), no se especifica ningún valor de tiempo de espera. En este caso, el tiempo de espera usado depende de la implementación. Si se ha establecido un tiempo de espera anterior para un socket (habilitando SO_LINGER), el proveedor de servicios debe restablecer este valor de tiempo de espera.

SO_REUSEADDR

De forma predeterminada, un socket no se puede enlazar (para obtener más información, consulte LPWSPBind) a una dirección local que ya está en uso. Sin embargo, en ocasiones puede ser conveniente 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 se debe permitir que un LPWSPBind en un socket se enlace a una dirección local que ya está en uso por otro socket, el cliente SPI de Windows Sockets debe establecer la opción de socket SO_REUSEADDR para el socket antes de emitir el LPWSPBind. Tenga en cuenta que la opción solo se interpreta en el momento de LPWSPBind: por lo tanto, es innecesario, 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 lpWSPBind no tiene ningún efecto en este o en cualquier otro socket.

SO_SNDBUF

Cuando una implementación de Windows Sockets admite las opciones SO_RCVBUF y SO_SNDBUF , un cliente SPI de Windows Sockets puede solicitar diferentes tamaños de búfer (más grandes o más pequeños). La llamada puede realizarse correctamente aunque el proveedor de servicios no haya disponible toda la cantidad solicitada. Un cliente SPI de Windows Sockets debe llamar a LPWSPGetSockopt con la misma opción para comprobar el tamaño del búfer realmente proporcionado.

PVD_CONFIG

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.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	ws2spi.h