Funzione WdfWaitLockAcquire (wdfsync.h)
[Si applica a KMDF e UMDF]
Il metodo WdfWaitLockAcquire acquisisce un blocco di attesa specificato.
Sintassi
NTSTATUS WdfWaitLockAcquire(
[in] WDFWAITLOCK Lock,
[in, optional] PLONGLONG Timeout
);
Parametri
[in] Lock
Handle per un oggetto wait-lock del framework, ottenuto da una chiamata precedente a WdfWaitLockCreate.
[in, optional] Timeout
Puntatore facoltativo a un valore di timeout. Il valore di timeout viene specificato nelle unità di tempo di sistema (intervalli di 100 nanosecondi).
Se il puntatore è diverso da NULL, il framework annulla il tentativo di ottenere il blocco se non viene completato entro il periodo di timeout specificato. I valori di timeout possono essere negativi, positivi o zero, come indicato di seguito:
- Se il valore di timeout è negativo, la scadenza è relativa all'ora di sistema corrente.
- Se il valore di timeout è positivo, l'ora di scadenza viene specificata come ora assoluta (che è effettivamente relativa all'1 gennaio 1601).
- Se il valore di timeout è zero, WdfWaitLockAcquire tenta di acquisire il blocco e quindi restituisce immediatamente, indipendentemente dal fatto che abbia acquisito o meno il blocco.
Il framework fornisce funzioni di conversione dell'ora che converte i valori temporali in unità di tempo di sistema.
Se il chiamante fornisce un puntatore NULL , il metodo attende per un periodo illimitato fino a quando non ha acquisito il blocco.
Valore restituito
WdfWaitLockAcquire può restituire i valori NTSTATUS seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Il chiamante ha acquisito il blocco di attesa. |
|
Intervallo di timeout specificato scaduto prima dell'acquisizione del blocco. |
Si noti che NT_SUCCESS(status) è uguale a TRUE per tutti questi valori di stato.
Il chiamante non deve controllare il valore restituito se il puntatore timeout è NULL, perché in questo caso WdfWaitLockAcquire restituisce solo dopo che ha acquisito il blocco.
Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.
Commenti
Il metodo WdfWaitLockAcquire non restituisce finché non acquisisce il blocco di attesa o fino alla scadenza del periodo di timeout.
WdfWaitLockAcquire chiama KeEnterCriticalRegion prima di acquisire il blocco di attesa. Di conseguenza, quando il metodo viene restituito, le NORMALI API del kernel sono disabilitate. WdfWaitLockAcquire non modifica l'IRQL del chiamante.
Se il puntatore timeout è NULL o se il valore di timeout non è zero, WdfWaitLockAcquire deve essere chiamato in IRQL = PASSIVE_LEVEL.
Se il valore di timeout è zero, WdfWaitLockAcquire deve essere chiamato in IRQL < DISPATCH_LEVEL. Si noti che questo è in disaccordo con il file di intestazione (wdfsync.h), che indica che questo metodo può essere chiamato in DISPATCH_LEVEL.
Per altre informazioni sui blocchi di attesa, vedere Tecniche di sincronizzazione per i driver Framework-Based.
Esempio
L'esempio di codice seguente acquisisce un blocco di attesa, aggiunge un oggetto dispositivo a una raccolta di oggetti e rilascia il blocco di attesa.
WdfWaitLockAcquire(
FilterDeviceCollectionLock,
NULL
);
status = WdfCollectionAdd(
FilterDeviceCollection,
deviceHandle
);
if (!NT_SUCCESS(status)) {
addFailed = TRUE;
}
WdfWaitLockRelease(FilterDeviceCollectionLock);
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| Versione UMDF minima | 2,0 |
| Intestazione | wdfsync.h (include Wdf.h) |
| Libreria | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | Vedere la sezione Osservazioni. |
| Regole di conformità DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf) |