Функция WSARecvEx (mswsock.h)

Статья
08/25/2023

Функция WSARecvEx получает данные из подключенного сокета или ограниченного сокета без подключения. Функция WSARecvEx аналогична функции recv , за исключением того, что параметр flags используется только для возврата сведений. При получении частичного сообщения при использовании протокола datagram бит MSG_PARTIAL задается в параметре flags при возврате из функции.

Примечание Функция WSARecvEx — это специальное расширение для спецификации Сокетов Windows.

Синтаксис

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

Параметры

[in] s

Дескриптор, идентифицирующий подключенный сокет.

[out] buf

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

[in] len

Длина (в байтах) буфера, на который указывает параметр buf .

[in, out] flags

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

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

Если ошибка не возникает, WSARecvEx возвращает количество полученных байтов. Если подключение закрыто, возвращается ноль. Кроме того, при получении частичного сообщения в параметре flags задается бит MSG_PARTIAL. Если сообщение было получено полностью, MSG_PARTIAL не задан в флагах

В противном случае возвращается значение SOCKET_ERROR, а определенный код ошибки можно получить, вызвав WSAGetLastError.

Важно Для протокола потокового транспорта MSG_PARTIAL никогда не устанавливается при возврате из WSARecvEx. Эта функция работает аналогично функции recv для протоколов потокового транспорта.

Код ошибки	Значение
WSAECONNABORTED	Виртуальное подключение разорвано из-за тайм-аута или иного сбоя. Приложение должно закрыть сокет, поскольку он больше не может использоваться.
WSAECONNRESET	Виртуальное подключение было сброшено удаленной стороной путем прерывания. Приложение должно закрыть сокет, поскольку он больше не может использоваться. На сокете датаграмм UPD эта ошибка означает, что при выполнении предыдущей операции отправки было получено сообщение "Порт ICMP недоступен".
WSAEFAULT	Параметр buf не полностью содержится в допустимой части адресного пространства пользователя.
WSAEINPROGRESS	Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEINTR	Вызов (блокирующий) был отменен вызовом WSACancelBlockingCall .
WSAEINVAL	Сокет не был привязан к bind, или был указан неизвестный флаг, или MSG_OOB был указан для сокета с включенной SO_OOBINLINE или (только для сокетов потока байтов) значение len равно нулю или отрицательному.
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENETRESET	Для сокета, ориентированного на подключение, эта ошибка означает, что подключение было разорвано из-за активности действия, которое обнаружило сбой во время выполнения операции. Для сокета датаграмм эта ошибка указывает на то, что срок жизни истек.
WSAENOTCONN	Сокет не подключен.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	MSG_OOB указано, но сокет не является типом потока, например типом SOCK_STREAM, данные OOB не поддерживаются в домене связи, связанном с этим сокетом, или сокет является однонаправленным и поддерживает только операции отправки.
WSAESHUTDOWN	Сокет завершен; Невозможно использовать WSARecvEx в сокете после вызова завершения работыс параметром SD_RECEIVE или SD_BOTH.
WSAETIMEDOUT	Соединение было разорвано из-за сбоя в сети или отсутствия ответа от одноранговой системы.
WSAEWOULDBLOCK	Сокет помечается как неблокировочный, и операция получения будет заблокирована.
WSANOTINITIALISED	Перед использованием этой функции должен быть выполнен успешный вызов WSAStartup .

Функция WSARecvEx , которая является частью реализации Microsoft Windows Sockets 2, похожа на более распространенную функцию recv , за исключением того, что параметр flags используется для одной конкретной цели. Параметр flags используется для указания того, получено ли частичное или полное сообщение при использовании протокола, ориентированного на сообщения.

Значение, указываемое параметром flags , игнорируется на входных данных. Поэтому никакие флаги не могут передаваться в функцию WSARecvEx для изменения ее поведения. Значение, указываемое параметром flags , задается в выходных данных. Это отличается от функций recv и WSARecv , где значение, указываемое параметром flags на входе, может изменить поведение функции.

Функции WSARecvEx и recv работают одинаково для потоковых протоколов.

Параметр flags поддерживает две распространенные ситуации, в которых будет получено частичное сообщение:

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

Бит MSG_PARTIAL задается в значении, на которое указывает параметр flags при возврате из WSARecvEx при получении частичного сообщения. Если было получено полное сообщение, MSG_PARTIAL не задано в значении, указанном параметром flags .

Функция recv отличается от функции
Функции WSARecvEx и WSARecv в том, что функция recv всегда получает одно сообщение для каждого вызова транспортных протоколов, ориентированных на сообщения. Функция recv также не имеет средств для указания приложению, что полученные данные являются лишь частичным сообщением. Приложение должно создать собственный протокол для проверки того, является ли сообщение частичным или полным, путем проверки кода ошибки WSAEMSGSIZE после каждого вызова recv. Если буфер приложения меньше отправляемых данных, большая часть сообщения копируется в буфер пользователя и возвращается с кодом ошибки WSAEMSGSIZE. Последующий вызов recv получит следующую часть сообщения.

Приложения, написанные для транспортных протоколов, ориентированных на сообщения, должны быть закодированы для этой возможности, если размер сообщения не гарантируется протоколом передачи данных приложения. Приложение может использовать recv и управлять самим протоколом. Кроме того, приложение может использовать WSARecvEx и проверка, что бит MSG_PARTIAL задан в параметре flags.

Функция WSARecvEx предоставляет разработчику более эффективный способ проверки того, является ли полученное сообщение частичным или полным при постепенном поступлении очень большого сообщения. Например, если приложение отправляет сообщение в один мегабайт, транспортный протокол должен разбить сообщение, чтобы отправить его по физической сети. Теоретически транспортный протокол на принимающей стороне может буферивировать все данные в сообщении, но это будет довольно затратным с точки зрения ресурсов. Вместо этого можно использовать WSARecvEx , минимизируя затраты и устраняя необходимость в протоколе на основе приложения.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	mswsock.h (включая Mswsock.h)
Библиотека	Mswsock.lib
DLL	Mswsock.dll