Код элемента управления SIO_IDEAL_SEND_BACKLOG_QUERY

Статья
06/13/2023

Описание

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

Для выполнения этой операции вызовите функцию WSAIoctl или WSPIoctl со следующими параметрами.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_QUERY, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY для этой операции.

lpvInBuffer

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

cbInBuffer

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

lpvOutBuffer

Указатель на выходной буфер. Этот параметр должен указывать на тип данных ULONG , если параметры lpOverlapped и lpCompletionRoutine имеют значение NULL.

cbOutBuffer

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

lpcbBytesReturned

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

Если выходной буфер слишком мал, вызов завершается ошибкой, WSAGetLastError возвращает WSAEINVAL, а параметр lpcbBytesReturned указывает на значение DWORD , равное нулю.

Если lpOverlapped имеет значение NULL, значение DWORD , на которое указывает параметр lpcbBytesReturned , возвращаемое при успешном вызове, не может быть равным нулю.

Если параметр lpOverlapped не равен NULL для перекрывающихся сокетов, будут инициированы операции, которые не могут быть завершены немедленно, а завершение будет указано позже. Значение DWORD , на которое указывает возвращаемый параметр lpcbBytesReturned , может быть равным нулю, так как размер хранимых данных не может быть определен до завершения перекрывающейся операции. Окончательное состояние завершения можно получить, когда соответствующий метод завершения получает сигнал о завершении операции.

lpvOverlapped

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

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

Если объект был открыт с перекрывающимся атрибутом, а параметр 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	Параметр lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped или lpCompletionRoutine не полностью содержится в допустимой части адресного пространства пользователя.
WSAEINPROGRESS	Функция вызывается при выполнении обратного вызова.
WSAEINTR	Блокирующая операция была прервана.
WSAEINVAL	Параметр dwIoControlCode не является допустимой командой, или указанный входной параметр недопустим, либо команда не применима к указанному типу сокета. Эта ошибка возвращается, если параметр cbOutBuffer меньше размера типа данных ULONG .
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOPROTOOPT	Параметр сокета не поддерживается в указанном протоколе.
WSAENOTCONN	Сокет не подключен.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Указанная команда IOCTL не поддерживается. Эта ошибка возвращается, если SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL не поддерживается поставщиком транспорта. Эта ошибка также возвращается при попытке использовать SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL в сокете датаграммы.

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

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

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

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

Типичное использование SIO_IDEAL_SEND_BACKLOG_CHANGE и SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL основано на методе отправки, используемом приложениями. Рассматриваются два распространенных случая.

Приложения, которые выполняют один блокирующий или неблокирующий запрос на отправку за один раз, обычно используют внутреннюю буферизацию отправки Winsock для достижения достойной пропускной способности. Ограничение буфера отправки для заданного подключения управляется параметром сокета SO_SNDBUF . Для метода блокирующей и неблокирующей отправки ограничение буфера отправки определяет, сколько данных хранится в TCP. Если значение ISB для подключения превышает предел буфера отправки, пропускная способность, достигнутая при подключении, не будет оптимальной. Чтобы повысить пропускную способность, приложения могут задать ограничение буфера отправки на основе результата запроса ISB по мере появления уведомлений об изменениях в подключении.

Для приложений, использующих перекрывающийся метод отправки с несколькими незавершенными запросами на отправку, объем данных, хранящихся в TCP, определяется ограничением буфера отправки в Winsock и общим объемом данных, содержащихся в невыполненных перекрывающихся запросах на отправку. В этом случае приложения должны использовать значение ISB, чтобы определить, сколько незавершенных запросов на отправку они должны хранить и какой размер данных должен быть для каждого запроса на отправку. В идеале приложение должно пытаться выполнить следующее уравнение:

ISB value == send buffer limit + (number of simultaneous overlapped send requests * data length per send request)

Обратите внимание, что использование IOCTL ISB через сокеты TCP в приведенном выше способе может привести к увеличению использования памяти в обмен на повышенную пропускную способность при подключениях с высокой задержкой пропускной способности. Реализация TCP в Windows будет регулировать значения ISB по мере необходимости на основе общего использования системной памяти.

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

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

SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL вряд ли будет блокироваться, поэтому обычно он называется синхронно с параметрами lpOverlapped и lpCompletionRoutine, имеющими значение NULL.

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

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

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

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

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

В Windows 7 и Windows Server 2008 R2 добавлена динамическая буферизация отправки для TCP. По умолчанию динамическая буферизация отправки для TCP включена, если приложение не задает параметр сокета SO_SNDBUF в сокете потока.

Для запроса или настройки динамической буферизации отправки для TCP рекомендуется использовать netsh.

Текущее значение динамической буферизации отправки для TCP можно получить с помощью следующей команды:

netsh winsock show autotuning

Динамическую буферизацию отправки для TCP можно отключить с помощью следующей команды:

netsh winsock set autotuning off

Динамическую буферизацию отправки для TCP можно включить с помощью следующей команды:

netsh winsock set autotuning on

Хотя это не рекомендуется, динамическую буферизацию отправки можно отключить в приложении, задав для следующего значения реестра нулевое значение:

HKEY_LOCAL_MACHINE\SYSTEM\Current Control Set\Services\AFD\Parameters\DynamicSendBufferDisable

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

При динамической буферизации отправки в Windows 7 и Windows Server 2008 R2 использование SIO_IDEAL_SEND_BACKLOG_CHANGE и SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL требуется только в особых обстоятельствах.