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

Статья
11/08/2024

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

Чтобы отменить пакеты завершения ввода-вывода по одному за раз, используйте функцию 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.

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

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

Windows 8 и более поздней версии, Windows Server 2012 и более поздней версии: значение dwMilliseconds dwMilliseconds не включает время, затраченное на низкое питание. Например, время ожидания не продолжает подсчитывать во время сна компьютера.

[in] fAlertable

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

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

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

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

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

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

Замечания

Эта функция связывает поток с указанным портом завершения. Поток может быть связан по крайней мере с одним портом завершения.

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

Эта функция возвращает FALSE, если операция ввода-вывода не была отложена. Обычно это означает, что при обработке параметров для этого вызова произошла ошибка или что дескриптор завершения завершения был закрыт или недействителен. Функция 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]
целевая платформа	Виндоус
заголовка	ioapiset.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll