Функция GetQueuedCompletionStatus

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

Синтаксис

BOOL GetQueuedCompletionStatus(
  HANDLE CompletionPort,       // дескриптор порта завершения
  LPDWORD lpNumberOfBytes,     // передаваемые байты
  PULONG_PTR lpCompletionKey,  // код завершения файла
  LPOVERLAPPED *lpOverlapped,  // буфер
  DWORD dwMilliseconds         // необязательное значение паузы
);

Параметры

CompletionPort

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

lpNumberOfBytes

[out] Указатель на переменную, которая получает число байтов, перемещенных в ходе операции ввода-вывода (I/O), которая завершилась.

lpCompletionKey

[out] Указатель на переменную, которая получает значение кода завершения, связанного с дескриптором файла, операция ввода-вывода (I/O) которого завершилась. Код завершения - код на каждый файл, который определяется при вызове функции CreateIoCompletionPort.

lpOverlapped

[out] Указатель на переменную, получающую адрес структуры OVERLAPPED, которая была определена, когда началось завершение операции ввода-вывода (I/O).

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

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

dwMilliseconds

[in] Число миллисекунд, которое вызывающая программа будет ждать пакет завершения, чтобы появиться в порте завершения. Если пакет завершения не появляется в пределах указанного времени, функция останавливает работу, возвращает значение FALSE и устанавливает *lpOverlapped в значение NULL.

Если параметр 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

Размещение и совместимость GetQueuedCompletionStatus
К Windows Vista Да
л Windows XP Да
и Windows 2000 Professional Да
е Windows NT Workstation Да версии 3.5 и выше
н Windows Me Нет
т Windows 98 Нет
  Windows 95 Нет
 
С Windows Server 2008 Да
е Windows Server 2003 Да
р Windows 2000 Server Да
в Windows NT Server Да версии 3.5 и выше
е    
р    
Используемая библиотека Kernel32.lib
Используемая DLL kernel32.dll
Заголовочный файл  
- объявлено в Winbase.h
- включено в Windows.h
Unicode Нет
Замечания по платформе Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz