GetQueuedCompletionStatus Subroutine

Purpose

Dequeues a completion packet from a specified I/O completion port.

Syntax

#include <iocp.h>
boolean_t GetQueuedCompletionStatus (CompletionPort, TransferCount, CompletionKey, Overlapped, Timeout)
HANDLE CompletionPort;
LPDWORD TransferCount, CompletionKey;
LPOVERLAPPED Overlapped; DWORD Timeout;

Description

The GetQueuedCompletionStatus subroutine attempts to dequeue a completion packet from the CompletionPort parameter. If there is no completion packet to be dequeued, this subroutine waits a predetermined amount of time as indicated by the Timeout parameter for a completion packet to arrive.

The GetQueuedCompletionStatus subroutine returns a boolean indicating whether or not a completion packet has been dequeued.

The GetQueuedCompletionStatus subroutine is part of the I/O Completion Port (IOCP) kernel extension.

Note: This subroutine only works with file descriptors of sockets, or regular files for use with the Asynchronous I/O (AIO) subsystem. It does not work with file descriptors of other types.

Parameters

Item Description
CompletionPort Specifies the completion port that this subroutine will attempt to access.
TransferCount Specifies the number of bytes transferred. This parameter is set by the subroutine from the value received in the completion packet.
CompletionKey Specifies the completion key associated with the file descriptor used in the transfer request. This parameter is set by the subroutine from the value received in the completion packet.
Overlapped Specifies the overlapped structure used in the transfer request. This parameter is set by the subroutine from the value received in the completion packet. For regular files, this parameter contains a pointer to the AIOCB for a completed AIO request. If an application uses the same completion port for both socket and AIO to regular files, it must use unique CompletionKey values to differentiate between sockets and regular files in order to properly interpret the Overlapped parameter.
Timeout Specifies the amount of time in milliseconds the subroutine is to wait for a completion packet. If this parameter is set to INFINITE, the subroutine will never timeout.

Return Values

Upon successful completion, the GetQueuedCompletionStatus subroutine returns a boolean indicating its success.

If the GetQueuedCompletionStatus subroutine is unsuccessful, the subroutine handler performs the following functions:
  • Returns a value of 0 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable, see the link in the Related Information section of this document.

Error Codes

The subroutine is unsuccessful if any of the following errors occur:
Item Description
ETIMEDOUT No completion packet arrived to be dequeued and the Timeout parameter has elapsed.
EINVAL The value of the CompletionPort or other parameter is not valid.
EAGAIN Resource temporarily unavailable. If a sleep is interrupted by a signal, EAGAIN may be returned.
ENOTCONN Socket is not connected. The ENOTCONN return can happen for two reasons. One is if a request is made, the fd is then closed, then the request is returned back to the process. The error will be ENOTCONN. The other is if the socket drops while the fd is still open, the requests after the socket drops (disconnects) will return ENOTCONN.
EBADF This error code might also be returned when the value of the CompletionPort parameter is not valid.

Examples

The following program fragment illustrates the use of the GetQueuedCompletionStatus subroutine to dequeue a completion packet. 
int transfer_count, completion_key
LPOVERLAPPED overlapped;
c = GetQueuedCompletionStatus (34, &transfer_count, &completion_key, &overlapped, 1000);