Función WdfWaitLockAcquire (wdfsync.h)

  • Artículo

[Se aplica a KMDF y UMDF]

El método WdfWaitLockAcquire adquiere un bloqueo de espera especificado.

Sintaxis

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

Parámetros

[in] Lock

Identificador de un objeto wait-lock de marco, obtenido por una llamada anterior a WdfWaitLockCreate.

[in, optional] Timeout

Puntero opcional a un valor de tiempo de espera. El valor de tiempo de espera se especifica en unidades de tiempo del sistema (intervalos de 100 nanosegundos).

Si el puntero no es NULL, el marco cancela el intento de obtener el bloqueo si no se completa dentro del período de tiempo de espera especificado. Los valores de tiempo de espera pueden ser negativos, positivos o cero, como se indica a continuación:

  • Si el valor de tiempo de espera es negativo, la hora de expiración es relativa a la hora actual del sistema.
  • Si el valor de tiempo de espera es positivo, la hora de expiración se especifica como una hora absoluta (que realmente es relativa al 1 de enero de 1601).
  • Si el valor de tiempo de espera es cero, WdfWaitLockAcquire intenta adquirir el bloqueo y, a continuación, devuelve inmediatamente, tanto si ha adquirido el bloqueo como si no.
Los tiempos de expiración relativos no se ven afectados por ningún cambio en la hora del sistema que pueda producirse dentro del período de tiempo de espera especificado. Los tiempos de expiración absolutos reflejan los cambios en la hora del sistema.

El marco proporciona funciones de conversión de tiempo que convierten valores de hora en unidades de tiempo del sistema.

Si el autor de la llamada proporciona un puntero NULL , el método espera indefinidamente hasta que haya adquirido el bloqueo.

Valor devuelto

WdfWaitLockAcquire puede devolver los siguientes valores NTSTATUS:

Código devuelto Descripción
STATUS_SUCCESS
 El autor de la llamada ha adquirido el bloqueo de espera.
STATUS_TIMEOUT
 El intervalo de tiempo de espera especificado expiró antes de que se adquiriera el bloqueo.
 

Tenga en cuenta que NT_SUCCESS(status) es igual a TRUE para todos estos valores de estado.

El autor de la llamada no tiene que comprobar el valor devuelto si el puntero timeout es NULL, porque en ese caso WdfWaitLockAcquire solo devuelve después de adquirir el bloqueo.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

El método WdfWaitLockAcquire no devuelve hasta que adquiere el bloqueo de espera o hasta que expire el período de tiempo de espera.

WdfWaitLockAcquire llama a KeEnterCriticalRegion antes de adquirir el bloqueo de espera. Como resultado, cuando el método devuelve, se deshabilitan las API de kernel normales . WdfWaitLockAcquire no modifica el IRQL del autor de la llamada.

Si el puntero timeout es NULL o si el valor de tiempo de espera no es cero, se debe llamar a WdfWaitLockAcquire en IRQL = PASSIVE_LEVEL.

Si el valor de tiempo de espera es cero, se debe llamar a WdfWaitLockAcquire en irQL < DISPATCH_LEVEL. Tenga en cuenta que esto está en desacuerdo con el archivo de encabezado (wdfsync.h), lo que indica que se puede llamar a este método en DISPATCH_LEVEL.

Para obtener más información sobre los bloqueos de espera, vea Técnicas de sincronización para controladores de Framework-Based.

Ejemplos

En el ejemplo de código siguiente se adquiere un bloqueo de espera, se agrega un objeto de dispositivo a una colección de objetos y se libera el bloqueo de espera.

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

Requisitos

Requisito Value
Plataforma de destino Universal
Versión mínima de KMDF 1.0
Versión mínima de UMDF 2.0
Encabezado wdfsync.h (incluya Wdf.h)
Library Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL vea la sección Comentarios.
Reglas de cumplimiento de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf)

Consulte también

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease