Função WdfWaitLockAcquire (wdfsync.h)
[Aplica-se a KMDF e UMDF]
O método WdfWaitLockAcquire adquire um bloqueio de espera especificado.
Sintaxe
NTSTATUS WdfWaitLockAcquire(
[in] WDFWAITLOCK Lock,
[in, optional] PLONGLONG Timeout
);
Parâmetros
[in] Lock
Um identificador para um objeto de bloqueio de espera da estrutura, obtido por uma chamada anterior para WdfWaitLockCreate.
[in, optional] Timeout
Um ponteiro opcional para um valor de tempo limite. O valor de tempo limite é especificado em unidades de tempo do sistema (intervalos de 100 nanossegundos).
Se o ponteiro não for NULL, a estrutura cancelará a tentativa de obter o bloqueio se ele não for concluído dentro do período de tempo limite especificado. Os valores de tempo limite podem ser negativos, positivos ou zero, da seguinte maneira:
- Se o valor de tempo limite for negativo, o tempo de expiração será relativo à hora atual do sistema.
- Se o valor de tempo limite for positivo, o tempo de expiração será especificado como um tempo absoluto (que na verdade é relativo a 1º de janeiro de 1601).
- Se o valor de tempo limite for zero, WdfWaitLockAcquire tentará adquirir o bloqueio e retornará imediatamente, independentemente de ter adquirido o bloqueio ou não.
A estrutura fornece funções de conversão de tempo que convertem valores de tempo em unidades de tempo do sistema.
Se o chamador fornecer um ponteiro NULL , o método aguardará indefinidamente até que ele tenha adquirido o bloqueio.
Retornar valor
WdfWaitLockAcquire pode retornar os seguintes valores NTSTATUS:
| Código de retorno | Descrição |
|---|---|
|
O chamador adquiriu o bloqueio de espera. |
|
O intervalo de tempo limite especificado expirou antes da aquisição do bloqueio. |
Observe que NT_SUCCESS(status) é igual a TRUE para todos esses valores status.
O chamador não precisará marcar o valor retornado se o ponteiro Timeout for NULL, pois nesse caso WdfWaitLockAcquire retornará somente depois de adquirir o bloqueio.
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Comentários
O método WdfWaitLockAcquire não retorna até que adquira o bloqueio de espera ou até que o período de tempo limite expire.
WdfWaitLockAcquire chama KeEnterCriticalRegion antes de adquirir o bloqueio de espera. Como resultado, quando o método retorna, as APCs de kernel normais são desabilitadas. WdfWaitLockAcquire não altera o IRQL do chamador.
Se o ponteiro Timeout for NULL ou se o valor de tempo limite não for zero, WdfWaitLockAcquire deverá ser chamado em IRQL = PASSIVE_LEVEL.
Se o valor de tempo limite for zero, WdfWaitLockAcquire deverá ser chamado em IRQL < DISPATCH_LEVEL. Observe que isso está em desacordo com o arquivo de cabeçalho (wdfsync.h), que indica que esse método pode ser chamado em DISPATCH_LEVEL.
Para obter mais informações sobre bloqueios de espera, consulte Técnicas de sincronização para drivers de Framework-Based.
Exemplos
O exemplo de código a seguir adquire um bloqueio de espera, adiciona um objeto de dispositivo a uma coleção de objetos e libera o bloqueio de espera.
WdfWaitLockAcquire(
FilterDeviceCollectionLock,
NULL
);
status = WdfCollectionAdd(
FilterDeviceCollection,
deviceHandle
);
if (!NT_SUCCESS(status)) {
addFailed = TRUE;
}
WdfWaitLockRelease(FilterDeviceCollectionLock);
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Versão mínima do UMDF | 2,0 |
| Cabeçalho | wdfsync.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | Consulte a seção Observações. |
| Regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf) |