WdfWaitLockAcquire-Funktion (wdfsync.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfWaitLockAcquire Methode erhält eine angegebene Wartesperre.

Syntax

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

Parameter

[in] Lock

Ein Handle zu einem Framework-Wait-Lock-Objekt, abgerufen durch einen vorherigen Aufruf von WdfWaitLockCreate.

[in, optional] Timeout

Ein optionaler Zeiger auf einen Timeoutwert. Der Timeoutwert wird in Systemzeiteinheiten (100-Nanosekundenintervalle) angegeben.

Wenn der Zeiger nichtNULL-ist, bricht das Framework den Versuch ab, die Sperre abzurufen, wenn er nicht innerhalb des angegebenen Timeoutzeitraums abgeschlossen ist. Timeoutwerte können wie folgt negativ, positiv oder null sein:

Wenn der Timeoutwert negativ ist, ist die Ablaufzeit relativ zur aktuellen Systemzeit.
Wenn der Timeoutwert positiv ist, wird die Ablaufzeit als absolute Zeit angegeben (die tatsächlich relativ zum 1. Januar 1601 ist).
Wenn der Timeoutwert null ist, WdfWaitLockAcquire versucht, die Sperre zu erwerben, und gibt dann sofort zurück, unabhängig davon, ob sie die Sperre erworben hat.

Relative Ablaufzeiten sind nicht von Änderungen an der Systemzeit betroffen, die innerhalb des angegebenen Timeoutzeitraums auftreten können. Absolute Ablaufzeiten spiegeln Systemzeitänderungen wider.

Das Framework bietet Zeitkonvertierungsfunktionen, die Zeitwerte in Systemzeiteinheiten konvertieren.

Wenn der Aufrufer einen NULL- Zeiger bereitstellt, wartet die Methode auf unbestimmte Zeit, bis sie die Sperre abgerufen hat.

Rückgabewert

WdfWaitLockAcquire- können die folgenden NTSTATUS-Wertezurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Anrufer hat die Wartesperre erworben.
STATUS_TIMEOUT	Das angegebene Timeout-Intervall abgelaufen ist, bevor die Sperre abgerufen wurde.

Beachten Sie, dass NT_SUCCESS(Status) TRUE- für alle diese Statuswerte entspricht.

Der Aufrufer muss den Rückgabewert nicht überprüfen, wenn der Timeout Zeiger NULL-ist, da in diesem Fall WdfWaitLockAcquire erst nach dem Abrufen der Sperre zurückgegeben wird.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Die WdfWaitLockAcquire--Methode wird erst zurückgegeben, wenn sie die Wartesperre erhält oder bis der Timeoutzeitraum abläuft.

WdfWaitLockAcquire ruft KeEnterCriticalRegion- auf, bevor die Wartesperre erworben wird. Wenn die Methode zurückgegeben wird, werden normalen Kernel-APCs deaktiviert,. WdfWaitLockAcquire ändert die IRQL des Aufrufers nicht.

Wenn der Timeout Zeiger NULL-ist oder der Timeoutwert nicht null ist, muss WdfWaitLockAcquire- bei IRQL = PASSIVE_LEVEL aufgerufen werden.

Wenn der Timeoutwert null ist, muss WdfWaitLockAcquire- bei IRQL-< DISPATCH_LEVEL aufgerufen werden. Beachten Sie, dass dies in Meinungsverschiedenheiten mit der Headerdatei (wdfsync.h) liegt, die angibt, dass diese Methode bei DISPATCH_LEVEL aufgerufen werden kann.

Weitere Informationen zu Wartesperren finden Sie unter Synchronisierungstechniken für Framework-Based Treiber.

Beispiele

Im folgenden Codebeispiel wird eine Wartesperre erfasst, einer Objektauflistung ein Geräteobjekt hinzugefügt und die Wartesperre freigegeben.

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

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfsync.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	Siehe Abschnitt "Hinweise".
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf)

Siehe auch

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease

Freigeben über