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

Статья
11/08/2024

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

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

Синтаксис

BOOL GetQueuedCompletionStatus(
  [in]  HANDLE       CompletionPort,
        LPDWORD      lpNumberOfBytesTransferred,
  [out] PULONG_PTR   lpCompletionKey,
  [out] LPOVERLAPPED *lpOverlapped,
  [in]  DWORD        dwMilliseconds
);

Параметры

[in] CompletionPort

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

lpNumberOfBytesTransferred

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

[out] lpCompletionKey

Указатель на переменную, которая получает значение ключа завершения, связанное с дескриптором файла, операция ввода-вывода которого завершена. Ключ завершения — это ключ для каждого файла, указанный в вызове CreateIoCompletionPort.

[out] lpOverlapped

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

Даже если вы передали функцию дескриптор файла, связанный с портом завершения и допустимой структурой OVERLAPPED, приложение может предотвратить уведомление порта завершения. Это делается путем указания допустимого дескриптора событий для элемента hEvent структуры OVERLAPPED и задания его низкого порядка. Допустимый дескриптор событий, бит которого имеет низкий порядок, запрещает завершение перекрываемого ввода-вывода в порт завершения.

[in] dwMilliseconds

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

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

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

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

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

Дополнительные сведения см. в разделе "Примечания".

Замечания

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

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

Windows Server 2003 и Windows XP: Закрытие дескриптора порта завершения во время вызова не приведет к ранее указанному поведению. Функция будет продолжать ждать, пока запись не будет удалена из порта или до истечения времени ожидания, если указано в качестве значения, отличного от INFINITE.

Если функция GetQueuedCompletionStatus успешно выполнена, она отменяет пакет завершения для успешной операции ввода-вывода из порта завершения и хранит сведения в переменных, указывающих на следующие параметры: lpNumberOfBytes, lpCompletionKeyи lpOverlapped. После сбоя (возвращаемое значение FALSE), эти же параметры могут содержать определенные сочетания значений следующим образом:

Если *lpOverlappedNULL, функция не отменяла пакет завершения из порта завершения. В этом случае функция не хранит сведения в переменных, на которые указываются параметры lpNumberOfBytes и lpCompletionKey, а их значения являются неопределенными.
Если *lpOverlapped не NULL, а функция отменяет пакет завершения для неудачной операции ввода-вывода из порта завершения, функция сохраняет сведения о неудачной операции в переменных, на которые указывает lpNumberOfBytes, lpCompletionKeyи lpOverlapped. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	ioapiset.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll