код элемента управления SIO_IDEAL_SEND_BACKLOG_CHANGE

Статья
10/11/2023

Description

Код элемента управления SIO_IDEAL_SEND_BACKLOG_CHANGE уведомляет приложение, когда идеальное значение невыполненной отправки (ISB) изменится для подключения.

Чтобы выполнить эту операцию, вызовите функцию WSAIoctl или WSPIoctl со следующими параметрами.

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.
);

Параметры

s

Дескриптор, определяющий сокет.

dwIoControlCode

Код элемента управления для операции. Используйте SIO_IDEAL_SEND_BACKLOG_CHANGE для этой операции.

lpvInBuffer

Указатель на входной буфер. Этот параметр не используется для этой операции.

cbInBuffer

Размер входного буфера в байтах. Этот параметр не используется для этой операции.

lpvOutBuffer

Указатель на выходной буфер. Этот параметр не используется для этой операции.

cbOutBuffer

Размер в байтах выходного буфера. Этот параметр должен иметь значение нулю.

lpcbBytesReturned

Указатель на переменную, которая получает размер в байтах данных, хранящихся в выходном буфере. Этот возвращаемый параметр указывает на значение DWORD нулевого значения для этой операции, так как выходные данные отсутствуют.

lpvOverlapped

Указатель на структуру WSAOVERLAPPED .

Если сокет был создан без перекрываемого атрибута, параметр lpOverlapped игнорируется.

Если s был открыт с перекрывающимся атрибутом и параметром lpOverlapped не равно NULL, операция выполняется как перекрываемая (асинхронная) операция. В этом случае параметр lpOverlapped должен указывать на допустимую структуру WSAOVERLAPPED.

Для перекрывающихся операций функция WSAIoctl или WSPIoctl возвращается немедленно, а соответствующий метод завершения сигнализирует о завершении операции. В противном случае функция не возвращается до завершения операции или ошибки.

lpCompletionRoutine

Тип: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Указатель на подпрограмму завершения, вызываемую при завершении операции (игнорируется для не перекрывающихся сокетов).

lpThreadId

Указатель на структуру WSATHREADID, которая будет использоваться поставщиком в последующем вызове WPUQueueApc. Поставщик должен хранить ссылку на структуру WSATHREADID (а не указатель на тот же) до тех пор, пока функция WPUQueueApc не возвращается.

Обратите внимание, что этот параметр применяется только к функции WSPIoctl .

lpErrno

Указатель на код ошибки.

Обратите внимание, что этот параметр применяется только к функции WSPIoctl .

Возвращаемое значение

Если операция выполнена успешно, функция WSAIoctl или WSPIoctl возвращает ноль.

Если операция завершается ошибкой или ожидается, функция WSAIoctl или WSPIoctl возвращает SOCKET_ERROR. Чтобы получить расширенные сведения об ошибке, вызовите WSAGetLastError.

Код ошибки	Значение
WSA_IO_PENDING	Операция, перекрываемая, была успешно инициирована, а завершение будет указано позже.
WSA_OPERATION_ABORTED	Перекрываемая операция была отменена из-за закрытия сокета или выполнения команды IOCTL SIO_FLUSH .
WSAEFAULT	Параметр lpOverlapped или lpCompletionRoutine не полностью содержится в допустимой части адресного пространства пользователя.
WSAEINPROGRESS	Функция вызывается при выполнении обратного вызова.
WSAEINTR	Операция блокировки была прервана.
WSAEINVAL	Параметр dwIoControlCode не является допустимой командой, или указанный входной параметр недопустим, или команда не применима к указанному типу сокета. Эта ошибка возвращается, если параметр cbOutBuffer не равен нулю.
WSAENETDOWN	Сбой сетевой подсистемы.
WSAENOPROTOOPT	Параметр сокета не поддерживается в указанном протоколе.
WSAENOTCONN	Сокет не подключен.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Указанная команда IOCTL не поддерживается. Эта ошибка возвращается, если SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL не поддерживается поставщиком транспорта. Эта ошибка также возвращается при попытке использовать SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL на сокете диаграммы данных.

Замечания

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL поддерживается в Windows Server 2008, Windows Vista с пакетом обновления 1 (SP1) и более поздних версиях операционной системы.

При отправке данных через TCP-подключение с помощью сокетов Windows важно обеспечить достаточное количество незавершенных данных (отправленных, но еще не подтверждено) в TCP для достижения максимальной пропускной способности. Идеальное значение для объема данных, выдающегося для достижения оптимальной пропускной способности для TCP-подключения, называется идеальным размером невыполненной отправки (ISB). Значение ISB — это функция продукта задержки пропускной способности подключения TCP и объявленного окна получения приемника (отчасти количество заторможения в сети).

Значение ISB для каждого подключения доступно из реализации протокола TCP в Windows Server 2008, Windows Vista с пакетом обновления 1 (SP1) и более поздних версий операционной системы. SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL можно использовать приложением для получения уведомления при динамическом изменении значения ISB для подключения.

В Windows Server 2008, Windows Vista с пакетом обновления 1 (SP1) и более поздних версиях операционной системы SIO_IDEAL_SEND_BACKLOG_CHANGE и SIO_IDEAL_SEND_BACKLOG_QUERY IOCTLs поддерживаются в сокетах, ориентированных на поток, которые находятся в подключенном состоянии.

Диапазон значения ISB для TCP-подключения может теоретически отличаться от 0 до 16 мегабайт.

См. справочную страницу SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL для типичного использования механизма ISB для достижения лучшей пропускной способности по сравнению с подключениями продуктов с высокой задержкой пропускной способности.

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL разрешен только в сокете потока, который находится в подключенном состоянии. В противном случае функция WSAIoctl или WSPIoctl завершится ошибкой wSAENOTCONN.

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL не использует входные или выходные буферы и блоки или блоки до изменения ISB в базовом соединении. После завершения этого IOCTL приложение Winsock может использовать SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL для получения нового значения ISB в соединении.

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL не поддерживает режим неблокировки. Приложение может выдавать этот IOCTL в сокете без блокировки, но IOCTL будет просто блокировать или перо, пока значение ISB не изменится.

Если оба параметра lpOverlapped и lpCompletionRoutine имеют значение NULL, сокет в этой функции будет рассматриваться как не перекрывающийся сокет. Для не перекрывающегося сокета параметры lpOverlapped и lpCompletionRoutine игнорируются, за исключением того, что функция может блокировать, если сокет находится в режиме блокировки. Если сокеты находится в режиме без блокировки, эта функция по-прежнему блокируется, так как этот конкретный IOCTL не поддерживает режим неблокировки.

Для перекрывающихся сокетов операции, которые не могут быть выполнены немедленно, будут инициированы, а завершение будет указано позже.

Любой IOCTL может блокироваться на неопределенный срок в зависимости от реализации поставщика услуг. Если приложению не удается запретить блокировку в вызове функции WSAIoctl или WSPIoctl, для операций ввода-вывода, которые, скорее всего, будут блокироваться.

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL предоставляет уведомление и, как ожидается, блокирует или задается до изменения значения ISB. Поэтому обычно он называется асинхронно с параметром lpOverlapped , заданным для допустимой структуры WSAOVERLAPPED.

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL может завершиться сбоем с WSAEINTR или WSA_OPERATION_ABORTED в следующих случаях:

Tcp-подключение отключается в направлении отправки. Это может произойти в результате вызова функции завершения работы с параметром SD_SEND, вызовом функции DisconnectEx или вызовом функции TransmitFile или TransmitPackets с параметром dwFlags, установленным для TF_DISCONNECT или TF_REUSE.
Tcp-подключение было сброшено или прервано.
Приложение выдает SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL, если запрос на уведомление уже задан. Одновременно допускается только один заготовленный SIO_IDEAL_SEND_BACKLOG_CHANGE запрос.
Запрос отменяется диспетчером ввода-вывода.
Сокет закрыт.

Две встроенные функции-оболочки для этих операций ввода-вывода определяются в файле заголовка Ws2tcpip.h . Рекомендуется использовать эти встроенные функции вместо использования SIO_IDEAL_SEND_BACKLOG_CHANGE и SIO_IDEAL_SEND_BACKLOG_QUERY ioCTLs напрямую.

Встроенная функция-оболочка для SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL является идеальной функциейendbacklognotify .

Встроенная функция-оболочка для SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL является идеальной функциейendbacklogquery .