Функция WPUCompleteOverlappedRequest (ws2spi.h)
Функция WPUCompleteOverlappedRequest выполняет уведомление о завершении перекрывающихся операций ввода-вывода.
Синтаксис
int WPUCompleteOverlappedRequest(
[in] SOCKET s,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] DWORD dwError,
[in] DWORD cbTransferred,
[out] LPINT lpErrno
);
Параметры
[in] s
Сокет поставщика услуг, созданный WPUCreateSocketHandle.
[in] lpOverlapped
Указатель на структуру WSAOVERLAPPED , связанную с перекрывающейся операцией ввода-вывода, о завершении которой требуется уведомить.
[in] dwError
Состояние завершения перекрывающейся операции ввода-вывода, о завершении которой необходимо уведомить.
[in] cbTransferred
Количество байтов, передаваемых в буферы клиента или из него (направление передачи зависит от характера отправки или получения перекрывающейся операции ввода-вывода, о завершении которой требуется уведомить).
[out] lpErrno
Указатель на код ошибки, полученный в результате выполнения этой функции.
Возвращаемое значение
Если ошибка не возникает, WPUCompleteOverlappedRequest возвращает ноль и уведомляет о завершении перекрывающейся операции ввода-вывода в соответствии с механизмом, выбранным клиентом (сигнализирует о событии, обнаруженном в структуре WSAOVERLAPPED , на которую ссылается lpOverlapped , и (или) помещает отчет о состоянии завершения в порт завершения, связанный с сокетом, если связан порт завершения). В противном случае WPUCompleteOverlappedRequest возвращает SOCKET_ERROR, а конкретный код ошибки доступен в lpErrno.
| Код ошибки | Значение |
|---|---|
| Сокет, передаваемый в параметре s, не является сокетом, созданным WPUCreateSocketHandle. |
Комментарии
Функция WPUCompleteOverlappedRequest выполняет уведомления о завершении перекрывающихся операций ввода-вывода для перекрывающихся операций ввода-вывода, где механизм завершения, заданный клиентом, отличается от асинхронного вызова процедур в пользовательском режиме (APC). Эта функция может использоваться только для дескрипторов сокетов, созданных WPUCreateSocketHandle.
Если клиент выбирает APC в пользовательском режиме в качестве метода уведомления, поставщик услуг должен использовать WPUQueueApc или другую соответствующую функцию операционной системы для выполнения уведомления о завершении. Если клиент не выбирает APC в пользовательском режиме, поставщик услуг, который не реализует функции IFS напрямую, не может определить, связан ли клиент с дескриптором сокета порт завершения. Таким образом, он не может определить, должен ли метод уведомления о завершении находиться в очереди записи о состоянии завершения в порт завершения или сигнализировать о событии, обнаруженном в структуре WSAOVERLAPPED . Архитектура Сокета Windows 2 отслеживает связь портов завершения с сокетом, созданным WPUCreateSocketHandle , и может принимать правильное решение между уведомлением о завершении на основе порта или уведомления на основе событий.
Когда WPUCompleteOverlappedRequest помещает в очередь признак завершения, он устанавливает для члена InternalHigh структуры WSAOVERLAPPED количество переданных байтов. Затем он задает для внутреннего члена некоторое зависимое от ОС значение, отличное от специального значения WSS_OPERATION_IN_PROGRESS. После возврата WPUCompleteOverlappedRequest может возникнуть небольшая задержка, так как обработка может выполняться асинхронно. Однако значение InternalHigh (количество байтов) гарантированно будет задано в течение времени , указанного в параметре Internal .
WPUCompleteOverlappedRequest работает как указано (выполняет уведомление о завершении по запросу клиента), независимо от того, связан ли дескриптор сокета с портом завершения.
Взаимодействие с WSPGetOverlappedResult
Поведение WPUCompleteOverlappedRequest накладывает некоторые ограничения на то, как поставщик услуг реализует WSPGetOverlappedResult , так как только члены Offset и OffsetHigh структуры WSAOVERLAPPED контролируются исключительно поставщиком услуг, но WSPGetOverlappedResult должен извлечь из структуры три значения (число байтов, флаги и ошибки). Поставщик услуг может сделать это любым выбранным способом, если он правильно взаимодействует с поведением WPUCompleteOverlappedRequest . Однако типичная реализация выглядит следующим образом:
- В начале перекрывающейся обработки поставщик услуг устанавливает значение Internal для WSS_OPERATION_IN_PROGRESS.
- После завершения операции ввода-вывода поставщик присваивает OffsetHigh коду ошибки Сокета Windows 2, полученному в результате операции, параметр Offset — флагам, полученным в результате операции ввода-вывода, и вызывает WPUCompleteOverlappedRequest, передавая число байтов передачи в качестве одного из параметров. WPUCompleteOverlappedRequest в конечном итоге устанавливает InternalHigh в значение счетчика байтов передачи, а затем задает значение Internal для значения, отличного от WSS_OPERATION_IN_PROGRESS.
- При вызове WSPGetOverlappedResult поставщик услуг проверяет внутренний. Если это WSS_OPERATION_IN_PROGRESS, поставщик ожидает дескриптора события в элементе hEvent или возвращает ошибку на основе параметра флага FWAIT WSPGetOverlappedResult. Если не выполняется или после завершения ожидания, поставщик возвращает значения из InternalHigh, OffsetHigh и Offset в качестве счетчика передачи, кода ошибки результата операции и флагов соответственно.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | ws2spi.h |