Código de control SIO_IDEAL_SEND_BACKLOG_CHANGE

Artículo
10/16/2023

Descripción

El código de control SIO_IDEAL_SEND_BACKLOG_CHANGE avisa a una aplicación cuando cambia el valor ideal de trabajo pendiente de envío (ISB) para la conexión.

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  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_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  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_IDEAL_SEND_BACKLOG_CHANGE para esta operación.

lpvInBuffer

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

cbInBuffer

Tamaño, en bytes, del búfer de entrada. Este parámetro no se usa para esta operación.

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 s se abrió 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, las funciones WSAIoctl y WSPIoctl se devuelven 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 se devuelve hasta que se haya completado la operación o hasta que 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 el proveedor usará 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 que se devuelva la función WPUQueueApc.

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 esta está pendiente, la función WSAIoctl o WSPIoctl devuelve SOCKET_ERROR. Para obtener información ampliada del error, llame a WSAGetLastError.

Código de error	Significado
WSA_IO_PENDING	Una operación superpuesta se inició correctamente y la finalización se indicará más adelante.
WSA_OPERATION_ABORTED	Se canceló una operación superpuesta debido al cierre del socket o a la ejecución del comando IOCTL SIO_FLUSH.
WSAEFAULT	El parámetro lpOverlapped o lpCompletionRoutine no está totalmente contenido en una parte válida del espacio de direcciones del usuario.
WSAEINPROGRESS	La función se invoca cuando hay una devolución de llamada en curso.
WSAEINTR	Se interrumpió una operación de bloqueo.
WSAEINVAL	El parámetro dwIoControlCode no es un comando válido, uno de los parámetros de entrada especificados no es aceptable, o el comando no es aplicable al tipo de socket especificado. Este error se devuelve si el parámetro cbOutBuffer no es cero.
WSAENETDOWN	Se ha producido un error en el subsistema de red.
WSAENOPROTOOPT	La opción de socket no se admite en el protocolo especificado.
WSAENOTCONN	El socket s no está conectado.
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 IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE. Este error también se devuelve cuando se intenta usar el IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE en un socket de datagrama.

Comentarios

El IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE es compatible con Windows Server 2008, Windows Vista con Service Pack 1 (SP1) y las versiones posteriores del sistema operativo.

Al enviar datos a través de una conexión TCP mediante sockets de Windows, es importante mantener una cantidad suficiente de datos pendientes (enviados pero no confirmados todavía) en TCP para lograr el mayor rendimiento. El valor ideal para la cantidad de datos pendientes para lograr el mejor rendimiento para la conexión TCP se denomina tamaño ideal de trabajo pendiente de envío (ISB). El valor de ISB es una función del producto de retraso de ancho de banda de la conexión TCP y la ventana de recepción anunciada del receptor (y en parte la cantidad de congestión en la red).

El valor de ISB por conexión está disponible en la implementación del protocolo TCP en Windows Server 2008, Windows Vista con SP1 y las versiones posteriores del sistema operativo. Una aplicación puede usar el IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE para recibir una notificación cuando el valor de ISB cambie dinámicamente para una conexión.

En Windows Server 2008, Windows Vista con SP1 y las versiones posteriores del sistema operativo, los IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE y SIO_IDEAL_SEND_BACKLOG_QUERY se admiten en sockets orientados a flujos que se encuentran en un estado conectado.

El intervalo para el valor ISB de una conexión TCP puede variar teóricamente de 0 a un máximo de 16 megabytes.

Consulte la página de referencia de IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY para ver el uso típico del mecanismo ISB con el fin de lograr un mejor rendimiento a través de conexiones de productos con retraso de ancho de banda alto.

El IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE solo se permite en un socket de flujo que esté en estado conectado. De lo contrario, se producirá un error en la función WSAIoctl o WSPIoctl con WSAENOTCONN.

El IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE no usa búferes de entrada o salida y se suspende o bloquea hasta que se produce un cambio de ISB en la conexión subyacente. Cuando se completa este IOCTL, una aplicación Winsock puede usar el IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY para recuperar el nuevo valor de ISB en la conexión.

El IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE no admite el modo de no bloqueo. Se permite que una aplicación emita este IOCTL en un socket sin bloqueo, pero el IOCTL simplemente se bloqueará o suspenderá hasta que cambie el valor de ISB.

Si los parámetros lpOverlapped y lpCompletionRoutine son NULL, el socket de esta función se tratará como un socket no superpuesto. En el caso de un socket no superpuesto, se omiten los parámetros lpOverlapped y lpCompletionRoutine, con la salvedad de que la función se puede bloquear si el socket s está en modo de bloqueo. Si el socket s está en modo de no bloqueo, esta función se bloqueará de todas maneras, ya que este IOCTL determinado no admite el modo de no bloqueo.

En el caso de los sockets superpuestos, se iniciarán las operaciones que no puedan completarse inmediatamente y se indicará su finalización más adelante.

Cualquier IOCTL puede bloquearse indefinidamente en función de la implementación del proveedor de servicios. Si la aplicación no puede tolerar el bloqueo en una llamada a la función WSAIoctl o WSPIoctl, se recomiendan las E/S superpuestas para los IOCTL que sean particularmente propensos a bloquearse.

El IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE proporciona una notificación y, en principio, se bloqueará o quedará pendiente hasta que cambie el valor ISB. Por lo tanto, normalmente se llamaría de forma asincrónica con el parámetro lpOverlapped establecido en una estructura WSAOVERLAPPED válida.

El IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE puede producir un error con WSAEINTR o WSA_OPERATION_ABORTED en los casos siguientes:

La conexión TCP se desconecta correctamente en la dirección de envío. Esto puede producirse como resultado de una llamada a la función de apagado con el parámetro how establecido en SD_SEND, una llamada a la función DisconnectEx o una llamada a la función TransmitFile o TransmitPackets con el parámetro dwFlags establecido en TF_DISCONNECT o TF_REUSE.
La conexión TCP se ha restablecido o anulado.
La aplicación emite un IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE cuando ya hay una solicitud de notificación pendiente. No se permite más de una solicitud SIO_IDEAL_SEND_BACKLOG_CHANGE pendiente a la vez.
El administrador de E/S cancela la solicitud.
El socket está cerrado.

En el archivo de encabezado Ws2tcpip.h se definen dos funciones de encapsulado insertadas para estos IOCTL. Se recomienda usar estas funciones insertadas en lugar de usar directamente los IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE y SIO_IDEAL_SEND_BACKLOG_QUERY.

La función de encapsulado insertada para el IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE es la función idealsendbacklognotify.

La función de encapsulado insertada para el IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY es la función idealsendbacklogquery.