código de control de SIO_KEEPALIVE_VALS

Artículo
06/13/2023

Descripción

El código de control SIO_KEEPALIVE_VALS habilita o deshabilita la configuración por conexión de la opción tcp keep-alive que especifica el tiempo de espera y el intervalo de mantenimiento de TCP.

Para realizar esta operación, llame a la función WSAIoctl o WSPIoctl con los parámetros siguientes.

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parámetros

s

Descriptor que identifica un socket.

dwIoControlCode

Código de control de la operación. Use SIO_KEEPALIVE_VALS para esta operación.

lpvInBuffer

Puntero al búfer de entrada. Este parámetro debe apuntar a una estructura de tcp_keepalive .

cbInBuffer

Tamaño, en bytes, del búfer de entrada. Este parámetro debe ser igual o mayor que el tamaño de la estructura de tcp_keepalive a la que apunta el parámetro lpvInBuffer .

lpvOutBuffer

Puntero al búfer de salida. Este parámetro no se usa para esta operación.

cbOutBuffer

Tamaño, en bytes, del búfer de salida. Este parámetro debe establecerse en cero.

lpcbBytesReturned

Puntero a una variable que recibe el tamaño, en bytes, de los datos almacenados en el búfer de salida. Este parámetro devuelto apunta a un valor DWORD de cero para esta operación, ya que no hay ninguna salida.

lpvOverlapped

Puntero a una estructura WSAOVERLAPPED .

Si el socket s se creó sin el atributo superpuesto, se omite el parámetro lpOverlapped .

Si se abrió s con el atributo superpuesto y el parámetro lpOverlapped no es NULL, la operación se realiza como una operación superpuesta (asincrónica). En este caso, el parámetro lpOverlapped debe apuntar a una estructura WSAOVERLAPPED válida.

Para las operaciones superpuestas, la función WSAIoctl o WSPIoctl devuelve inmediatamente y el método de finalización adecuado se señala cuando se ha completado la operación. De lo contrario, la función no devuelve hasta que se haya completado la operación o se produzca un error.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntero a la rutina de finalización a la que se llama cuando se ha completado la operación (se omite para sockets no superpuestos).

lpThreadId

Puntero a una estructura WSATHREADID que usará el proveedor en una llamada posterior a WPUQueueApc. El proveedor debe almacenar la estructura WSATHREADID a la que se hace referencia (no el puntero a la misma) hasta después de que la función WPUQueueApc devuelva.

Nota Este parámetro solo se aplica a la función WSPIoctl .

lpErrno

Puntero al código de error.

Nota Este parámetro solo se aplica a la función WSPIoctl .

Valor devuelto

Si la operación se completa correctamente, la función WSAIoctl o WSPIoctl devuelve cero.

Si se produce un error en la operación o está pendiente, la función WSAIoctl o WSPIoctl devuelve SOCKET_ERROR. Para obtener información de error extendida, llame a WSAGetLastError.

Código de error	Significado
WSA_IO_PENDING	Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior.
WSA_OPERATION_ABORTED	Se canceló una operación superpuesta debido al cierre del socket o a la ejecución del comando SIO_FLUSH IOCTL .
WSAEFAULT	El parámetro lpOverlapped o lpCompletionRoutine no está totalmente incluido en una parte válida del espacio de direcciones del usuario.
WSAEINPROGRESS	La función se invoca cuando una devolución de llamada está en curso.
WSAEINTR	Se interrumpió una operación de bloqueo.
WSAEINVAL	El parámetro dwIoControlCode no es un comando válido o un parámetro de entrada especificado no es aceptable o el comando no es aplicable al tipo de socket especificado.
WSAENETDOWN	Error en el subsistema de red.
WSAENOPROTOOPT	La opción socket no se admite en el protocolo especificado. Este error se devuelve para un socket de datagrama.
WSAENOTSOCK	El descriptor s no es un socket.
WSAEOPNOTSUPP	No se admite el comando IOCTL especificado. Este error se devuelve si el proveedor de transporte no admite el SIO_KEEPALIVE_VALS IOCTL.

Comentarios

El SIO_KEEPALIVE_VALS IOCTL es compatible con Windows 2000 y versiones posteriores del sistema operativo.

El código de control de SIO_KEEPALIVE_VALS habilita o deshabilita la configuración por conexión de la opción keep-alive de TCP que especifica el tiempo de espera y el intervalo de mantenimiento de TCP que se usa para los paquetes de mantenimiento de TCP. Para obtener más información sobre la opción keep-alive, consulte la sección 4.2.3.6 en requisitos para hosts de Internet: capas de comunicación especificadas en RFC 1122 disponible en el sitio web de IETF. (Este recurso solo puede estar disponible en inglés).

El parámetro lpvInBuffer debe apuntar a una estructura de tcp_keepalive definida en el archivo de encabezado Mstcpip.h . Esta estructura se define de la siguiente manera:

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

El valor especificado en el miembro onoff determina si TCP keep-alive está habilitado o deshabilitado. Si el miembro onoff se establece en un valor distinto de cero, se habilita tcp keep-alive y se usan los demás miembros de la estructura. El miembro keepalivetime especifica el tiempo de espera, en milisegundos, sin actividad hasta que se envíe el primer paquete keep-alive. El miembro keepaliveinterval especifica el intervalo, en milisegundos, entre cuando se envían paquetes keep-alive sucesivos si no se recibe ninguna confirmación.

La opción SO_KEEPALIVE , que es una de las opciones de socket de SOL_SOCKET, también se puede usar para habilitar o deshabilitar el mantenimiento de TCP en una conexión, así como consultar el estado actual de esta opción. Para consultar si TCP keep-alive está habilitado en un socket, se puede llamar a la función getsockopt con la opción SO_KEEPALIVE . Para habilitar o deshabilitar tcp keep-alive, se puede llamar a la función setsockopt con la opción SO_KEEPALIVE . Si tcp keep-alive está habilitado con SO_KEEPALIVE, la configuración de TCP predeterminada se usa para el tiempo de espera y el intervalo de mantenimiento activo, a menos que estos valores se hayan cambiado mediante SIO_KEEPALIVE_VALS.

El valor predeterminado en todo el sistema del tiempo de espera de mantenimiento se puede controlar a través de la configuración del registro KeepAliveTime que toma un valor en milisegundos. Si no se establece la clave, el tiempo de espera de mantenimiento predeterminado es de 2 horas. El valor predeterminado de todo el sistema del intervalo keep-alive se puede controlar a través de la configuración del Registro KeepAliveInterval que toma un valor en milisegundos. Si no se establece la clave, el intervalo predeterminado de mantenimiento activo es de 1 segundo.

En Windows Vista y versiones posteriores, el número de sondeos de mantenimiento activo (retransmisiones de datos) se establece en 10 y no se puede cambiar.

En Windows Server 2003, Windows XP y Windows 2000, la configuración predeterminada para el número de sondeos de mantenimiento activo es 5. El número de sondeos keep-alive se puede controlar a través de la configuración del Registro TcpMaxDataRetransmissions y PPTPTcpMaxDataRetransmissions . El número de sondeos de mantenimiento activo se establece en el mayor de los dos valores de clave del Registro. Si este número es 0, no se enviarán sondeos de mantenimiento activo. Si este número es superior a 255, se ajusta a 255.