Функция GetQueuedCompletionStatus

Функция GetQueuedCompletionStatus пытается исключить из очереди пакет завершения ввода - вывода из указанного порта завершения I/O. Если в очереди нет пакета завершения, функция ожидает завершения незаконченной операции ввода-вывода (I/O), связанной с портом завершения.

Синтаксис

Параметры

CompletionPort

lpNumberOfBytes

lpCompletionKey

lpOverlapped

Нижеследующие функции могут использоваться, чтобы запускать операции ввода-вывода (I/O), которые заканчивают работу, используя порты завершения . Вы должны передавать этим функциям структуру  OVERLAPPED и дескриптор файла, связанный с портом завершения (вызовом CreateIoCompletionPort, чтобы активизировать механизм порта завершения ввода-вывода (I/O):

• ConnectNamedPipe
• DeviceIoControl
• LockFileEx
• ReadDirectoryChangesW
• ReadFile
• TransactNamedPipe
• WaitCommEvent
• WriteFile

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

dwMilliseconds

Если параметр dwMilliseconds определен как INFINITE (БЕСКОНЕЧЕНО), функция никогда не будет останавливаться. Если dwMilliseconds равняется нулю и нет никакой операции ввода-вывода (I/O), которую надо исключить из очереди, функция остановится немедленно.

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

Если функция исключает из очереди пакет окончания работы в следствие успешной операции I/O порта завершения, возвращаемое значение - не нуль. Функция хранит информацию в переменных, на которые указывают параметры lpNumberOfBytesTransferred, lpCompletionKey и lpOverlapped.

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

Если параметр *lpOverlapped - не NULL, а функция исключает из очереди пакет окончания работы из-за ошибки завершения операции ввода-вывода (I/O) порта завершения, величина возвращаемого значения - нуль. Функция хранит информацию в переменных, на которые указывают параметры lpNumberOfBytes, lpCompletionKey и lpOverlapped. Чтобы получить дополнительные данные об ошибке, вызовите GetLastError.

Если дескриптор сокета, связанного с портом завершения закрыт, функция GetQueuedCompletionStatus возвращает значение ERROR_SUCCESS, с параметром *lpOverlapped равным не NULL и lpNumberOfBytes равным нулю.

Замечания

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

Система ввода - вывода может быть проинструктирована так, чтобы отправлять уведомления о пакетах завершении портам завершения, где они поставлены в очередь. Функция CreateIoCompletionPort обеспечивает механизм для этого действия.

Когда Вы исполняете операцию ввода/вывода с дескриптором файла, который связан с портом окончания работы ввода/вывода , система I/O отправляет уведомление порту завершения о пакете окончания работы, когда заканчивается операция ввода-вывода (I/O). Порт завершения помещает пакет завершения в очередь по принципу "первым вошел - первым вышел". Функция GetQueuedCompletionStatus извлекает эти пакеты завершения из очереди.

Серверное приложение может иметь несколько потоков, вызывающих функцию GetQueuedCompletionStatus для одного и того же порта завершения. Как только завершается операция ввода, операционная система ставит в очередь пакеты окончания работы порта завершения. Если потоки активно дожидаются вызова этой функции, очередные запросы завершают их вызов. Для получения дополнительной информации, см. статью Порты завершения ввода-вывода (I/O).

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

Код примера

Пример, см. в статье Чтение асинхроно с портами завершения ввода-вывода данных (I/O).

Смотри также

Обзор Управление файлами, Функции для файлового ввода-вывода (I/O), ConnectNamedPipe, CreateIoCompletionPort, DeviceIoControl, LockFileEx, OVERLAPPED, ReadFile, PostQueuedCompletionStatus, TransactNamedPipe, WaitCommEvent, WriteFile