#ifndef _NTIOAPI_H

/**
 * Removes one packet from an I/O completion port, waiting nonalertably if necessary.
 * Dequeue status and the packet's own I/O status are separate results.
 *
 * \param[in] IoCompletionHandle Handle with IO_COMPLETION_MODIFY_STATE (0x2),
 * not merely SYNCHRONIZE or IO_COMPLETION_QUERY_STATE.
 * \param[out] KeyContext Required writable pointer-sized output for the packet key.
 * \param[out] ApcContext Required writable pointer-sized output for its opaque context.
 * \param[out] IoStatusBlock Required writable output containing the packet's status
 * and pointer-sized Information. A failing packet status does not make dequeue fail.
 * \param[in, optional] Timeout In 100-nanosecond units: negative relative interval,
 * nonnegative absolute deadline, zero to poll, or NULL for no deadline.
 * \return STATUS_SUCCESS when a packet was removed; STATUS_TIMEOUT means none was
 * obtained. STATUS_ABANDONED can report queue rundown. Do not use NT_SUCCESS alone
 * to decide that outputs describe a packet.
 * \remarks On the native x64 and WoW64 paths, timeout preserves
 * KeyContext, ApcContext and IoStatusBlock. Use outputs only on STATUS_SUCCESS.
 * Context values are data, not kernel pointers to free or callback routines to invoke.
 * \sa https://learn.microsoft.com/en-us/windows/win32/devnotes/ntremoveiocompletion
 */
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtRemoveIoCompletion(
    _In_ HANDLE IoCompletionHandle,
    _Out_ PVOID *KeyContext,
    _Out_ PVOID *ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_opt_ PLARGE_INTEGER Timeout
    );

#endif
View code on GitHub

#ifndef _NTZWAPI_H

_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwRemoveIoCompletion(
    _In_ HANDLE IoCompletionHandle,
    _Out_ PVOID *KeyContext,
    _Out_ PVOID *ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_opt_ PLARGE_INTEGER Timeout
    );

#endif
View code on GitHub

NTSTATUS NtRemoveIoCompletion (
    __in HANDLE IoCompletionHandle,
    __out PVOID *KeyContext,
    __out PVOID *ApcContext,
    __out PIO_STATUS_BLOCK IoStatusBlock,
    __in_opt PLARGE_INTEGER Timeout
    )
View the official Win32 development documentation

NtDoc

No description available.

Edit description on GitHub

Win32 development documentation (ntremoveiocompletion)

NtRemoveIoCompletion function

Removes an entry from an I/O completion object. If there are currently no entries available, then the calling thread waits for an entry.

Parameters

IoCompletionHandle [in]

A handle to an I/O completion object.

KeyContext [out]

A pointer to a variable that receives the key context that was specified when the I/O completion object was associated with a file object.

ApcContext [out]

A pointer to a variable that receives the context that was specified when the I/O operation was issued.

IoStatusBlock [out]

A pointer to a variable that receives the I/O completion status.

Timeout [in, optional]

A pointer to an optional time out value.

Return value

An NTSTATUS code. For more information, see Using NTSTATUS values.

Remarks

IO_STATUS_BLOCK has the following definition.

typedef struct _IO_STATUS_BLOCK {
    union {
        NTSTATUS Status;
        PVOID Pointer;
    } DUMMYUNIONNAME;

    ULONG_PTR Information;
} IO_STATUS_BLOCK, *PIO_STATUS_BLOCK;

This function has no associated import library or header file; you must call it using the LoadLibrary and GetProcAddress functions. The API is exported from ntdll.dll.

Requirements

Requirement	Value
DLL	ntdll.dll

View the official Win32 development documentation

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows SDK.

Function NtRemoveIoCompletion is one of waiting calls and it's finished when at least one completion record will be available in specified Io Completion object. Records are added when I/O operation is finished, but previously File object have to been associated with Io Completion object.
Association between File and Io Completion objects is added by call to NtSetInformationFile
with FileCompletionInformation information class. Additionally every association have to have unique Key defined. This functionality allows to use one Io Completion object with different File objects.
Every one File object can have only one Io Completion associated with it.

I/O operations won't be appended to Io Completion object except file operations will be called with non-zero value in ApcContext parameters.

IoCompletionHandle

HANDLE to previously created or opened Io Completion object.

CompletionKey

Receives completion Key informing about File object who finishes I/O.

CompletionValue

Value of ApcContext file operation parameter. CompletionValue informs about operation finished.

IoStatusBlock

Io status of finished operation.

Timeout

Optionally pointer to time out value.

Documented by

Tomasz Nowak

NtRemoveIoCompletion - NtDoc