Функция обратного вызова LPWSPGETOVERLAPPEDRESULT (ws2spi.h)

Статья
08/28/2023

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

Синтаксис

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Параметры

[in] s

Определяет сокет. Это тот же сокет, который был указан при запуске перекрывающейся операции вызовом LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo или LPWSPIoctl.

[in] lpOverlapped

Указатель на структуру WSAOverlapped , указанную при запуске перекрывающейся операции.

[out] lpcbTransfer

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

[in] fWait

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

[out] lpdwFlags

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

[out] lpErrno

Указатель на код ошибки.

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

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

Код ошибки	Значение
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOTSOCK	Дескриптор не является сокетом.
WSA_INVALID_HANDLE	Член hEvent структуры WSAOverlapped не содержит допустимый дескриптор объекта события.
WSAEINVAL	Один из параметров недопустим.
WSA_IO_INCOMPLETE	Параметр fWait имеет значение FALSE, а операция ввода-вывода еще не завершена.

Результаты, сообщаемые функцией LPWSPGetOverlappedResult , являются результатами последней перекрывающейся операции указанного сокета, для которой была предоставлена указанная структура WSAOverlapped и для которой ожидались результаты операции. Ожидающая операция указывается, когда функция, которая запустила операцию, возвращает SOCKET_ERROR, а lpErrno WSA_IO_PENDING. Когда операция ввода-вывода находится в состоянии ожидания, функция, которая запустила операцию, сбрасывает элемент hEvent структуры WSAOVERLAPPED в состояние без знака. Затем, когда ожидающая операция будет завершена, система устанавливает для объекта события сигнальное состояние.

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

Примечание

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

Взаимодействие с WPUCompleteOverlappedRequest

Поведение WPUCompleteOverlappedRequest накладывает некоторые ограничения на то, как поставщик услуг реализует LPWSPGetOverlappedResult , так как только члены Offset и OffsetHigh структуры WSAOverlapped управляются исключительно поставщиком услуг, хотя три значения (количество байтов, флаги и ошибки) должны быть извлечены из структуры LPWSPGetOverlappedResult. Поставщик услуг может сделать это любым выбранным способом, если он правильно взаимодействует с поведением WPUCompleteOverlappedRequest . В следующем описании представлена типичная реализация:

В начале перекрывающейся обработки поставщик услуг устанавливает значение Internal для WSS_OPERATION_IN_PROGRESS.

После завершения операции ввода-вывода поставщик присваивает offsetHigh коду ошибки Windows Sockets 2, полученному в результате операции, присваивает параметру Offset флаги, полученные в результате операции ввода-вывода, и вызывает wpUCompleteOverlappedRequest, передавая число байтов передачи в качестве одного из параметров. WPUCompleteOverlappedRequest в конечном итоге устанавливает InternalHigh в значение счетчика байтов передачи, а затем задает значение Internal для значения, отличного от WSS_OPERATION_IN_PROGRESS.

При вызове LPWSPGetOverlappedResult поставщик услуг проверяет внутренний. Если это WSS_OPERATION_IN_PROGRESS, поставщик ожидает дескриптора события в элементе hEvent или возвращает ошибку на основе параметра флага fWaitLPWSPGetOverlappedResult. Если не выполняется или после завершения ожидания, поставщик возвращает значения из InternalHigh, OffsetHigh и Offset в качестве счетчика передачи, кода ошибки результата операции и флагов соответственно.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхняя часть	ws2spi.h