IoBuildSynchronousFsdRequest-Funktion (wdm.h)

Artikel
02/29/2024

Die IoBuildSynchronousFsdRequest-Routine ordnet eine IRP für eine synchron verarbeitete E/A-Anforderung zu und richtet sie ein.

Syntax

__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
);

Parameter

[in] MajorFunction

Der Hauptfunktionscode für die IRP. Dieser Code kann IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS oder IRP_MJ_SHUTDOWN sein.

[in] DeviceObject

Ein Zeiger auf die DEVICE_OBJECT Struktur für das Geräteobjekt des nächstniedrigen Treibers, das das Zielgerät darstellt.

[in, out] Buffer

Ein Zeiger auf einen Datenpuffer. Wenn MajorFunctionIRP_MJ_WRITE ist, enthält der Puffer daten, die geschrieben werden sollen. Wenn MajorFunctionIRP_MJ_READ ist, empfängt der Puffer Daten. Wenn MajorFunctionIRP_MJ_FLUSH_BUFFERS oder IRP_MJ_SHUTDOWN ist, muss dieser Parameter NULL sein.

[in, optional] Length

Die Länge des Puffers in Bytes, auf den puffer verweist. Für Geräte wie Datenträger muss dieser Wert ein ganzzahliges Vielfaches der Sektorgröße sein. Ab Windows 8 kann die Sektorgröße 4.096 oder 512 Bytes betragen. In früheren Versionen von Windows beträgt die Sektorgröße immer 512 Bytes. Dieser Parameter ist für Lese- und Schreibanforderungen erforderlich, muss aber für Leer- und Herunterfahrensanforderungen null sein.

[in, optional] StartingOffset

Ein Zeiger auf den Offset auf dem Datenträger für Lese- und Schreibanforderungen. Die Einheiten und die Bedeutung dieses Werts sind treiberspezifisch. Dieser Parameter ist für Lese- und Schreibanforderungen erforderlich, muss aber für Leer- und Herunterfahrensanforderungen null sein.

[in] Event

Ein Zeiger auf ein vom Aufrufer zugewiesenes und initialisiertes Ereignisobjekt. Der E/A-Manager legt das Ereignis auf den Signalzustand fest, wenn ein Treiber auf niedrigerer Ebene den angeforderten Vorgang abschließt. Nach dem Aufrufen von IoCallDriver kann der Treiber auf das Ereignisobjekt warten.

[out] IoStatusBlock

Ein Zeiger auf eine Position, die den E/A-status-Block empfängt, der festgelegt wird, wenn der IRP von einem Treiber auf niedrigerer Ebene abgeschlossen wird.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt IoBuildSynchronousFsdRequest einen Zeiger auf eine initialisierte IRP-Struktur zurück, wobei der E/A-Stapelspeicherort des nächstniedrigen Treibers aus den angegebenen Parametern eingerichtet ist. Andernfalls gibt die Routine NULL zurück.

Hinweise

Ein Dateisystemtreiber (FSD) oder ein anderer Treiber auf höherer Ebene kann IoBuildSynchronousFsdRequest aufrufen, um IRPs einzurichten, die synchron an Treiber auf niedrigerer Ebene gesendet werden.

IoBuildSynchronousFsdRequest ordnet ein IRP zu und richtet diese ein, das Treiber auf niedrigerer Ebene anfordert, um einen synchronen Lese-, Schreib-, Lösch- oder Herunterfahrvorgang auszuführen. Die IRP enthält genügend Informationen zum Starten des Vorgangs.

Treiber auf niedrigerer Ebene können Einschränkungen für parameter erzwingen, die für diese Routine bereitgestellt werden. Beispielsweise können Datenträgertreiber erfordern, dass die für Length und StartingOffset angegebenen Werte ganzzahlige Vielfache der Sektorgröße des Geräts sind.

Nach dem Aufrufen von IoBuildSynchronousFsdRequest zum Erstellen einer Anforderung muss der Treiber IoCallDriver aufrufen, um die Anforderung an den nächstniedrigen Treiber zu senden. Wenn IoCallDriver STATUS_PENDING zurückgibt, muss der Treiber auf den Abschluss des IRP warten, indem er KeWaitForSingleObject für das angegebene Ereignis aufruft. Die meisten Treiber müssen keine IoCompletion-Routine für die IRP festlegen.

IRPs, die von IoBuildSynchronousFsdRequest erstellt werden, müssen durch den Aufruf eines Treibers an IoCompleteRequest abgeschlossen werden. Ein Treiber, der IoBuildSynchronousFsdRequest aufruft, darf IoFreeIrp nicht aufrufen, da der E/A-Manager diese synchronen IRPs freigibt, nachdem IoCompleteRequest aufgerufen wurde.

IoBuildSynchronousFsdRequest stellt die IRPs, die erstellt werden, in eine IRP-Warteschlange ein, die für den aktuellen Thread spezifisch ist. Wenn der Thread beendet wird, bricht der E/A-Manager die IRP ab.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI-Complianceregeln	ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDIs(storport), IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)