ExAcquireRundownProtectionEx function (wdm.h)

Article
02/22/2024

The ExAcquireRundownProtectionEx routine tries to acquire run-down protection on a shared object so the caller can safely access the object.

Syntax

BOOLEAN ExAcquireRundownProtectionEx(
  [in, out] PEX_RUNDOWN_REF RunRef,
  [in]      ULONG           Count
);

Parameters

[in, out] RunRef

A pointer to an EX_RUNDOWN_REF structure that was initialized by a previous call to the ExInitializeRundownProtection routine. The run-down protection routines use this structure to track the run-down status of the associated shared object. This structure is opaque to drivers.

[in] Count

The amount by which to increment to the run-down instance count of the object. The count is incremented only if the routine returns TRUE. For more information, see Remarks

Return value

ExAcquireRundownProtectionEx returns TRUE if the routine successfully acquires run-down protection for the caller. Otherwise, it returns FALSE. A return value of FALSE indicates that the run down of the object has started and that the object must be treated as invalid.

Remarks

To safely access a shared object, a driver calls ExAcquireRundownProtectionEx to acquire run-down protection on the object.

The RunRef parameter points to an EX_RUNDOWN_REF structure that tracks the run-down status of the associated object. This status information includes a count of instances of run-down protection that are currently in effect on the object. The ExAcquireRundownProtectionEx and ExReleaseRundownProtectionEx routines increment and decrement this count by arbitrary amounts. Two related routines, ExAcquireRundownProtection and ExReleaseRundownProtection, increment and decrement this count by one.

As long as the run-down block itself is nonpaged, this function can be called at DISPATCH_LEVEL.

For more information, see Run-Down Protection.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows Server 2003.
Target Platform	Universal
Header	wdm.h (include Wdm.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (see Remarks)
DDI compliance rules	HwStorPortProhibitedDDIs(storport)