Функция GetQueuedCompletionStatusEx

2025-05-09

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

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

Синтаксис

BOOL WINAPI GetQueuedCompletionStatusEx(
  _In_  HANDLE             CompletionPort,
  _Out_ LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  _In_  ULONG              ulCount,
  _Out_ PULONG             ulNumEntriesRemoved,
  _In_  DWORD              dwMilliseconds,
  _In_  BOOL               fAlertable
);

Параметры

CompletionPort (Порт завершения)[in]

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

lpCompletionPortEntries[out]

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

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

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

ulCount[in]

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

ulNumEntriesУдалено[out]

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

dwMilliseconds[in]

Количество миллисекунд, в течение которых вызывающий объект готов ожидать появления пакета завершения на порту завершения. Если пакет завершения не появляется в течение указанного времени, функция прерывает время ожидания и возвращает 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 не включает время, затраченное в состояниях с низким энергопотреблением. Например, время ожидания не продолжает обратный отсчет, пока компьютер находится в спящем режиме.

fAlertable (с возможностью оповещения)[in]

Если этот параметр имеет значение 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 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

Требования

Требование	Ценность
Минимальный поддерживаемый клиент	Windows Vista [классические приложения \| Приложения UWP]
Минимальный поддерживаемый сервер	Windows Server 2008 [классические приложения \| Приложения UWP]
Заголовок	`IoAPI.h` (включить `Windows.h`) `WinBase.h` на Windows Server 2008 R2, Windows 7, Windows Server 2008 и Windows Vista (включительно `Windows.h`)
Библиотека	`Kernel32.lib`
Библиотека dll	`Kernel32.dll`