Fonction WdfWaitLockAcquire (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 pour un objet de verrouillage d’attente de 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’a pas la valeur NULL, l’infrastructure annule la tentative d’obtention du verrou si elle n’est pas terminée dans le délai d’expiration spécifié. Les valeurs de délai d’expiration peuvent être négatives, positives ou nulles, comme suit :
- Si la valeur du délai d’attente est négative, le délai d’expiration est relatif à l’heure système actuelle.
- Si la valeur du délai d’attente est positive, l’heure d’expiration est spécifiée comme une heure absolue (qui est en fait relative au 1er janvier 1601).
- Si la valeur du 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 des fonctions de conversion de temps qui convertissent des valeurs de temps en unités de temps système.
Si l’appelant fournit un pointeur NULL , la méthode attend indéfiniment jusqu’à ce qu’elle ait acquis le verrou.
Valeur retournée
WdfWaitLockAcquire peut retourner les valeurs NTSTATUS suivantes :
| Code de retour | Description |
|---|---|
|
L’appelant a acquis le verrou d’attente. |
|
L’intervalle de délai spécifié a expiré avant l’acquisition du verrou. |
Notez que NT_SUCCESS(status) est égal à TRUE pour toutes ces valeurs status.
L’appelant n’a pas besoin d’case activée la valeur de retour si le pointeur Timeout a la valeur NULL, car dans ce cas WdfWaitLockAcquire retourne uniquement après avoir acquis le verrou.
Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.
Remarques
La méthode WdfWaitLockAcquire ne retourne pas tant qu’elle n’a pas acquis 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, les API de noyau normaux sont désactivés. WdfWaitLockAcquire ne modifie pas l’IRQL de l’appelant.
Si le pointeur de délai d’expiration a la valeur NULL ou si la valeur du délai d’attente n’est pas égale à zéro, WdfWaitLockAcquire doit être appelé à l’adresse IRQL = PASSIVE_LEVEL.
Si la valeur de délai d’attente est égale à zéro, WdfWaitLockAcquire doit être appelé au 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);
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| Version UMDF minimale | 2.0 |
| En-tête | wdfsync.h (inclure Wdf.h) |
| Bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | Consultez la section Notes. |
| Règles de conformité DDI | DriverCreate(kmdf),KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf) |