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

Статья
08/24/2023

Извлекает несколько записей портов завершения одновременно. Он ожидает завершения ожидающих операций ввода-вывода, связанных с указанным портом завершения.

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

Синтаксис

BOOL GetQueuedCompletionStatusEx(
  [in]  HANDLE             CompletionPort,
  [out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  [in]  ULONG              ulCount,
  [out] PULONG             ulNumEntriesRemoved,
  [in]  DWORD              dwMilliseconds,
  [in]  BOOL               fAlertable
);

Параметры

[in] CompletionPort

Дескриптор для порта завершения. Чтобы создать порт завершения, используйте функцию CreateIoCompletionPort .

[out] lpCompletionPortEntries

При входе указывает на предварительно выделенный массив OVERLAPPED_ENTRY структур.

В выходных данных получает массив OVERLAPPED_ENTRY структур, которые содержат записи. Количество элементов массива предоставляется ulNumEntriesRemoved.

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

[in] ulCount

Максимальное количество удаляемых записей.

[out] ulNumEntriesRemoved

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

[in] dwMilliseconds

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

Если параметр dwMilliseconds имеет значение INFINITE (0xFFFFFFFF), время ожидания функции никогда не будет истекает. Если значение dwMilliseconds равно нулю и операция ввода-вывода для вывода из очереди отсутствует, функция немедленно истекает.

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] fAlertable

Если этот параметр имеет значение FALSE, функция не возвращается до истечения времени ожидания или до получения записи.

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

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

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

Возвращает ненулевое значение (TRUE) в случае успешного выполнения или ноль (FALSE) в противном случае.

Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Эта функция возвращает значение TRUE при завершении хотя бы одного ожидающего выполнения операций ввода-вывода, но вполне возможно, что одна или несколько операций ввода-вывода завершилось сбоем. Обратите внимание, что пользователь этой функции должен проверка список возвращаемых записей в параметре lpCompletionPortEntries, чтобы определить, какие из них соответствуют любым возможным операциям ввода-вывода, завершившимся сбоем, путем просмотра состояния элемента lpOverlapped в каждом OVERLAPPED_ENTRY.

Эта функция возвращает значение FALSE , если операция ввода-вывода не была выведена из очереди. Обычно это означает, что произошла ошибка при обработке параметров для этого вызова или что дескриптор CompletionPort был закрыт или является недопустимым иным образом. Функция GetLastError предоставляет расширенные сведения об ошибке.

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

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

Дополнительные сведения о теории портов завершения ввода-вывода, использовании и связанных функциях см. в разделе Порты завершения ввода-вывода.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Требования

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