WdfWaitLockAcquire, fonction (wdfsync.h)

[S’applique à KMDF et UMDF]

La méthode WdfWaitLockAcquire acquiert un verrou d’attente spécifié.

Syntaxe

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

Paramètres

[in] Lock

Handle vers un objet de verrouillage d’attente du framework, obtenu par un appel précédent à WdfWaitLockCreate.

[in, optional] Timeout

Pointeur facultatif vers une valeur de délai d’attente. La valeur de délai d’attente est spécifiée dans les unités de temps système (intervalles de 100 nanosecondes).

Si le pointeur n’est pasNULL, l’infrastructure annule la tentative d’obtention du verrou s’il n’est pas terminé dans le délai d’attente spécifié. Les valeurs de délai d’attente peuvent être négatives, positives ou nulles, comme suit :

• Si la valeur de délai d’attente est négative, l’heure d’expiration est relative à l’heure système actuelle.
• Si la valeur du délai d’attente est positive, le temps d’expiration est spécifié comme une heure absolue (qui est réellement relative au 1er janvier 1601).
• Si la valeur de délai d’attente est égale à zéro, WdfWaitLockAcquire tente d’acquérir le verrou, puis retourne immédiatement, qu’il ait acquis le verrou ou non.

L’infrastructure fournit fonctions de conversion de temps qui convertissent les valeurs de temps en unités de temps système.

Si l’appelant fournit une pointeur NULL, la méthode attend indéfiniment jusqu’à ce qu’elle ait acquis le verrou.

Valeur de retour

WdfWaitLockAcquire pouvez retourner les valeurs NTSTATUS suivantes :

Notez que NT_SUCCESS(état) est égal à TRUE pour toutes ces valeurs d’état.

L’appelant n’a pas besoin de vérifier la valeur de retour si le pointeur Timeout est NULL, car dans ce cas WdfWaitLockAcquire retourne uniquement après l’acquisition du verrou.

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfWaitLockAcquire ne retourne pas tant qu’elle n’acquiert pas le verrou d’attente ou jusqu’à l’expiration du délai d’expiration.

WdfWaitLockAcquire appelle KeEnterCriticalRegion avant d’acquérir le verrou d’attente. Par conséquent, lorsque la méthode retourne, API de noyau normales sont désactivées. WdfWaitLockAcquire ne modifie pas le runtime d’intégration de l’appelant.

Si le pointeur timeout est NULL ou si la valeur de délai d’attente n’est pas égale à zéro, WdfWaitLockAcquire doit être appelé à IRQL = PASSIVE_LEVEL.

Si la valeur de délai d’attente est égale à zéro, WdfWaitLockAcquire doit être appelée à l'< DISPATCH_LEVEL IRQL. Notez qu’il s’agit d’un désaccord avec le fichier d’en-tête (wdfsync.h), ce qui indique que cette méthode peut être appelée à DISPATCH_LEVEL.

Pour plus d’informations sur les verrous d’attente, consultez Techniques de synchronisation pour les pilotes Framework-Based.

Exemples

L’exemple de code suivant acquiert un verrou d’attente, ajoute un objet d’appareil à une collection d’objets et libère le verrou d’attente.

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

Exigences

Voir aussi

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease