Funzione IoBuildSynchronousFsdRequest (wdm.h)

Articolo
08/08/2023

La routine IoBuildSynchronousFsdRequest alloca e configura un'IRP per una richiesta di I/O sincrona.

Sintassi

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock
);

Parametri

[in] MajorFunction

Codice della funzione principale per l'IRP. Questo codice può essere IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS o IRP_MJ_SHUTDOWN.

[in] DeviceObject

Puntatore alla struttura DEVICE_OBJECT per l'oggetto dispositivo del driver inferiore successivo, che rappresenta il dispositivo di destinazione.

[in, out] Buffer

Puntatore a un buffer di dati. Se MajorFunction è IRP_MJ_WRITE, il buffer contiene dati da scrivere. Se MajorFunction è IRP_MJ_READ, il buffer riceve i dati. Se MajorFunction è IRP_MJ_FLUSH_BUFFERS o IRP_MJ_SHUTDOWN, questo parametro deve essere NULL.

[in, optional] Length

Lunghezza, in byte, del buffer a cui punta buffer. Per i dispositivi come i dischi, questo valore deve essere un numero intero multiplo delle dimensioni del settore. A partire da Windows 8, la dimensione del settore può essere di 4.096 o 512 byte. Nelle versioni precedenti di Windows, le dimensioni del settore sono sempre 512 byte. Questo parametro è necessario per le richieste di lettura e scrittura, ma deve essere zero per le richieste di scaricamento e arresto.

[in, optional] StartingOffset

Puntatore all'offset sul disco, per le richieste di lettura e scrittura. Le unità e il significato di questo valore sono specifiche del driver. Questo parametro è necessario per le richieste di lettura e scrittura, ma deve essere zero per le richieste di scaricamento e arresto.

[in] Event

Puntatore a un oggetto evento allocato e inizializzato del chiamante. 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.

[out] IoStatusBlock

Puntatore a una posizione che riceve il blocco di stato di I/O impostato quando l'IRP viene completato da un driver di livello inferiore.

Valore restituito

Se l'operazione ha esito positivo, IoBuildSynchronousFsdRequest restituisce un puntatore a una struttura IRP inizializzata, con la posizione dello stack I/O inferiore successivo configurata dai parametri forniti. In caso contrario, la routine restituisce NULL.

Commenti

Un driver di file system (FSD) o un altro driver di livello superiore può chiamare IoBuildSynchronousFsdRequest per configurare i provider di integrazione che invia in modo sincrono ai driver di livello inferiore.

IoBuildSynchronousFsdRequest alloca e configura un'istanza di IRP che richiede driver di livello inferiore per eseguire un'operazione di lettura, scrittura, scaricamento o arresto sincrona. L'IRP contiene informazioni sufficienti per avviare l'operazione.

I driver di livello inferiore potrebbero imporre restrizioni sui parametri forniti a questa routine. Ad esempio, i driver di disco potrebbero richiedere che i valori forniti per Length e StartingOffset siano interi più delle dimensioni del settore del dispositivo.

Dopo aver chiamato IoBuildSynchronousFsdRequest 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 IoBuildSynchronousFsdRequest devono essere completati dalla chiamata di un driver a IoCompleteRequest. Un driver che chiama IoBuildSynchronousFsdRequest non deve chiamare IoFreeIrp, perché il gestore I/O libera questi IRP sincroni dopo la chiamata di IoCompleteRequest .

IoBuildSynchronousFsdRequest accoda gli indirizzi IP creati in una coda IRP specifica per il thread corrente. Se il thread viene chiuso, il gestore di I/O annulla l'IRP.

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	ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDDDIs(storport), IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)