Functia ZwDeviceIoControlFile (ntifs.h) – drivere Windows

• 30.04.2018
• 4 minute de citit

In acest articol

ZwDeviceIoControlFile Rutina trimite un cod de control direct la un driver de dispozitiv specificat, provocand driverul corespunzator pentru a efectua operatia specificata.

Sintaxa

NTSYSAPI NTSTATUS ZwDeviceIoControlFile (HANDLE FileHandle, HANDLE Event, PIO_APC_ROUTINE ApcRoutine, PVOID ApcContext, PIO_STATUS_BLOCK IoStatusBlock, ULONG IoControlCode, PVOID InputBuffer, OutputBuffer ULONG, InputBuffer ULONG, InputBuffer ULONG

Parametrii

FileHandle

[in] Handle returnat de ZwCreateFile sau ZwOpenFile pentru obiectul fisier care reprezinta dispozitivul caruia ar trebui sa i se furnizeze informatiile de control sau de la care ar trebui returnate informatiile. Obiectul fisier trebuie sa fi fost deschis pentru I / O asincron daca apelantul specifica un eveniment , ApcRoutine si un context APC (in ApcContext ) sau un context de finalizare (in ApcContext ). Pentru I / O catre un dispozitiv de stocare in masa, obiectul fisier trebuie sa fi fost deschis pentru accesul direct la dispozitivul de stocare (DASD).

Eveniment

[in, optional] Maner pentru un eveniment creat de apelant. Daca acest parametru este furnizat, apelantul va fi pus intr-o stare de asteptare pana cand operatiunea solicitata este finalizata si evenimentul dat este setat la starea semnalata. Acest parametru este optional si poate fi NUL . Trebuie sa fie NULL daca apelantul va astepta ca FileHandle sa fie setat la starea Semnalizat.

ApcRoutine

[in, optional] Adresa unei rutine APC optionale, furnizate de apelant, care va fi apelata la finalizarea operatiei solicitate. Acest parametru poate fi NULL . Trebuie sa fie NULL daca exista un obiect de completare I / O asociat cu obiectul fisier.

ApcContext

[in, optional] Pointer catre o zona contextuala determinata de apelant. Aceasta valoare a parametrului este utilizata ca context APC daca apelantul furnizeaza un APC sau este utilizata ca context de finalizare daca un obiect de completare I / O a fost asociat cu obiectul fisier. Cand operatiunea se incheie, fie contextul APC este trecut catre APC, daca a fost specificat unul, fie contextul de finalizare este inclus ca parte a mesajului de finalizare pe care Managerul I / O il posteaza la obiectul de completare I / O asociat.

Acest parametru este optional si poate fi NUL . Trebuie sa fie NULL daca ApcRoutine este NULL si nu exista niciun obiect de completare I / O asociat cu obiectul fisier.

IoStatusBlock

[out] Pointer catre o variabila care primeste starea finala finala si informatii despre operatie. Pentru apelurile de succes care returneaza date, numarul de octeti scris in OutputBuffer este returnat in membrul Informatii .

IoControlCode

[in] cod IOCTL_ XXX care indica operatia de control I / O a dispozitivului care urmeaza sa fie efectuata, de obicei de catre driverul dispozitivului de baza. Valoarea acestui parametru determina formatul si lungimea necesara pentru InputBuffer si OutputBuffer , precum si care dintre urmatoarele perechi de parametri sunt necesare. Pentru informatii detaliate despre codurile IOCTL_ XXX specifice dispozitivului definite de sistem , consultati sectiunea specifica tehnologiei dispozitivului din documentatia Microsoft Windows Driver Kit (WDK) si Codurile de control pentru intrarea si iesirea dispozitivului din documentatia Microsoft Windows SDK.

InputBuffer

[in, optional] Pointer catre un buffer de intrare alocat apelantului care contine informatii specifice dispozitivului care trebuie furnizate dispozitivului tinta. Daca IoControlCode specifica o operatie care nu necesita date de intrare, acest indicator poate fi NULL .

InputBufferLength

[in] Dimensiunea, in octeti, a bufferului la InputBuffer . Daca InputBuffer este NULL , setati InputBufferLength la zero.

OutputBuffer

[out, optional] Pointer catre un buffer de iesire alocat apelantului in care informatiile sunt returnate de pe dispozitivul tinta. Daca IoControlCode specifica o operatiune care nu produce date de iesire, acest indicator poate fi NULL .

OutputBufferLength

[in] Dimensiunea, in octeti, a bufferului la OutputBuffer . Daca OutputBuffer este NULL , setati OutputBufferLength la zero.

Valoare returnata

ZwDeviceIoControlFile returneaza STATUS_SUCCESS daca driverul (driverele) de baza a efectuat cu succes operatia solicitata. In caz contrar, valoarea returnata poate fi un cod de stare de eroare propagat de la un driver de baza. Codurile posibile de stare de eroare includ urmatoarele:

ZwDeviceIoControlFile ofera o vizualizare consistenta a datelor de intrare si iesire catre sistem si catre driverele in modul kernel, oferind in acelasi timp aplicatiilor si driverelor subiacente o metoda dependenta de dispozitiv de specificare a unei interfete de comunicatii.

Pentru mai multe informatii despre codurile IOCTL_ XXX definite de sistem si despre definirea valorilor IOCTL_ XXX sau FSCTL_ XXX specifice driverului , consultati Utilizarea codurilor de control I / O din Ghidul de arhitectura al modului kernel si Codurile de control pentru intrarea si iesirea dispozitivului in documentatia Microsoft Windows SDK .

Daca apelantul a deschis fisierul pentru I / O asincrona (fara setul de optiuni de creare / deschidere FILE_SYNCHRONOUS_ XXX ), evenimentul specificat, daca exista, va fi setat la starea semnalizata la finalizarea operatiei de control al dispozitivului. In caz contrar, obiectul fisier specificat de FileHandle va fi setat la starea semnalizata. In cazul in care un ApcRoutine a fost specificat, este numit cu ApcContext si IoStatusBlock pointer.

Minifiltrele ar trebui sa utilizeze FltDeviceIoControlFile in loc de ZwDeviceIoControlFile .

Apelantii ZwDeviceIoControlFile trebuie sa ruleze la IRQL = PASSIVE_LEVEL si cu APC-uri speciale de nucleu activate.

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

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 2000. Platforma tinta Header universal ntifs.h (include Ntifs.h, Ntddk.h) Biblioteca NtosKrnl.lib DLL NtosKrnl.exe IRQL PASSIVE_LEVEL (a se vedea sectiunea Observatii) Regulile de conformitate DDI PowerIrpDDis, HwStorPortProhibitedDDIs

Vezi si

FltDeviceIoControlFile

IoBuildAsynchronousFsdRequest

IoBuildDeviceIoControlRequest

IoBuildSynchronousFsdRequest

IoCallDriver

Utilizarea codurilor de control I / O

Utilizarea versiunilor Nt si Zw ale rutinelor Native System Services

ZwClose

ZwCreateFile

ZwOpenFile