#ifndef _NTIOAPI_H
//
// Wait completion packet
//
#if (PHNT_VERSION >= PHNT_WINDOWS_8)

/**
 * Arranges one completion-port notification when a waitable target is satisfied.
 * If the target is already signaled, a packet is queued during association.
 * After the packet is removed, call this function again to establish another wait.
 *
 * \param[in] WaitCompletionPacketHandle Idle wait-packet handle with
 * WAIT_COMPLETION_PACKET_SET_STATE (0x1). An already-associated packet returns
 * STATUS_INVALID_PARAMETER_1 including while queued for removal.
 * \param[in] IoCompletionHandle I/O completion port with IO_COMPLETION_MODIFY_STATE (0x2).
 * \param[in] TargetObjectHandle Supported waitable target with SYNCHRONIZE (0x00100000).
 * Mutants and queue objects are rejected with STATUS_INVALID_PARAMETER_3; an arbitrary handle is not necessarily a supported wait target.
 * \param[in, optional] KeyContext Opaque pointer-sized key to store in the notification.
 * \param[in, optional] ApcContext Opaque pointer-sized context, not a callback address.
 * \param[in] IoStatus Status value to store in the notification, not association status.
 * \param[in] IoStatusInformation Pointer-sized information value to store in the packet.
 * \param[out, optional] AlreadySignaled Receives TRUE if the target object, not the
 * wait-packet object, was already signaled when the association was established.
 * \return NTSTATUS describing association. A TRUE AlreadySignaled does not mean
 * that the packet has already been removed; consume it from the completion port.
 * \remarks Satisfying the wait consumes a synchronization event's signal or one
 * semaphore count; it does not clear a notification event. The association is
 * one-shot, not a persistent subscription. The kernel retains references to the
 * packet, target and port while the association is outstanding. Synchronize reuse
 * with dequeue or completed cancellation, not simply an NT_SUCCESS cancellation status.
 * \sa https://learn.microsoft.com/en-us/windows/win32/devnotes/ntassociatewaitcompletionpacket
 */
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtAssociateWaitCompletionPacket(
    _In_ HANDLE WaitCompletionPacketHandle,
    _In_ HANDLE IoCompletionHandle,
    _In_ HANDLE TargetObjectHandle,
    _In_opt_ PVOID KeyContext,
    _In_opt_ PVOID ApcContext,
    _In_ NTSTATUS IoStatus,
    _In_ ULONG_PTR IoStatusInformation,
    _Out_opt_ PBOOLEAN AlreadySignaled
    );

#endif
#endif
View code on GitHub

#ifndef _NTZWAPI_H

_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwAssociateWaitCompletionPacket(
    _In_ HANDLE WaitCompletionPacketHandle,
    _In_ HANDLE IoCompletionHandle,
    _In_ HANDLE TargetObjectHandle,
    _In_opt_ PVOID KeyContext,
    _In_opt_ PVOID ApcContext,
    _In_ NTSTATUS IoStatus,
    _In_ ULONG_PTR IoStatusInformation,
    _Out_opt_ PBOOLEAN AlreadySignaled
    );

#endif
View code on GitHub

NTSTATUS NtAssociateWaitCompletionPacket (
    _In_ HANDLE WaitCompletionPacketHandle,
    _In_ HANDLE IoCompletionHandle,
    _In_ HANDLE TargetObjectHandle,
    _In_opt_ PVOID KeyContext,
    _In_opt_ PVOID ApcContext,
    _In_ NTSTATUS IoStatus,
    _In_ ULONG_PTR IoStatusInformation,
    _Out_opt_ PBOOLEAN AlreadySignaled
    )
View the official Win32 development documentation

NtDoc

This function is documented in Windows SDK.

Edit description on GitHub

Win32 development documentation (ntassociatewaitcompletionpacket)

NtAssociateWaitCompletionPacket function

Creates a wait completion association for the target object.

Parameters

WaitCompletionPacketHandle [in]

A handle to a wait completion packet which describes the association. This object must not be in use.

IoCompletionHandle [in]

A handle to an IO completion object which will receive a notification when the object becomes signaled.

TargetObjectHandle [in]

A handle to a waitable object for which notifications are to be received.

KeyContext [in]

Supplies the key context that is returned during a call to NtRemoveIoCompletion.

ApcContext [in]

The apc context that is returned during a call to NtRemoveIoCompletion.

IoStatus [in]

The IoStatus->Status data that is returned during a call to NtRemoveIoCompletion.

IoStatusInformation [in]

The IoStatus->Information data that is returned during a call to NtRemoveIoCompletion.

AlreadySignaled [out]

An optional pointer to a boolean variable that receives an indication of whether the target object was already signaled at the time of the association when this function succeeds.

Return value

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

Remarks

When the object is signaled, a packet is queued to the supplied completion port and the supplied values will be conveyed to a caller of NtRemoveIoCompletion. When the packet is picked up, the association must be reestablished by calling this function again. An error is returned if the wait completion packet is already in use for an association.

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