Funzione IoBuildDeviceIoControlRequest (wdm.h)
La routine IoBuildDeviceIoControlRequest alloca e configura un'istanza di IRP per una richiesta di controllo del dispositivo sincronamente elaborata.
Sintassi
__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
[in] ULONG IoControlCode,
[in] PDEVICE_OBJECT DeviceObject,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength,
[in] BOOLEAN InternalDeviceIoControl,
[in, optional] PKEVENT Event,
[out] PIO_STATUS_BLOCK IoStatusBlock
);
Parametri
[in] IoControlCode
Fornisce il codice di controllo I/O (IOCTL) da usare nella richiesta. Per informazioni sui codici di controllo I/O specifici dei tipi di dispositivo, vedere sezioni specifiche del tipo di dispositivo nel Kit driver di Windows (WDK).
[in] DeviceObject
Fornisce un puntatore alla struttura DEVICE_OBJECT per l'oggetto dispositivo del driver inferiore successivo, che rappresenta il dispositivo di destinazione.
[in, optional] InputBuffer
Fornisce un puntatore a un buffer di input da passare al driver inferiore o NULL se la richiesta non passa i dati di input ai driver inferiori.
[in] InputBufferLength
Fornisce la lunghezza, in byte, del buffer di input. Se InputBuffer è NULL, InputBufferLength deve essere zero.
[out, optional] OutputBuffer
Fornisce un puntatore a un buffer di output in cui il driver inferiore restituisce dati o NULL se la richiesta non richiede driver inferiori per restituire i dati.
[in] OutputBufferLength
Fornisce la lunghezza, in byte, del buffer di output. Se OutputBuffer è NULL, OutputBufferLength deve essere zero.
[in] InternalDeviceIoControl
Se TRUE, la routine imposta il codice della funzione principale dell'IRP su IRP_MJ_INTERNAL_DEVICE_CONTROL. In caso contrario, la routine imposta il codice di funzione principale di IRP su IRP_MJ_DEVICE_CONTROL.
[in, optional] Event
Fornisce un puntatore a un oggetto evento allocato dal chiamante e inizializzato. Gestione I/O imposta l'evento sullo stato segnalato quando un driver di livello inferiore completa l'operazione richiesta. Dopo aver chiamato IoCallDriver, il driver può attendere l'oggetto evento. Il parametro Event è facoltativo e può essere impostato su NULL. Tuttavia, se Event è NULL, il chiamante deve fornire una routine IoCompletion per l'IRP per notificare al chiamante al termine dell'operazione.
[out] IoStatusBlock
Specifica un blocco di stato di I/O da impostare quando la richiesta viene completata da driver inferiori.
Valore restituito
Se l'operazione ha esito positivo, IoBuildDeviceIoControlRequest restituisce un puntatore a un'IRP, con la posizione dello stack I/O del driver inferiore successivo configurata dai parametri forniti. In caso contrario, la routine restituisce NULL.
Commenti
Un driver può chiamare IoBuildDeviceIoControlRequest per configurare irP per le richieste di controllo del dispositivo che invia in modo sincrono ai driver di livello inferiore.
Dopo aver chiamato IoBuildDeviceIoControlRequest per creare una richiesta, il driver deve chiamare IoCallDriver per inviare la richiesta al driver inferiore successivo. Se IoCallDriver restituisce STATUS_PENDING, il driver deve attendere il completamento dell'IRP chiamando KeWaitForSingleObjectnell'evento specificato. La maggior parte dei driver non deve impostare una routine IoCompletion per l'IRP .
Gli IRP creati da IoBuildDeviceIoControlRequest devono essere completati dalla chiamata di un driver a IoCompleteRequest. Un driver che chiama IoBuildDeviceIoControlRequest non deve chiamare IoFreeIrp, perché il gestore I/O libera questi IRP sincroni dopo la chiamata di IoCompleteRequest .
IoBuildDeviceIoControlRequest accoda gli indirizzi IP creati in una coda IRP specifica del thread corrente. Se il thread viene chiuso, il gestore di I/O annulla l'IRP.
Se il chiamante fornisce un parametro InputBuffer o OutputBuffer , questo parametro deve puntare a un buffer che risiede nella memoria di sistema. Il chiamante è responsabile della convalida di tutti i valori dei parametri copiati nel buffer di input da un buffer in modalità utente. Il buffer di input può contenere valori di parametro interpretati in modo diverso a seconda che l'origine della richiesta sia un'applicazione in modalità utente o un driver in modalità kernel. Nell'IRP restituito da IoBuildDeviceIoControlRequest , il campo RequestorMode è sempre impostato su KernelMode. Questo valore indica che la richiesta e tutte le informazioni contenute nella richiesta provengono da un componente in modalità kernel attendibile.
Se il chiamante non può convalidare i valori dei parametri copiati da un buffer in modalità utente al buffer di input oppure se questi valori non devono essere interpretati come provenienti da un componente in modalità kernel, il chiamante deve impostare il campo RequestorMode in UserMode. Questa impostazione informa il driver che gestisce la richiesta di controllo I/O che il buffer contiene dati in modalità utente non attendibili.
Il metodo effettivo in base al quale i contenuti dei parametri InputBuffer e OutputBuffer vengono archiviati in IRP dipendono dal valore TransferType per IOCTL. Per altre informazioni su questo valore, vedere Descrizioni del buffer per i codici di controllo I/O.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 2000. |
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| Regole di conformità DDI | HwStorPortProhibitedDDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm),SignalEventInCompletion(wdm) |