IoBuildSynchronousFsdRequest-Funktion (wdm.h)
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) |