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

Статья
06/12/2023

Описание

Код элемента управления SIO_APPLY_TRANSPORT_SETTING применяет к сокету один или несколько параметров транспорта.

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING для этой операции.

lpvInBuffer

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

cbInBuffer

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

lpvOutBuffer

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

cbOutBuffer

Размер выходного буфера в байтах.

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	Операция блокировки была прервана вызовом WSACancelBlockingCall. Эта ошибка возвращается, если операция блокировки была прервана.
WSAEINVAL	Указан недопустимый аргумент. Эта ошибка возвращается, если параметр dwIoControlCode не является допустимой командой, или указанный входной параметр недопустим или команда не применима к указанному типу сокета.
WSAENETDOWN	Операция на сокете обнаружила отключение сети. Эта ошибка возвращается, если произошел сбой сетевой подсистемы.
WSAENOTSOCK	Предпринята попытка выполнения операции с тем, что не является сокетом. Эта ошибка возвращается, если дескриптор не является сокетом.
WSAEOPNOTSUPP	Предпринятая операция не поддерживается для типа объекта, на который ссылается ссылка. Эта ошибка возвращается, если указанная команда IOCTL не поддерживается. Эта ошибка также возвращается, если поставщик транспорта не поддерживает SIO_APPLY_TRANSPORT_SETTING IOCTL. Эта ошибка также возвращается при попытке использовать SIO_APPLY_TRANSPORT_SETTING IOCTL в сокете, отличном от UDP или TCP.

SIO_APPLY_TRANSPORT_SETTING IOCTL — это универсальный IOCTL, используемый для применения параметра транспорта к сокету. Применяемый параметр транспорта основан на TRANSPORT_SETTING_ID , переданном в параметре lpvInBuffer .

Начиная с Windows 8 и Windows Server 2012 система определяет возможность REAL_TIME_NOTIFICATION_CAPABILITY в сокете TCP. Начиная с Windows 10 и Windows Server 2016 также определяется ASSOCIATE_NAMERES_CONTEXT. Дополнительные сведения см. в разделах addrinfoex4 и ASSOCIATE_NAMERES_CONTEXT_INPUT.

Если для TRANSPORT_SETTING_ID , переданного в параметре lpvInBuffer, для элемента Guid задано значение REAL_TIME_NOTIFICATION_CAPABILITY, то это запрос на применение параметров уведомлений в режиме реального времени для сокета TCP, используемого с ControlChannelTrigger для получения фоновых сетевых уведомлений в приложении Магазина Windows. Параметр lpvInBuffer должен указывать на структуру REAL_TIME_NOTIFICATION_SETTING_INPUT . Параметр lpvOutBuffer не используется для этой операции. Этот параметр транспорта применяется только к сокетам TCP. Этот параметр транспорта позволяет winInet или аналогичным сетевым службам пометить заданный сокет TCP как включенный ControlChannelTrigger . Windows помечает соответствующий сокет TCP и настроит соответствующие параметры оборудования и программного обеспечения при вызове этого параметра. Приложение Магазина Windows не будет вызывать этот IOCTL напрямую.