Функция GetOverlappedResult

Функция GetOverlappedResult извлекает результаты асинхронной (перекрывающей) операции с указанным файлом, именованным каналом или с устройством коммуникации.

Синтаксис

Параметры

hFile

[in] Дескриптор файла, именованного канала или устройства коммуникации. Это тот же самый дескриптор, который определялся, когда асинхронная (перекрывающая) операция запускалась вызовом функции ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl или WaitCommEvent.

lpOverlapped

[in] Указатель на структуру OVERLAPPED, которая определялась, когда запускалась асинхронная операция.

lpNumberOfBytesTransferred

[out] Указатель на переменную, получающую число байтов, которые были фактически переданы при операции чтения или записи. Для операции с функцией TransactNamedPipe - это число байтов, которые были прочитаны из канала. Для операции с функцией DeviceIoControl - это число байтов выводимых данных, возвращенных драйвером устройства. Для операций с функциями ConnectNamedPipe или WaitCommEvent это значение не определяется.

bWait

[in] Если этот параметр ИСТИНА (TRUE), функция не возвращает значение до тех пор, пока операция не будет завершена. Если этот параметр ЛОЖЬ (FALSE), а операция все еще находится в ожидании завершения, функцией возвращается ЛОЖЬ (FALSE), а функция GetLastError возвращает ошибку ERROR_IO_INCOMPLETE.

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

Если функция завершается успешно, возвращаемое значение - не нуль.

Если функция завершается ошибкой, возвращаемое значение - нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.

Замечания

Результаты, о которых сообщает функция GetOverlappedResult, являются такими исходя из последней асинхронной (перекрывающей) операции  указанного дескриптора, для которого предназначалась указанная структура OVERLAPPED, и для которого результаты операции ожидают обработки. Отложенная обработка назначается тогда, когда функция, которая начала операцию возвратила ЛОЖЬ (FALSE), а функция GetLastError возвратила ERROR_IO_PENDING. Когда операция ввода/вывода (I/O) находится в ожидании, функция, которая начала операцию, возвращает в исходное положение (сбрасывает) член hEvent структуры OVERLAPPED в несигнальное состоянию. Затем, когда ждущая обработки (незаконченная) операция будет завершена, система устанавливает объект "событие" в сигнальное состояние.

Установите вручную возврат в исходное состояние объекта "событие" в структуре OVERLAPPED. Если объект "событие" использует автоматический возврат в исходное состояние (автосброс), дескриптор события не должен определяться ни в какой другой операции "занять" в интервале между стартом асинхронной операции и вызовом в GetOverlappedResult. Например, объект "событие" иногда определяется в одной из ждущихся функций, чтобы ждать завершения операции. Когда функция ожидания возвращает значение, система устанавливает состояние события автовозвратом в несигнальное состояние, а последующий вызов функции GetOverlappedResult с установкой параметра bWait в значение ИСТИНА (TRUE), становится причиной блокирования функции на неопределенное время.

Если параметр bWait - ИСТИНА (TRUE), GetOverlappedResult определяет, была ли незаконченная операция завершена при ожидании объекта "событие", чтобы быть в сигнальном состоянии.

Если член hEvent структуры OVERLAPPED - NULL, система использует состояние дескриптора hFile, чтобы сообщить, когда операция была завершена. Использование дескрипторов файла, именованного канала или устройства коммуникаций с этой целью препятствует нормальной работе. Более безопасно использовать объект "событие" тогда, когда есть опасность беспорядка, который может произойти, если несколько асинхронных операций одновременно выполняются на том же самом файле, именованном канале или устройстве коммуникации. В этой ситуации, нет какого-либо способа узнать, какая операция заставила объект быть в сигнальном состоянии.

Демонстрационный код

Пример, который использует функцию GetOverlappedResult, см. в статье Обнаружение конца файла.

Смотри также

Обзор Асинхронный ввод и вывод данных, Функции, используемые при синхронизации, CancelIo, ConnectNamedPipe, CreateEvent, DeviceIoControl, GetLastError, OVERLAPPED,  ReadFile,  TransactNamedPipe, WaitCommEvent, WriteFile