Функция GetOverlappedResultEx (ioapiset.h)

Статья
03/09/2023

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

Синтаксис

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Параметры

[in] hFile

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

[in] lpOverlapped

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

[out] lpNumberOfBytesTransferred

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

[in] dwMilliseconds

Интервал времени ожидания в миллисекундах.

Если значение dwMilliseconds равно нулю и операция по-прежнему выполняется, функция возвращает немедленно, а функция GetLastError возвращает ERROR_IO_INCOMPLETE.

Если параметр dwMilliseconds не равен нулю и операция по-прежнему выполняется, функция ожидает, пока объект не будет поставлен в очередь, подпрограмма завершения ввода-вывода или APC или истекает интервал перед возвратом. Используйте GetLastError для получения расширенных сведений об ошибке.

Если dwMilliseconds имеет значение INFINITE, функция возвращает только в том случае, если объект получает сигнал, подпрограмму завершения ввода-вывода или очередь APC.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 и Windows Server 2008 R2: Значение dwMilliseconds включает время, затраченное на состояния с низким энергопотреблением. Например, время ожидания продолжает отсчитывать, пока компьютер находится в спячьм режиме.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 и Windows Server 2016. Значение dwMilliseconds не включает время, затраченное на малое энергопотребление Государств. Например, время ожидания не продолжает отсчитывать, пока компьютер находится в спялом режиме.

[in] bAlertable

Если этот параметр имеет значение TRUE и вызывающий поток находится в состоянии ожидания, функция возвращает, когда система помещает в очередь подпрограмму завершения ввода-вывода или APC. Затем вызывающий поток запускает подпрограмму или функцию. В противном случае функция не возвращается, а подпрограмма завершения или функция APC не выполняются.

Подпрограмма завершения помещается в очередь при завершении функции ReadFileEx или WriteFileEx , в которой она была указана. Функция возвращает, а подпрограмма завершения вызывается только в том случае, если bAlertable имеет значение TRUE, а вызывающий поток является потоком, инициировавшем операцию чтения или записи. APC помещается в очередь при вызове QueueUserAPC.

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

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

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Распространенные коды ошибок:

Если параметр dwMilliseconds равен нулю и операция все еще выполняется, GetLastError возвращает ERROR_IO_INCOMPLETE.
Если параметр dwMilliseconds является ненулевым, а подпрограмма завершения ввода-вывода или APC поставлена в очередь, GetLastError возвращает WAIT_IO_COMPLETION.
Если значение dwMilliseconds не равно нулю и истекает указанный интервал времени ожидания, GetLastError возвращает WAIT_TIMEOUT.

Функция GetOverlappedResultEx отличается от Функции GetOverlappedResult следующим образом: параметр dwMilliseconds может указать интервал времени ожидания для операции, а параметр bAlertable может указать, что вызывающий поток должен выполнять ожидание с оповещением.

Результаты, сообщаемые функцией GetOverlappedResultEx , являются результатами последней перекрывающейся операции указанного дескриптора, для которой была предоставлена указанная структура OVERLAPPED и для которой ожидались результаты операции. Ожидающая операция указывается, когда функция, которая запустила операцию, возвращает значение FALSE, а функция GetLastError возвращает ERROR_IO_PENDING. Когда операция ввода-вывода находится в состоянии ожидания, функция, которая запустила операцию, сбрасывает элемент hEvent структуры OVERLAPPED в состояние без знака. После завершения ожидающей операции система присваивает объекту события состояние сигнального.

Укажите объект события сброса вручную в структуре OVERLAPPED . Если используется объект события автоматического сброса, дескриптор события не должен указываться в любой другой операции ожидания в интервале между запуском перекрывающейся операции и вызовом Метода GetOverlappedResultEx. Например, объект события иногда указывается в одной из функций ожидания для ожидания завершения операции. Когда функция ожидания возвращается, система устанавливает для события автоматического сброса состояние без знака, а последующий вызов GetOverlappedResultEx с параметром dwMilliseconds , равным INFINITE , приводит к блокировке функции на неопределенный срок.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	ioapiset.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll