WdfWaitLockAcquire-Funktion (wdfsync.h)

Artikel
02/29/2024

[Gilt für KMDF und UMDF]

Die WdfWaitLockAcquire-Methode ruft eine angegebene Wartesperre ab.

Syntax

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

Parameter

[in] Lock

Ein Handle für ein Framework-Wait-Lock-Objekt, das durch einen vorherigen Aufruf von WdfWaitLockCreate abgerufen wurde.

[in, optional] Timeout

Ein optionaler Zeiger auf einen Timeoutwert. Der Timeoutwert wird in Systemzeiteinheiten (Intervalle von 100 Nanosekunden) angegeben.

Wenn der Zeiger ungleich NULL ist, bricht das Framework den Versuch ab, die Sperre zu erhalten, wenn er nicht innerhalb des angegebenen Timeoutzeitraums abgeschlossen wird. 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, versucht WdfWaitLockAcquire , die Sperre zu erhalten, und gibt dann sofort zurück, unabhängig davon, ob die Sperre abgerufen wurde oder nicht.

Relative Ablaufzeiten werden nicht durch Änderungen an der Systemzeit beeinflusst, die innerhalb des angegebenen Timeoutzeitraums auftreten können. Absolute Ablaufzeiten spiegeln Änderungen der Systemzeit wider.

Das Framework stellt Zeitkonvertierungsfunktionen bereit, die Zeitwerte in Systemzeiteinheiten konvertieren.

Wenn der Aufrufer einen NULL-Zeiger bereitstellt, wartet die Methode unbegrenzt, bis sie die Sperre erhalten hat.

Rückgabewert

WdfWaitLockAcquire kann die folgenden NTSTATUS-Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Aufrufer hat die Wartesperre erworben.
STATUS_TIMEOUT	Das angegebene Timeoutintervall ist abgelaufen, bevor die Sperre abgerufen wurde.

Beachten Sie, dass NT_SUCCESS(status) für alle diese status Werte gleich TRUE ist.

Der Aufrufer muss den Rückgabewert nicht überprüfen, wenn der TimeoutzeigerNULL ist, da in diesem Fall WdfWaitLockAcquire erst nach dem Abrufen der Sperre zurückgibt.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

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

WdfWaitLockAcquire ruft KeEnterCriticalRegion auf, bevor die Wartesperre abgerufen wird. Daher werden normale Kernel-APCs deaktiviert, wenn die Methode zurückgibt. WdfWaitLockAcquire ändert die IRQL des Aufrufers nicht.

Wenn der TimeoutzeigerNULL ist oder der Timeoutwert nicht null ist, muss WdfWaitLockAcquire unter IRQL = PASSIVE_LEVEL aufgerufen werden.

Wenn der Timeoutwert null ist, muss WdfWaitLockAcquire unter IRQL < DISPATCH_LEVEL aufgerufen werden. Beachten Sie, dass dies nicht mit der Headerdatei (wdfsync.h) übereinstimmt, was 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 abgerufen, einer Objektsammlung 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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfsync.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf)

Weitere Informationen

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease

Freigeben über