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

Статья
03/08/2023

Функция WSAGetOverlappedResult извлекает результаты перекрывающейся операции в указанном сокете.

Синтаксис

BOOL WSAAPI WSAGetOverlappedResult(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD         lpcbTransfer,
  [in]  BOOL            fWait,
  [out] LPDWORD         lpdwFlags
);

Параметры

[in] s

Дескриптор, определяющий сокет.

Это тот же сокет, который был указан при запуске перекрывающейся операции вызовом любой из функций Winsock, поддерживающих перекрывающиеся операции. К этим функциям относятся AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets, WSARecv, WSARecvFrom , LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg, WSASendTo и WSAIoctl.

[in] lpOverlapped

Указатель на структуру WSAOVERLAPPED , указанную при запуске перекрывающейся операции. Этот параметр не должен быть указателем NULL .

[out] lpcbTransfer

Указатель на 32-разрядную переменную, получающую количество байтов, которые фактически были переданы операцией отправки или получения или функцией WSAIoctl . Этот параметр не должен быть указателем NULL .

[in] fWait

Флаг, указывающий, должна ли функция ожидать завершения ожидающей перекрывающейся операции. Если задано значение TRUE, функция не возвращается, пока операция не будет завершена. Если значение FALSE и операция по-прежнему находится в состоянии ожидания, функция возвращает значение FALSE , а функция WSAGetLastError возвращает WSA_IO_INCOMPLETE. Параметру fWait может быть присвоено значение TRUE, только если перекрываемая операция выбрала уведомление о завершении на основе событий.

[out] lpdwFlags

Указатель на 32-разрядную переменную, которая получит один или несколько флагов, дополняющих состояние завершения. Если перекрываемая операция была инициирована через WSARecv или WSARecvFrom, этот параметр будет содержать значение результатов для параметра lpFlags . Этот параметр не должен быть указателем NULL .

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

Если WSAGetOverlappedResult завершается успешно, возвращается значение TRUE. Это означает, что перекрывающаяся операция успешно завершена, а значение, на которое указывает lpcbTransfer , обновлено.

Если WSAGetOverlappedResult возвращает значение FALSE, это означает, что либо перекрывающаяся операция не завершена, перекрывающаяся операция завершена, но с ошибками, либо состояние завершения перекрывающейся операции не может быть определено из-за ошибок в одном или нескольких параметрах WSAGetOverlappedResult. При сбое значение, указанное lpcbTransfer , не будет обновлено. Используйте WSAGetLastError , чтобы определить причину сбоя (с помощью функции WSAGetOverlappedResult или связанной операции перекрытия).

Код ошибки	Значение
WSANOTINITIALISED	Перед использованием этой функции должен быть выполнен успешный вызов WSAStartup .
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOTSOCK	Дескриптор не является сокетом.
WSA_INVALID_HANDLE	Параметр hEvent структуры WSAOVERLAPPED не содержит допустимый дескриптор объекта события.
WSA_INVALID_PARAMETER	Один из параметров недопустим.
WSA_IO_INCOMPLETE	Параметр fWait имеет значение FALSE , а операция ввода-вывода еще не завершена.
WSAEFAULT	Один или несколько параметров lpOverlapped, lpcbTransfer или lpdwFlags не находятся в допустимой части адресного пространства пользователя. Эта ошибка возвращается, если параметр lpOverlapped, lpcbTransfer или lpdwFlags был пустым указателем в Windows Server 2003 и более ранних версиях.

Функция WSAGetOverlappedResult сообщает результаты перекрывающейся операции, указанной в параметре lpOverlapped для сокета, указанного в параметре s . Функция WSAGetOverlappedResult передает дескриптор сокета и структуру WSAOVERLAPPED , указанную при вызове перекрывающейся функции. Ожидающая операция указывается, когда функция, которая запустила операцию, возвращает значение FALSE , а функция WSAGetLastError возвращает WSA_IO_PENDING. Когда операция ввода-вывода, например WSARecv , находится в состоянии ожидания, функция, которая запустила операцию, сбрасывает элемент hEvent структуры WSAOVERLAPPED в состояние без знака. После завершения ожидающей операции система устанавливает для объекта события сигнальное состояние.

Если параметр fWait имеет значение TRUE, WSAGetOverlappedResult определяет, завершена ли ожидающая операция, ожидая, пока объект события будет находиться в состоянии сигнала. Клиент может задать для параметра fWait значение TRUE, но только если он выбрал уведомление о завершении на основе событий при запросе операции ввода-вывода. Если была выбрана другая форма уведомления, то использование параметра hEvent структуры WSAOVERLAPPED отличается, а параметр fWait имеет значение TRUE , что приводит к непредсказуемым результатам.

Если функция WSAGetOverlappedResult вызывается с параметром lpOverlapped, lpcbTransfer или lpdwFlags, равным NULL-указателю в Windows Vista, это приведет к нарушению доступа. Если функция WSAGetOverlappedResult вызывается с параметром lpOverlapped, lpcbTransfer или lpdwFlags, равным null-указателю в Windows Server 2003 и более ранних версиях, это приведет к возврату кода ошибки WSAEFAULT.

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

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone Windows Phone 8 и более поздних версий.

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