Functia ZwWaitForSingleObject (ntifs.h) – drivere Windows

• 30.04.2018
• 5 minute de citit

In acest articol

Cei ZwWaitForSingleObject asteapta de rutina pana cand obiectul specificat o o pot atinge de stat. Semnalata De asemenea, poate fi specificat un timeout optional.

Sintaxa

NTSYSAPI NTSTATUS ZwWaitForSingleObject (HANDLE Handle, BOOLEAN Alertable, PLARGE_INTEGER Timeout);

Parametrii

Maner

[in] Un maner pentru obiect.

Alertabil

[in] O valoare booleana care specifica daca asteptarea este alertabila.

Pauza

[in, optional] Un indicator optional catre o valoare de expirare care specifica timpul absolut sau relativ la care urmeaza sa fie finalizata asteptarea. O valoare negativa specifica un interval relativ la ora curenta. Valoarea trebuie exprimata in unitati de 100 nanosecunde. Timpii de expirare absoluta urmaresc orice schimbari din timpul sistemului. Timpii relativi de expirare nu sunt afectati de modificarile de timp ale sistemului.

Valoare returnata

ZwWaitForSingleObject poate returna unul dintre urmatoarele coduri de stare posibile:

Cod de returnare Descriere

STATUS_ACCESS_DENIED

Apelantul nu avea privilegiile necesare pentru evenimentul specificat de parametrul Handle .

STATUS_ALERTED

Asteptarea a fost intrerupta pentru a trimite o alerta la firul curent.

STATUS_INVALID_HANDLE

Parametrul Handle furnizat nu era valid.

STATUS_SUCCESS

Obiectul specificat a satisfacut asteptarea.

STATUS_TIMEOUT

Un timeout a avut loc inainte ca obiectul sa fie setat la o stare semnalizata. Aceasta valoare poate fi returnata atunci cand setul specificat de conditii de asteptare nu poate fi indeplinit imediat si parametrul Timeout este setat la zero.

STATUS_USER_APC

Asteptarea a fost intrerupta pentru a livra un APC utilizator la firul curent.  

Retineti ca macrocomanda NT_SUCCESS recunoaste valorile de stare STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT si STATUS_USER_APC ca valori „de succes”.

ZwWaitForSingleObject asteapta pana cand obiectul specificat atinge starea de Semnalizat. De asemenea, poate fi specificat un timeout optional. ZwWaitForSingleObject examineaza starea curenta a obiectului specificat pentru a determina daca asteptarea poate fi satisfacuta imediat. Daca da, se efectueaza actiuni. In caz contrar, firul curent este pus intr-o stare de asteptare si un nou fir este selectat pentru executare pe procesorul curent.

Daca nu este specificat un parametru Timeout , atunci asteptarea nu va fi satisfacuta pana cand obiectul atinge o stare de Semnalizat. Daca este specificat un parametru Timeout si obiectul nu a atins o stare de Semnalizat atunci cand expira expirarea, atunci asteptarea este satisfacuta automat. Daca este specificata o valoare de expirare explicita de zero, atunci nu va aparea nicio asteptare daca asteptarea nu poate fi satisfacuta imediat. O valoare de expirare zero permite testarea unui set de conditii de asteptare si pentru performanta conditionata a oricaror efecte secundare daca asteptarea poate fi satisfacuta imediat, ca si in cazul achizitionarii unui mutex. Asteptarea poate fi, de asemenea, specificata ca alertabila.

De Alertable precizeaza parametru daca firul poate fi alertat si , prin urmare , starea de asteptare abandonata. Daca valoarea acestui parametru este FALS, atunci firul nu poate fi alertat. Singura exceptie de la aceasta regula este cea a unui fir de terminare. In anumite circumstante, un fir de terminare poate fi alertat in timp ce este in curs de lichidare. Un fir este alertat automat, de exemplu, cand este terminat de un utilizator cu CTRL + C.

Daca valoarea Alertable este TRUE si exista una dintre urmatoarele conditii, firul va fi alertat:

1. Daca originea alertei este o rutina interna, nedocumentata in modul kernel, utilizata pentru a alerta firele.
2. Originea alertei este un APC in modul utilizator.

In primul dintre aceste doua cazuri, asteptarea firului este satisfacuta cu o stare de finalizare STATUS_ALERTED. In cel de-al doilea caz, este multumit de starea de finalizare STATUS_USER_APC.

Firul trebuie sa poata fi alertat pentru ca un APC in modul utilizator sa fie livrat. Nu este cazul APC-urilor in mod kernel. Un APC in modul kernel poate fi livrat si executat chiar daca firul nu este alertat. Odata ce executarea APC se incheie, asteptarea firului se reia. Un fir nu este niciodata alertat si nici nu este intrerupta asteptarea, prin livrarea unui APC in modul kernel.

Livrarea APC-urilor in modul kernel catre un fir de asteptare nu depinde daca firul poate fi alertat. Daca APC in modul kernel este un APC special in modul kernel, atunci APC este livrat cu conditia ca IRQL sa fie mai mic decat APC_LEVEL. Daca APC in modul kernel este un APC normal in modul kernel, atunci APC este livrat cu conditia sa se mentina urmatoarele trei conditii: (1) IRQL este mai mic decat APC_LEVEL, (2) niciun APC de kernel nu este in desfasurare si (3) ) firul nu se afla intr-o sectiune critica.

Daca manerul trecut catre ZwWaitForSingleObject se refera la un mutex, livrarea APC este aceeasi ca si pentru toate celelalte obiecte dispecerate in timpul asteptarii. Cu toate acestea, odata ce ZwWaitForSingleObject revine cu STATUS_SUCCESS si firul detine de fapt mutex-ul, sunt livrate numai APC-uri speciale in modul kernel. Livrarea tuturor celorlalte APC-uri, atat in ​​modul kernel, cat si in modul utilizator, este dezactivata. Aceasta restrictie privind livrarea APC persista pana la eliberarea mutex-ului.

Este deosebit de important sa verificati valoarea returnata a ZwWaitForSingleObject atunci cand parametrul Alertable este TRUE , deoarece ZwWaitForSingleObject s-ar putea reveni mai devreme cu o stare STATUS_USER_APC sau STATUS_ALERTED.

Toate asteptarile pe termen lung pot fi intrerupte de un utilizator daca parametrul Alertable este setat la FALS .

Pentru informatii suplimentare, consultati Subiectele in asteptare primesc alerte si APC-uri?

Apelantii ZwWaitForSingleObject trebuie sa ruleze la IRQL mai putin sau egal cu DISPATCH_LEVEL. De obicei, apelantul trebuie sa ruleze la IRQL PASSIVE_LEVEL si intr-un context de fir nonarbitrar. Un apel in timpul rularii la IRQL DISPATCH_LEVEL este valid daca si numai daca apelantul specifica un parametru Timeout de zero. Adica, un driver nu trebuie sa astepte un interval diferit de zero la IRQL egal cu DISPATCH_LEVEL.

Intervalele de time-out sunt masurate in raport cu ceasul sistemului, iar acuratetea masurarii time-out-ului este limitata de granularitatea ceasului sistemului. Pentru mai multe informatii, consultati Precizia temporizatorului.

Nota   Daca apelul catre functia ZwWaitForSingleObject apare in modul utilizator, ar trebui sa utilizati numele „ NtWaitForSingleObject ” in loc de „ ZwWaitForSingleObject ”.

Pentru apelurile de la driverele in modul kernel, versiunile Nt Xxx si Zw Xxx ale unei rutine Windows Native System Services se pot comporta diferit in modul in care gestioneaza si interpreteaza parametrii de intrare. Pentru mai multe informatii despre relatia dintre versiunile Nt Xxx si Zw Xxx ale unei rutine, consultati Utilizarea versiunilor Nt si Zw ale rutinelor Native System Services.

Cerinte

    Client minim acceptat Disponibil incepand cu Windows XP. Target Platform Universal Header ntifs.h (include Ntifs.h, FltKernel.h) Biblioteca NtosKrnl.lib DLL NtosKrnl.exe IRQL PASSIVE_LEVEL Regulile de conformitate DDI HwStorPortProhibitedDDIs, SpNoWait

Vezi si

IoCreateNotificationEvent

IoCreateSynchronizationEvent

KeClearEvent

KeResetEvent

KeSetEvent

KeWaitForSingleObject

Utilizarea versiunilor Nt si Zw ale rutinelor Native System Services

ZwClose

ZwCreateEvent

ZwSetEvent