Функция WSAPoll (winsock2.h)

  • Статья

Функция WSAPoll определяет состояние одного или нескольких сокетов.

Синтаксис

int WSAAPI WSAPoll(
  [in, out] LPWSAPOLLFD fdArray,
  [in]      ULONG       fds,
  [in]      INT         timeout
);

Параметры

[in, out] fdArray

Массив из одной или нескольких структур POLLFD , определяющих набор сокетов, для которых запрашивается состояние. Массив должен содержать по крайней мере одну структуру с допустимым сокетом. При возврате этот параметр получает обновленные сокеты с заданным для каждого члена флагов состояния revents , которые соответствуют критериям запроса о состоянии.

[in] fds

Количество структур WSAPOLLFD в fdarray. Это не обязательно количество сокетов, для которых запрашивается состояние.

[in] timeout

Значение типа , указывающее поведение ожидания на основе следующих значений.

Значение Значение
Больше нуля Время ожидания (в миллисекундах).
Ноль Вернитесь немедленно.
Меньше нуля Подождите неограниченное время.

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

Возвращает одно из следующих значений.

Возвращаемое значение Описание
Ноль До истечения срока действия таймера сокеты не находились в состоянии запроса.
Больше нуля Количество элементов в fdarray , для которых элемент revents структуры POLLFD не является нулями.
SOCKET_ERROR Произошла ошибка. Вызовите функцию WSAGetLastError , чтобы получить расширенный код ошибки.
 
Расширенный код ошибки Значение
WSAENETDOWN
 Произошел сбой сетевой подсистемы.
WSAEFAULT
 При чтении входных параметров пользователя возникло исключение.
WSAEINVAL
 Передан недопустимый параметр. Эта ошибка возвращается, если структуры WSAPOLLFD , на которые указывает параметр fdarray при запросе состояния сокета. Эта ошибка также возвращается, если ни один из сокетов, указанных в элементе fd любой из структур WSAPOLLFD , на которые указывает параметр fdarray , не был допустимым.
WSAENOBUFS
 Функции не удалось выделить достаточный объем памяти.

Комментарии

Функция WSAPoll определена в Windows Vista и более поздних версиях.

Структуры WSAPOLLFD . Приложение устанавливает соответствующие флаги в элементе событий структуры WSAPOLLFD , чтобы указать тип состояния, запрошенного для каждого соответствующего сокета. Функция WSAPoll возвращает состояние сокета в элементе revents структуры WSAPOLLFD .

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

Структура WSAPOLLFD , на которую указывает параметр fdarray . Для всех сокетов, которые не соответствуют этим критериям и не имеют условия ошибки, соответствующий член revents будет иметь значение 0.

При запросе состояния для этого сокета в структуре WSAPOLLFD можно задать сочетание следующих флагов:

Flag Описание
POLLPRI Приоритетные данные можно считывать без блокировки. Этот флаг не поддерживается поставщиком Microsoft Winsock.
POLLRDBAND Данные по диапазону приоритета (внеполосные) могут считываться без блокировки.
POLLRDNORM Обычные данные могут считываться без блокировки.
POLLWRNORM Обычные данные могут быть записаны без блокировки.
 

Флаг POLLIN определяется как сочетание значений флагов POLLRDNORM и POLLRDBAND . Флаг POLLOUT определяется как значение флага POLLWRNORM .

Структура WSAPOLLFD должна содержать только сочетание указанных выше флагов, поддерживаемых поставщиком Winsock. Все остальные значения считаются ошибками, и WSAPoll вернет SOCKET_ERROR. Последующий вызов функции WSAGetLastError извлекает расширенный код ошибки WSAEINVAL. Если флаг POLLPRI установлен в сокете для поставщика Microsoft Winsock, функция WSAPoll завершится ошибкой.

Когда структуры WSAPOLLFD , на которые указывает параметр fdarray для указания состояния сокета:

Flag Описание
POLLERR Произошла ошибка.
POLLHUP Потоковое подключение было либо отключено, либо прервано.
POLLNVAL Использовался недопустимый сокет.
POLLPRI Приоритетные данные можно считывать без блокировки. Этот флаг не возвращается поставщиком Microsoft Winsock.
POLLRDBAND Данные по диапазону приоритета (внеполосные) могут считываться без блокировки.
POLLRDNORM Обычные данные могут считываться без блокировки.
POLLWRNORM Обычные данные могут быть записаны без блокировки.
 

Что касается сокетов TCP и UDP:

  • Структура WSAPOLLFD как обычные данные , например POLLRDNORM.
  • Структура WSAPOLLFD, последующая операция recv гарантированно завершится без блокировки.
  • Структура WSAPOLLFDот POLLWRNORM.
  • Структура WSAPOLLFDот POLLRDNORM. Последующий вызов для принятия гарантированно завершится без блокировки.
  • Структура WSAPOLLFD от POLLRDBAND.
  • Структура WSAPOLLFD, когда удаленный одноранговый узел завершает операцию отправки (получен TCP FIN). Последующий запрос функции recv вернет ноль байтов.
  • Структура WSAPOLLFD, когда удаленный одноранговый узел инициирует корректное отключение.
  • Структура WSAPOLLFD возвращается при внезапном отключении удаленного однорангового узла.
  • Структура WSAPOLLFD при закрытии локального сокета.

Количество элементов (не сокетов) в fdarray обозначается nfds. Члены fdarray , у которых элемент fd имеет отрицательное значение, игнорируются, а их повторные события будут иметь значение POLLNVAL после возврата. Такое поведение полезно для приложения, которое поддерживает фиксированное выделение fdarray и не сжимает массив для удаления неиспользуемых записей или перераспределения памяти. Перед вызовом WSAPoll не нужно очищать повторные события для какого-либо элемента.

Аргумент времени ожидания указывает время ожидания функции перед возвратом. Положительное значение содержит количество миллисекундах, которое нужно ожидать перед возвратом. Нулевое значение приводит к немедленному возврату WSAPoll , а отрицательное значение указывает, что WSAPoll должен ждать неограниченное время.

Примечание При выполнении блокирующего вызова Winsock, например WSAPoll , с параметром времени ожидания , равным отрицательному числу, Winsock может потребоваться дождаться сетевого события, прежде чем вызов может завершиться. В этой ситуации Winsock выполняет оповещенное ожидание, которое может быть прервано асинхронным вызовом процедуры (APC), запланированным в том же потоке. Выполнение другого блокирующего вызова Winsock внутри APC, который прервал текущий блокирующий вызов Winsock в том же потоке, приведет к неопределенному поведению и никогда не должен выполняться клиентами Winsock.
 
Примечание Начиная с Windows 10 версии 2004, когда сокет TCP не удается подключиться, (POLLHUP \| POLLERR \| УКАЗАНО ЗНАЧЕНИЕ POLLWRNORM).
 

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Требования

Требование Значение
Минимальная версия клиента Windows 8.1, Windows Vista [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header winsock2.h (включая Winsock2.h)
Библиотека Ws2_32.lib
DLL Ws2_32.dll

См. также раздел

WSAGetLastError

WSAPOLLFD