Funzione ZwDeviceIoControlFile (ntifs.h)

Articolo
07/11/2023

La routine ZwDeviceIoControlFile invia un codice di controllo direttamente a un driver di dispositivo specificato, causando l'esecuzione dell'operazione specificata da parte del driver corrispondente.

Sintassi

NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            IoControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

Parametri

[in] FileHandle

Handle restituito da ZwCreateFile o ZwOpenFile per l'oggetto file che rappresenta il dispositivo a cui devono essere fornite le informazioni sul controllo o da cui devono essere restituite le informazioni. L'oggetto file deve essere stato aperto per l'I/O asincrono se il chiamante specifica un oggetto Event, ApcRoutine e un contesto APC (in ApcContext) o un contesto di completamento (in ApcContext). Per l'I/O in un dispositivo di archiviazione di massa sottostante, l'oggetto file deve essere stato aperto per l'accesso diretto al dispositivo di archiviazione (DASD).

[in, optional] Event

Handle per un evento creato dal chiamante. Se questo parametro viene specificato, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione richiesta e l'evento specificato viene impostato sullo stato Segnalato. Questo parametro è facoltativo e può essere NULL. Deve essere NULL se il chiamante attenderà che FileHandle venga impostato sullo stato Segnalato.

[in, optional] ApcRoutine

Indirizzo di una routine APC fornita dal chiamante facoltativo da chiamare al termine dell'operazione richiesta. Questo parametro può essere NULL. Deve essere NULL se è presente un oggetto di completamento I/O associato all'oggetto file.

[in, optional] ApcContext

Puntatore a un'area di contesto determinata dal chiamante. Questo valore di parametro viene utilizzato come contesto APC se il chiamante fornisce un APC o viene utilizzato come contesto di completamento se un oggetto di completamento di I/O è stato associato all'oggetto file. Al termine dell'operazione, il contesto APC viene passato all'APC, se ne è stato specificato uno o il contesto di completamento viene incluso come parte del messaggio di completamento che il gestore di I/O invia all'oggetto di completamento I/O associato.

Questo parametro è facoltativo e può essere NULL. Deve essere NULL se ApcRoutine è NULL e non è presente alcun oggetto di completamento I/O associato all'oggetto file.

[out] IoStatusBlock

Puntatore a una variabile che riceve lo stato di completamento finale e informazioni sull'operazione. Per le chiamate riuscite che restituiscono dati, il numero di byte scritti in OutputBuffer viene restituito nel membro Information .

[in] IoControlCode

IOCTL_ codiceXXX che indica l'operazione di controllo di I/O del dispositivo da eseguire, in genere dal driver di dispositivo sottostante. Il valore di questo parametro determina il formato e la lunghezza richiesta di InputBuffer e OutputBuffer, nonché quali delle coppie di parametri seguenti sono necessarie. Per informazioni dettagliate sui codici IOCTL_XXX specifici del sistema definiti dal sistema, vedere la sezione specifica della tecnologia del dispositivo della documentazione di Microsoft Windows Driver Kit (WDK) e Codici di controllo di input e output del dispositivo nella documentazione di Microsoft Windows SDK.

[in, optional] InputBuffer

Puntatore a un buffer di input allocato dal chiamante che contiene informazioni specifiche del dispositivo da assegnare al dispositivo di destinazione. Se IoControlCode specifica un'operazione che non richiede dati di input, questo puntatore può essere NULL.

[in] InputBufferLength

Dimensioni, in byte, del buffer in InputBuffer. Se InputBuffer è NULL, impostare InputBufferLength su zero.

[out, optional] OutputBuffer

Puntatore a un buffer di output allocato dal chiamante in cui le informazioni vengono restituite dal dispositivo di destinazione. Se IoControlCode specifica un'operazione che non produce dati di output, questo puntatore può essere NULL.

[in] OutputBufferLength

Dimensioni, in byte, del buffer in OutputBuffer. Se OutputBuffer è NULL, impostare OutputBufferLength su zero.

Valore restituito

ZwDeviceIoControlFile restituisce STATUS_SUCCESS se i driver sottostanti hanno eseguito correttamente l'operazione richiesta. In caso contrario, il valore restituito può essere un codice di stato di errore propagato da un driver sottostante. I codici di stato di errore possibili includono quanto segue:

Commenti

ZwDeviceIoControlFile offre una visualizzazione coerente dei dati di input e output per il sistema e per i driver in modalità kernel, fornendo applicazioni e driver sottostanti con un metodo dipendente dal dispositivo per specificare un'interfaccia di comunicazione.

Per altre informazioni sui codici IOCTL_XXX definiti dal sistema e sulla definizione di valori IOCTL_XXX o FSCTL_XXX specifici del driver, vedere Uso dei codici di controllo di I/O nella Guida all'architettura della modalità kernel e codici di controllo di input del dispositivo e output nella documentazione di Microsoft Windows SDK.

Se il chiamante ha aperto il file per l'I/O asincrono (con nessuno dei due set di opzioni create/open FILE_SYNCHRONOUS_XXX ), l'evento specificato, se presente, verrà impostato sullo stato segnalato al termine dell'operazione di controllo del dispositivo. In caso contrario, l'oggetto file specificato da FileHandle verrà impostato sullo stato segnalato. Se è stato specificato un oggetto ApcRoutine , viene chiamato con i puntatori ApcContext e IoStatusBlock .

I minifiltri devono usare FltDeviceIoControlFile anziché ZwDeviceIoControlFile.

I chiamanti di ZwDeviceIoControlFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.

Nota Se la chiamata alla funzione ZwDeviceIoControlFile si verifica in modalità utente, è necessario usare il nome "NtDeviceIoControlFile" anziché "ZwDeviceIoControlFile".

Per le chiamate da driver in modalità kernel, le versioni **Nt*Xxx** e **Zw*Xxx** di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per ulteriori informazioni sulla relazione tra le versioni **Nt*Xxx** e **Zw*Xxx** di una routine, vedere [Using Nt and Zw Versions of the Native System Services Routines](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000.
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h, Ntddk.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)