Funzione IoBuildDeviceIoControlRequest (wdm.h)

Articolo
08/08/2023

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)