Функция WSAIoctl (winsock2.h)
Функция WSAIoctl управляет режимом сокета.
Синтаксис
int WSAAPI WSAIoctl(
[in] SOCKET s,
[in] DWORD dwIoControlCode,
[in] LPVOID lpvInBuffer,
[in] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Параметры
[in] s
Дескриптор, определяющий сокет.
[in] dwIoControlCode
Управляющий код выполняемой операции. См . раздел Winsock IOCTLs.
[in] lpvInBuffer
Указатель на входной буфер.
[in] cbInBuffer
Размер входного буфера (в байтах).
[out] lpvOutBuffer
Указатель на выходной буфер.
[in] cbOutBuffer
Размер выходного буфера (в байтах).
[out] lpcbBytesReturned
Указатель на фактическое количество байтов выходных данных.
[in] lpOverlapped
Указатель на структуру WSAOVERLAPPED (игнорируется для неперекрывающихся сокетов).
[in] lpCompletionRoutine
Тип: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Возвращаемое значение
После успешного завершения WSAIoctl возвращает ноль. В противном случае возвращается значение SOCKET_ERROR, а определенный код ошибки можно получить, вызвав WSAGetLastError.
| Код ошибки | Значение |
|---|---|
| Перекрываемая операция была успешно инициирована, а завершение будет указано позже. | |
| Произошел сбой сетевой подсистемы. | |
| Параметр lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped или lpCompletionRoutine не полностью содержится в допустимой части адресного пространства пользователя или слишком мал параметр cbInBuffer или cbOutBuffer . | |
| Параметр dwIoControlCode не является допустимой командой, заданный входной параметр недопустим, или команда не применима к указанному типу сокета. | |
| Функция вызывается при выполнении обратного вызова. | |
| Дескриптор s не является сокетом. | |
| Указанная команда IOCTL не может быть реализована. (Например, структуры FLOWSPEC , указанные в SIO_SET_QOS или SIO_SET_GROUP_QOS , не могут быть удовлетворены.) | |
| Сокет помечается как неблокирующий, и запрошенная операция будет блокироваться. | |
| Параметр сокета не поддерживается в указанном протоколе. Например, была предпринята попытка использовать SIO_GET_BROADCAST_ADDRESS IOCTL в сокете IPv6 или попытка использовать TCP-SIO_KEEPALIVE_VALS IOCTL в сокете датаграмм. |
Комментарии
Функция WSAIoctl используется для задания или получения операционных параметров, связанных с сокетом, транспортным протоколом или подсистемой связи.
Если и lpOverlapped , и lpCompletionRoutine имеют значение NULL, сокет в этой функции будет рассматриваться как неперекрытый сокет. Для неперекрывающихся сокетов параметры lpOverlapped и lpCompletionRoutine игнорируются, что приводит к поведении функции, аналогичной стандартной функции ioctlsocket , за исключением того, что функция может блокировать, если сокет находится в режиме блокировки. Если сокет находится в режиме без блокировки, эта функция может возвращать WSAEWOULDBLOCK, если указанная операция не может быть немедленно завершена. В этом случае приложение может переключить сокет в режим блокировки и повторно отправить запрос или дождаться соответствующего сетевого события (например, FD_ROUTING_INTERFACE_CHANGE или FD_ADDRESS_LIST_CHANGE в случае SIO_ROUTING_INTERFACE_CHANGE или SIO_ADDRESS_LIST_CHANGE) с помощью сообщения Windows (с помощью WSAsyncSelect) или механизма уведомления на основе события (с помощью WSAEventSelect).
Для перекрывающихся сокетов будут инициированы операции, которые не могут быть завершены немедленно, а завершение будет указано позже. Значение DWORD , на которое указывает возвращаемый параметр lpcbBytesReturned , может игнорироваться. Окончательное состояние завершения и возвращаемые байты можно получить, когда соответствующий метод завершения получает сигнал о завершении операции.
Любой IOCTL может блокироваться на неопределенный срок в зависимости от реализации поставщика услуг. Если приложение не допускает блокировки в вызове WSAIoctl , перекрывающиеся операции ввода-вывода будут рекомендованы для списков IOCTL, которые особенно часто блокируются, в том числе:
SIO_ADDRESS_LIST_CHANGE
SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_SET_QOS
SIO_SET_GROUP_QOS
Некоторые ioCTL, относящиеся к протоколу, также могут быть особенно склонны к блокировке. Проверьте соответствующее приложение для конкретного протокола, чтобы получить любую доступную информацию.
Прототип подпрограммы завершения, на которую указывает параметр lpCompletionRoutine , выглядит следующим образом:
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
void CALLBACK CompletionRoutine (
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine — это заполнитель для имени функции, предоставленной приложением. Параметр dwError указывает состояние завершения перекрывающейся операции, как указано в параметре lpOverlapped . Параметр cbTransferred указывает количество полученных байтов. Параметр dwFlags не используется для этого IOCTL. Подпрограмма завершения не возвращает значение.
Можно использовать схему кодирования, которая сохраняет определенные в настоящее время операционные коды ioctlsocket , предоставляя удобный способ секционирования пространства идентификаторов кода операций на столько, сколько параметр dwIoControlCode теперь является 32-разрядной сущностью. Параметр dwIoControlCode создан для обеспечения независимости протокола и поставщика при добавлении новых кодов элементов управления при сохранении обратной совместимости с сокетами Windows 1.1 и кодами элементов управления Unix. Параметр dwIoControlCode имеет следующую форму.
| I | O | V | T | Семейство поставщиков или адресов | Код |
|---|---|---|---|---|---|
| 3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
| 1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
O устанавливается, если выходной буфер действителен для кода, как и в случае с IOC_OUT. Коды управления с помощью входных и выходных буферов задают как I, так и O.
V устанавливается, если для кода нет параметров, как в случае с IOC_VOID.
T — это 2-битовое количество, определяющее тип IOCTL. Определяются следующие значения:
0 IOCTL — это стандартный код IOCTL Unix, как и FIONREAD и FIONBIO.
1 IOCTL — это универсальный код IOCTL windows Sockets 2. Новые коды IOCTL, определенные для сокетов Windows 2, будут иметь T == 1.
2 IOCTL применяется только к определенному семейству адресов.
3 IOCTL применяется только к поставщику определенного поставщика, как и IOC_VENDOR. Этот тип позволяет назначить компаниям номер поставщика, который отображается в параметре семейства "Поставщик/адрес ". Затем поставщик может определить новые ioCTL, относящиеся к этому поставщику, без необходимости регистрировать IOCTL в клиринговом центре, обеспечивая тем самым гибкость и конфиденциальность поставщика.
Семейство поставщиков и адресов 11-битовое количество, определяющее поставщика, которому принадлежит код (если T == 3) или содержит семейство адресов, к которому применяется код (если T == 2). Если это код IOCTL Unix (T == 0), то этот параметр имеет то же значение, что и код в Unix. Если это универсальный IOCTL сокетов Windows 2 (T == 1), этот параметр можно использовать в качестве расширения параметра кода для предоставления дополнительных значений кода.
Код 16-разрядное количество, содержащее конкретный код IOCTL для операции.
Поддерживаются следующие коды IOCTL Unix (команды).
Поддерживаются следующие команды Windows Sockets 2.
Если перекрывающаяся операция завершается немедленно, WSAIoctl возвращает нулевое значение, а параметр lpcbBytesReturned обновляется на количество байтов в выходном буфере. Если перекрывающаяся операция успешно инициирована и завершится позже, эта функция возвращает SOCKET_ERROR и указывает код ошибки WSA_IO_PENDING. В этом случае lpcbBytesReturned не обновляется. Когда перекрываемая операция завершается, объем данных в выходном буфере указывается либо с помощью параметра cbTransferred в подпрограмме завершения (если указано), либо с помощью параметра lpcbTransfer в WSAGetOverlappedResult.
При вызове с перекрывающимся сокетом параметр lpOverlapped должен быть действителен в течение всего времени перекрывающейся операции. Параметр lpOverlapped содержит адрес структуры WSAOVERLAPPED .
Если параметр lpCompletionRoutine имеет значение NULL, параметр hEventlpOverlapped получает сигнал о завершении перекрывающейся операции, если он содержит допустимый дескриптор объекта события. Приложение может использовать WSAWaitForMultipleEvents или WSAGetOverlappedResult для ожидания или опроса объекта события.
Ниже приведен прототип процедуры завершения.
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Этот объект CompletionRoutine является заполнителем для определяемой приложением или библиотекой функции. Подпрограмма завершения вызывается только в том случае, если поток находится в состоянии предупреждения. Чтобы поместить поток в оповещенное состояние, используйте функцию WSAWaitForMultipleEvents, WaitForSingleObjectEx или WaitForMultipleObjectsEx с параметром fAlertable или bAlertable, равнымTRUE.
Параметр dwErrorпараметра CompletionRoutine указывает состояние завершения перекрывающейся операции, как указано в lpOverlapped. Параметр cbTransferred указывает количество возвращаемых байтов. В настоящее время значения флагов не определены, а dwFlags будет равно нулю. Функция CompletionRoutine не возвращает значение.
Возврат из этой функции позволяет использовать другую подпрограмму завершения для этого сокета. Подпрограммы завершения можно вызывать в любом порядке, не обязательно в том же порядке, в каком выполняются перекрывающиеся операции.
Совместимости
Коды IOCTL с T == 0 являются подмножеством кодов IOCTL, используемых в сокетах Беркли. В частности, не существует команды, эквивалентной FIOASYNC.Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8.1, Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | winsock2.h |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по