FsRtlCopyRead-Funktion (ntifs.h)
Die FsRtlCopyRead-Routine kopiert Daten aus einer zwischengespeicherten Datei in einen Benutzerpuffer.
Syntax
BOOLEAN FsRtlCopyRead(
[in] PFILE_OBJECT FileObject,
[in] PLARGE_INTEGER FileOffset,
[in] ULONG Length,
[in] BOOLEAN Wait,
[in] ULONG LockKey,
[out] PVOID Buffer,
[out] PIO_STATUS_BLOCK IoStatus,
[in] PDEVICE_OBJECT DeviceObject
);
Parameter
[in] FileObject
Zeiger auf ein Dateiobjekt für die zwischengespeicherte Datei, aus der die Daten gelesen werden sollen.
[in] FileOffset
Startbyteoffset in der zwischengespeicherten Datei.
[in] Length
Länge der zu lesenden Daten in Bytes.
[in] Wait
Legen Sie auf TRUE fest, wenn der Aufrufer in einen Wartezustand versetzt werden kann, bis alle Daten kopiert wurden, andernfalls FALSE.
[in] LockKey
Ein Wert, der dem zu sperrenden Bytebereich zugeordnet ist. Wenn der zu sperrende Bereich einen anderen Bereich überschneidet, der bereits mit einer nicht exklusiven Sperre gesperrt ist, oder wenn der zu lesende Bereich ein Unterbereich eines anderen Bereichs ist, der bereits nicht endgültig gesperrt ist, muss der Wert in diesem Parameter der Schlüssel für diese nicht exklusive Sperre sein. Die Sperre muss vom übergeordneten Prozess des aufrufenden Threads gehalten werden. Andernfalls hat dieser Parameter keine Auswirkung.
[out] Buffer
Zeiger auf einen Puffer, in den die Daten kopiert werden sollen.
[out] IoStatus
Zeiger auf eine vom Aufrufer zugewiesene Struktur, die die endgültige Vervollständigung status und Informationen zum Vorgang empfängt. Wenn die Daten erfolgreich kopiert wurden, enthält IoStatus.Status STATUS_SUCCESS. Wenn nicht alle Daten erfolgreich kopiert wurden, enthält IoStatus.Information die tatsächliche Anzahl von Bytes, die kopiert wurden.
[in] DeviceObject
Das Geräteobjekt für das Gerät, das die Dateidaten enthält.
Rückgabewert
FsRtlCopyRead gibt TRUE zurück, wenn die Kopieranforderung abgeschlossen wurde, andernfalls FALSE. Beachten Sie, dass ein Rückgabewert von TRUE nicht unbedingt bedeutet, dass der Kopiervorgang erfolgreich war.
Wenn FsRtlCopyRead FALSE zurückgibt oder der Inhalt von IoStatus darauf hindeutet, dass der Kopiervorgang fehlgeschlagen ist, muss der Aufrufer eine Lese-IRP zuweisen, anstatt FsRtlCopyRead aufzurufen.
Hinweise
Anstatt eine dateisystemspezifische schnelle E/A-Leseroutine zu implementieren, sollten Entwickler von Dateisystemen, die die Dateizwischenspeicherung unterstützen, die Verwendung von FsRtlCopyRead als Einstiegspunkt des Dateisystems für die Verarbeitung schneller E/A-Leseanforderungen in Erwägung ziehen. Dies erfordert, dass die DriverEntry-Routine des Dateisystems den FastIoRead-Einstiegspunkt in der FAST_IO_DISPATCH Struktur des Dateisystemtreiberobjekts auf FsRtlCopyRead festgelegt. Darüber hinaus muss das Dateisystem Folgendes tun:
Für jede Datei, für die schnelle E/A ausgeführt werden kann, muss das Dateisystem eine FSRTL_COMMON_FCB_HEADER Struktur zuordnen und initialisieren.
In den meisten Dateisystemen wird dies erreicht, indem die FSRTL_COMMON_FCB_HEADER-Struktur in einen Dateisteuerungsblock (FCB) oder eine vergleichbare Struktur eingeschlossen wird, die zum Beibehalten des Zustands einer geöffneten Datei verwendet wird.
Der Speicher für die FSRTL_COMMON_FCB_HEADER-Struktur wird in der Regel aus einem ausgelagerten Pool zugeordnet.
Für jede Datei, für die schnelle E/A ausgeführt werden kann, muss das Dateisystem alle Dateiobjekte für die Datei mit der FSRTL_COMMON_FCB_HEADER Struktur verknüpfen. Dies geschieht, indem sie das FsContext-Element jedes Dateiobjekts so festlegen, dass er auf diese Struktur verweist (oder auf die FCB- oder andere Struktur, die die FSRTL_COMMON_FCB_HEADER-Struktur enthält).
Beim Zwischenspeichern einer Datei muss das Dateisystem das IsFastIoPossible-Element der FSRTL_COMMON_FCB_HEADER Struktur der Datei auf einen entsprechenden Wert festlegen. Dieser Wert sollte bei Bedarf aktualisiert werden, solange die Datei zwischengespeichert bleibt.
Insbesondere sollten Dateisysteme den IsFastIoPossible-Member der FSRTL_COMMON_FCB_HEADER Struktur auf FastIoIsQuestionable festlegen, sobald eine exklusive Bytebereichssperre für die zwischengespeicherte Datei vorhanden ist.
Wenn Wait TRUE ist, wird garantiert , dass FsRtlCopyRead die Kopieranforderung abgeschlossen und TRUE zurückgibt. Wenn sich die erforderlichen Seiten der zwischengespeicherten Datei bereits im Arbeitsspeicher befinden, werden die Daten sofort kopiert, und es tritt keine Blockierung auf. Wenn die benötigten Seiten nicht vorhanden sind, wird der Aufrufer in einen Wartezustand versetzt, bis alle erforderlichen Seiten als resident festgelegt wurden und die Daten kopiert werden können.
Wenn Wait false ist, lehnt FsRtlCopyRead die Blockierung ab und gibt FALSE zurück, wenn die Standard Ressource der Datei nicht abgerufen werden kann oder wenn die erforderlichen Seiten der zwischengespeicherten Datei nicht bereits im Arbeitsspeicher gespeichert sind.
Die FastIoCheckIfPossible-Routine des Dateisystems ist dafür verantwortlich, sicherzustellen, dass der durch FileOffset und Length definierte Bytebereich keinen exklusiv gesperrten Bytebereich enthält, für den der Aufrufer den entsprechenden LockKey-Wert nicht übergibt. Wenn das Dateisystem die FsRtlXxxLock Yyy-Unterstützungsroutinen verwendet, um Bytebereichsperren zu verwalten, kann dies durch Aufrufen von FsRtlFastCheckLockForRead aus der FastIoCheckIfPossible-Routine erreicht werden, bevor FsRtlCopyRead aufgerufen wird.
Verwenden Sie zum Zwischenspeichern einer Datei die CcInitializeCacheMap-Routine .
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | ntifs.h (include Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI-Complianceregeln | PowerIrpDDis(wdm) |