Функция WdfWaitLockAcquire (wdfsync.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfWaitLockAcquire получает указанную блокировку ожидания.

Синтаксис

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

Параметры

[in] Lock

Дескриптор объекта блокировки ожидания платформы, полученный при предыдущем вызове WdfWaitLockCreate.

[in, optional] Timeout

Необязательный указатель на значение времени ожидания. Значение времени ожидания указывается в системных единицах времени (100-наносекундные интервалы).

Если указатель не равен NULL, платформа отменяет попытку получить блокировку, если она не завершена в течение указанного периода времени ожидания. Значения времени ожидания могут быть отрицательными, положительными или нулевыми, как показано ниже.

Если значение времени ожидания отрицательное, время истечения срока действия будет относительно текущего системного времени.
Если значение времени ожидания является положительным, время истечения срока действия указывается как абсолютное время (фактически относительно 1 января 1601 г.).
Если время ожидания равно нулю, WdfWaitLockAcquire пытается получить блокировку, а затем немедленно возвращается, независимо от того, была ли она приобретена блокировка или нет.

На относительные сроки действия не влияют изменения системного времени, которые могут произойти в течение указанного периода времени ожидания. Абсолютное время истечения срока действия отражает изменения системного времени.

Платформа предоставляет функции преобразования времени , которые преобразуют значения времени в системные единицы времени.

Если вызывающий объект предоставляет указатель NULL , метод ожидает неограниченное время, пока не будет получена блокировка.

Возвращаемое значение

WdfWaitLockAcquire может возвращать следующие значения NTSTATUS:

Код возврата	Описание
STATUS_SUCCESS	Вызывающий объект получил блокировку ожидания.
STATUS_TIMEOUT	Указанный интервал времени ожидания истек до получения блокировки.

Обратите внимание, что NT_SUCCESS(status) равно TRUE для всех этих значений состояния.

Вызывающему объекту не нужно проверка возвращаемое значение, если указатель времени ожидания имеет значение NULL, так как в этом случае WdfWaitLockAcquire возвращает только после получения блокировки.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

WdfWaitLockAcquire вызывает KeEnterCriticalRegion перед получением блокировки ожидания. В результате при возврате метода обычные ПТР ядра отключаются. WdfWaitLockAcquire не изменяет IRQL вызывающего абонента.

Если указатель timeout имеет значение NULL или значение времени ожидания не равно нулю, необходимо вызвать WdfWaitLockAcquire по irQL = PASSIVE_LEVEL.

Если время ожидания равно нулю, необходимо вызвать WdfWaitLockAcquire в DISPATCH_LEVEL IRQL < . Обратите внимание, что это не согласуется с файлом заголовка (wdfsync.h), который указывает на то, что этот метод можно вызвать при DISPATCH_LEVEL.

Дополнительные сведения о блокировках ожидания см. в разделе Методы синхронизации для драйверов Framework-Based.

Примеры

В следующем примере кода выполняется получение блокировки ожидания, добавление объекта устройства в коллекцию объектов и освобождение блокировки ожидания.

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfsync.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	См. раздел "Примечания".
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf)

См. также раздел

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease