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

Статья
05/30/2024

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

Синтаксис

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 помещается в очередь.

Значение 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