Código de control SIO_IDEAL_SEND_BACKLOG_CHANGE
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.