GetQueuedCompletionStatus

The GetQueuedCompletionStatus function attempts to dequeue an I/O completion packet from a specified I/O completion port. If there is no completion packet queued, the function waits for a pending I/O operation associated with the completion port to complete.

BOOL GetQueuedCompletionStatus(
  HANDLE CompletionPort,       // handle to completion port
  LPDWORD lpNumberOfBytes,     // bytes transferred
  PULONG_PTR lpCompletionKey,  // file completion key
  LPOVERLAPPED *lpOverlapped,  // buffer
  DWORD dwMilliseconds         // optional timeout value
);

Parameters

CompletionPort

[in] Handle to the completion port of interest. To create a completion port, use the CreateIoCompletionPort function.

lpNumberOfBytes

[out] Pointer to a variable that receives the number of bytes transferred during an I/O operation that has completed.

lpCompletionKey

[out] Pointer to a variable that receives 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

[out] Pointer to a variable that receives the address of the OVERLAPPED structure that was specified when the completed I/O operation was started.

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

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

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

[in] Specifies the number of milliseconds that the caller is willing to wait for an completion packet to appear at the 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

This function associates a thread with the specified completion port. A thread can be associated with at most one completion port.

The I/O system can be instructed to send completion notification packets to completion ports, where they are queued. 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 completion port places the completion packet in a first-in-first-out queue. The GetQueuedCompletionStatus function retrieves these queued 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. For more information, see I/O Completion Ports.

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

Requirements

  Windows NT/2000: Requires Windows NT 3.5 or later.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

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