GetQueuedCompletionStatus

The GetQueuedCompletionStatus function attempts to dequeue an I/O completion packet from a specified input/output completion port. If there is no completion packet queued, the function waits for a pending input/output operation associated with the completion port to complete. The function returns when it can dequeue a completion packet, or optionally when the function times out. If the function returns because of an I/O operation completion, it sets several variables that provide information about the operation.

BOOL GetQueuedCompletionStatus(
  HANDLE CompletionPort,       // the I/O completion port of interest
  LPDWORD lpNumberOfBytesTransferred,
                               // to receive number of bytes 
                               // transferred during I/O
  LPDWORD lpCompletionKey,     // to receive file's completion key
  LPOVERLAPPED *lpOverlapped,  // to receive pointer to OVERLAPPED 
                               // structure
  DWORD dwMilliseconds         // optional timeout value
);
 

Parameters

CompletionPort

Handle to the input/output completion port of interest. I/O completion ports are created by the CreateIoCompletionPort function.

lpNumberOfBytesTransferred

Pointer to a variable that the function sets to the number of bytes transferred during an I/O operation that has completed.

lpCompletionKey

Pointer to a variable that the function sets to the completion key value associated with the file handle whose I/O operation has completed. A completion key is a per-file key that is specified in a call to CreateIoCompletionPort.

lpOverlapped

Pointer to a variable that the function sets to the address of the OVERLAPPED structure that was specified when the completed input/output operation was started.

The following functions can be used to start input/output operations that complete using I/O completion ports. You must pass the function an OVERLAPPED structure and a file handle associated (by a call to CreateIoCompletionPort) with an I/O completion port to invoke the I/O completion port mechanism:

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

Even if you have passed the function a file handle associated with a completion port and a valid OVERLAPPED structure, an application can prevent completion port notification. This is done by specifying a valid event handle for the hEvent member of the OVERLAPPED structure, and setting its low-order bit. A valid event handle whose low-order bit is set keeps I/O completion from being queued to the completion port.

dwMilliseconds

Specifies the number of milliseconds that the caller is willing to wait for an completion packet to appear at the I/O completion port. If a completion packet doesn't appear within the specified time, the function times out, returns FALSE, and sets *lpOverlapped to NULL.

If dwMilliseconds is INFINITE, the function will never time out. If dwMilliseconds is zero and there is no I/O operation to dequeue, the function will time out immediately.

Return Values

If the function dequeues a completion packet for a successful I/O operation from the completion port, the return value is nonzero. The function stores information in the variables pointed to by the lpNumberOfBytesTransferred, lpCompletionKey, and lpOverlapped parameters.

If *lpOverlapped is NULL and the function does not dequeue a completion packet from the completion port, the return value is zero. The function does not store information in the variables pointed to by the lpNumberOfBytesTransferred and lpCompletionKey parameters. To get extended error information, call GetLastError. If the function did not dequeue a completion packet because the wait timed out, GetLastError returns WAIT_TIMEOUT.

If *lpOverlapped is not NULL and the function dequeues a completion packet for a failed I/O operation from the completion port, the return value is zero. The function stores information in the variables pointed to by lpNumberOfBytesTransferred, lpCompletionKey, and lpOverlapped. To get extended error information, call GetLastError.

Remarks

The I/O system can be instructed to send I/O completion notification packets to input/output completion ports, where they are queued up. The CreateIoCompletionPort function provides a mechanism for this.

When you perform an input/output operation with a file handle that has an associated input/output completion port, the I/O system sends a completion notification packet to the completion port when the I/O operation completes. The I/O completion port places the completion packet in a first-in-first-out queue. The GetQueuedCompletionStatus function retrieves these queued I/O completion packets.

A server application may have several threads calling GetQueuedCompletionStatus for the same completion port. As input operations complete, the operating system queues completion packets to the completion port. If threads are actively waiting in a call to this function, queued requests complete their call.

You can call the PostQueuedCompletionStatus function to post an I/O completion packet to an I/O completion port. The I/O completion packet will satisfy an outstanding call to the GetQueuedCompletionStatus function.

QuickInfo

  Windows NT: Requires version 3.5 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

File I/O Overview, File Functions, ConnectNamedPipe, CreateIoCompletionPort, DeviceIoControl, LockFileEx, OVERLAPPED, ReadFile, PostQueuedCompletionStatus, TransactNamedPipe, WaitCommEvent, WriteFile