WdfWaitLockAcquire メソッド

The WdfWaitLockAcquire method acquires a specified wait lock.

構文

NTSTATUS WdfWaitLockAcquire(
  [in]            WDFWAITLOCK Lock,
  [in, optional]  PLONGLONG Timeout
);

パラメーター

• Lock [in]
  A handle to a framework wait-lock object, obtained by a previous call to WdfWaitLockCreate.

• Timeout [in, optional]
  An optional pointer to a time-out value. The time-out value is specified in system time units (100-nanosecond intervals). If the pointer is non-NULL, the framework cancels the attempt to obtain the lock if it is not completed within the specified time-out period. Time-out values can be negative, positive, or zero, as follows:

  • If the time-out value is negative, the expiration time is relative to the current system time.

  • If the time-out value is positive, the expiration time is specified as an absolute time (which is actually relative to January 1, 1601).

  • If the time-out value is zero, WdfWaitLockAcquire attempts to acquire the lock and then returns immediately, whether it has acquired the lock or not.

  Relative expiration times are not affected by any changes to the system time that might occur within the specified time-out period. Absolute expiration times do reflect system time changes.

  The framework provides time conversion functions that convert time values into system time units.

戻り値

WdfWaitLockAcquire can return the following NTSTATUS values:

Note that NT_SUCCESS(status) equals TRUE for all of these status values.

The caller does not have to check the return value if the Timeout pointer is NULL, because in that case WdfWaitLockAcquire returns only after it acquires the lock.

A bug check occurs if the driver supplies an invalid object handle.

解説

The WdfWaitLockAcquire method does not return until it acquires the wait lock or until the time-out period expires.

After WdfWaitLockAcquire acquires the wait lock, it calls KeEnterCriticalRegion before returning so that normal kernel APCs are disabled. WdfWaitLockAcquire does not alter the caller's IRQL.

If the Timeout pointer is NULL, or if the time-out value is not zero, WdfWaitLockAcquire must be called at IRQL = PASSIVE_LEVEL.

If the time-out value is zero, WdfWaitLockAcquire can be called at IRQL <= DISPATCH_LEVEL.

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

例

The following code example acquires a wait lock, adds a device object to an object collection, and releases the wait lock.

  WdfWaitLockAcquire(
                   FilterDeviceCollectionLock,
                   NULL
                   );
status = WdfCollectionAdd(
                          FilterDeviceCollection,
                          deviceHandle
                          );
if (!NT_SUCCESS(status)) {
    addFailed = TRUE;
}
WdfWaitLockRelease(FilterDeviceCollectionLock);

要件

参照

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease