NtWaitForKeyedEvent - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
#ifndef _NTEXAPI_H
#if (PHNT_MODE != PHNT_MODE_KERNEL)

/**
 * The NtWaitForKeyedEvent routine pairs with one matching keyed-event release, blocking until a match or
 * interruption. Use it as the wait half of a user-mode synchronization protocol, not to wait on a persistent
 * signal state; a matching release may arrive before or after this call.
 *
 * \param KeyedEventHandle Handle with KEYEDEVENT_WAIT (0x1), or NULL for the system's
 * default keyed event (ExpCritSecOutOfMemoryEvent).
 * \param KeyValue Opaque pointer-sized matching key, not an object handle (including a
 * registry key handle). An address may be used as the key, but the kernel does not
 * dereference it or inspect the memory contents, unlike the Address parameter of
 * WaitOnAddress.
 * Its low bit must be zero; NULL is a valid zero key, not a wildcard. The matching
 * release must use the same object and key and belong to the same process.
 * \param Alertable Whether a blocking wait can be interrupted by an alert or user APC.
 * \param Timeout Optional timeout in 100-nanosecond units: negative for a relative
 * interval, positive for an absolute deadline, zero for polling, or NULL for no deadline.
 * \return STATUS_SUCCESS only when paired with a matching release; STATUS_TIMEOUT,
 * STATUS_ALERTED or STATUS_USER_APC can end an unmatched blocking wait.
 * On x64, an odd KeyValue returns STATUS_INVALID_PARAMETER_1
 * (despite KeyValue being the second parameter), before handle validation.
 * \remarks Test for STATUS_SUCCESS, not just NT_SUCCESS, to distinguish a match
 * from timeout or interruption. A successful wait consumes one matching release.
 * If the match wins a timeout/APC race, the kernel completes the rendezvous and
 * may return STATUS_SUCCESS instead of the interrupt.
 */
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtWaitForKeyedEvent(
    _In_opt_ HANDLE KeyedEventHandle,
    _In_opt_ PVOID KeyValue,
    _In_ BOOLEAN Alertable,
    _In_opt_ PLARGE_INTEGER Timeout
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwWaitForKeyedEvent(
    _In_opt_ HANDLE KeyedEventHandle,
    _In_opt_ PVOID KeyValue,
    _In_ BOOLEAN Alertable,
    _In_opt_ PLARGE_INTEGER Timeout
    );

#endif

View code on GitHub

NtDoc

No description available.

NTinternals.net (undocumented.ntinternals.net)

Function with similar functionality as NtReleaseKeyedEvent. In my opinion it is not needed and exists only for future vision of KeyedEvent objects or just as a mistake.

KeyedEventHandle

HANDLE for previously opened KeyedEvent object.

Key

Value to wait for, must have lowest bit clear.

Alertable

If set, waiting can be broken by alerting thread.

Timeout

Optionally pointer for timing out value.

Documented by

See also