WdfWaitLockCreate function (wdfsync.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfWaitLockCreate method creates a framework wait-lock object.

Syntax

NTSTATUS WdfWaitLockCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES LockAttributes,
  [out]          WDFWAITLOCK            *Lock
);

Parameters

[in, optional] LockAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies attributes for the wait-lock object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] Lock

A pointer to a location that receives a handle to a new framework wait-lock object.

Return value

WdfWaitLockCreate returns STATUS_SUCCESS if the operation succeeds.

For a list of other return values that the WdfWaitLockCreate method might return, see Framework Object Creation Errors.

This method also might return other NTSTATUS values.

Remarks

The WdfWaitLockCreate method creates a framework wait-lock object. After creating a wait-lock object, a driver can call WdfWaitLockAcquire to acquire the lock and WdfWaitLockRelease to release the lock.

By default, the new wait-lock object's parent is the framework driver object that the WdfDriverCreate method created. You can use the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure to specify a different parent. The framework deletes the wait-lock object when it deletes the parent object. If your driver does not change the default parent, the driver should delete the wait-lock object when it has finished using the object; otherwise, the object will remain until the I/O manager unloads your driver.

For more information about wait locks, see Synchronization Techniques for Framework-Based Drivers.

Examples

The following code example initializes a WDF_OBJECT_ATTRIBUTES, specifies that the wait lock's parent object will be a device object, and calls WdfWaitLockCreate.

WDF_OBJECT_ATTRIBUTES attributes;
WDFWAITLOCK lockHandle;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = Device;
status = WdfWaitLockCreate(
                           &attributes,
                           &lockHandle
                           );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfsync.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheckLock(kmdf)