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
Points to a
variable that the function sets to the number of bytes transferred during an
I/O operation that has completed.
lpCompletionKey
Points 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
Points 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
LockFileExADH1LQ
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
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, the error returned is
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.
See Also