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

Zeigen Sie auf ein Dateiobjekt für die zwischengespeicherte Datei, aus der die Daten gelesen werden sollen.

[in] FileOffset

Byteoffset innerhalb der zwischengespeicherten Datei wird gestartet.

[in] Length

Länge in Byte der zu lesenden Daten.

[in] Wait

Auf TRUE festgelegt, 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 überlappt, der bereits mit einer nicht exklusiven Sperre gesperrt ist, oder wenn der zu lesende Bereich ein Unterbereich eines anderen Bereichs ist, der bereits nichtexklusiv gesperrt ist, muss der Wert in diesem Parameter der Schlüssel für diese nichtexklusive Sperre sein. Die Sperre muss vom übergeordneten Prozess des aufrufenden Threads gehalten werden. Andernfalls hat dieser Parameter keine Auswirkung.

[out] Buffer

Zeigen Sie auf einen Puffer, in den die Daten kopiert werden sollen.

[out] IoStatus

Zeigen Sie auf eine vom Aufrufer zugewiesene Struktur, die den endgültigen Abschlussstatus und Informationen zum Vorgang empfängt. Wenn die Daten erfolgreich kopiert werden, enthält IoStatus.Status- STATUS_SUCCESS. Wenn nicht alle Daten erfolgreich kopiert werden, 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 "TRUE" zurück, wenn die Kopieranforderung abgeschlossen wurde, andernfalls FALSE. Beachten Sie, dass ein Rückgabewert von TRUE nicht notwendigerweise bedeutet, dass der Kopiervorgang erfolgreich war.

Wenn FsRtlCopyRead FALSE zurückgibt, oder wenn der Inhalt von IoStatus darauf hinweist, dass der Kopiervorgang fehlgeschlagen ist, muss der Aufrufer ein Lese-IRP zuweisen, anstatt FsRtlCopyReadaufzurufen.

Bemerkungen

Anstatt eine dateisystemspezifische schnelle E/A-Leseroutine zu implementieren, sollten Entwickler von Dateisystemen, die die Dateizwischenspeicherung unterstützen, FsRtlCopyRead- als Einstiegspunkt des Dateisystems für die Verarbeitung schneller E/A-Leseanforderungen in Betracht ziehen. Dies erfordert, dass die DriverEntry Routine des Dateisystems den FastIoRead Einstiegspunkt auf FsRtlCopyRead in der FAST_IO_DISPATCH Struktur des Dateisystemtreiberobjekts festlegen. Darüber hinaus muss das Dateisystem folgendes ausführen:

1. 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 (FILE Control Block, FCB) oder eine vergleichbare Struktur eingeschlossen wird, die verwendet wird, um den Zustand einer geöffneten Datei beizubehalten.

   Der Speicher für die FSRTL_COMMON_FCB_HEADER-Struktur wird in der Regel aus dem ausgelagerten Pool zugewiesen.

2. 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 erfolgt durch Festlegen der FsContext Member jedes Dateiobjekts, um auf diese Struktur zu verweisen (oder die FCB oder eine andere Struktur, die die FSRTL_COMMON_FCB_HEADER Struktur enthält).

3. Beim Zwischenspeichern einer Datei muss das Dateisystem den IsFastIoPossible Member der FSRTL_COMMON_FCB_HEADER Struktur der Datei auf einen geeigneten Wert festlegen. Dieser Wert sollte nach Bedarf aktualisiert werden, solange die Datei zwischengespeichert bleibt.

   Insbesondere sollten Dateisysteme die IsFastIoPossible Member der FSRTL_COMMON_FCB_HEADER Struktur so festlegen, dass sie FastIoIsQuestionable , sobald eine exklusive Bytebereichssperre für die zwischengespeicherte Datei vorhanden ist.

Wenn Wait WAHR ist, ist FsRtlCopyRead garantiert, dass die Kopieranforderung abgeschlossen und TRUE zurückgegeben wird. Wenn die erforderlichen Seiten der zwischengespeicherten Datei bereits im Arbeitsspeicher vorhanden sind, werden die Daten sofort kopiert, und es tritt keine Blockierung auf. Wenn erforderliche Seiten nicht vorhanden sind, wird der Aufrufer in einen Wartezustand versetzt, bis alle erforderlichen Seiten resident wurden und die Daten kopiert werden können.

Wenn Wait FALSE ist, wird FsRtlCopyRead die Blockierung verweigern und FALSE zurückgeben, wenn sie die Hauptressource der Datei nicht abrufen kann oder die erforderlichen Seiten der zwischengespeicherten Datei nicht bereits im Arbeitsspeicher vorhanden sind.

Die FastIoCheckIfPossible Routine des Dateisystems ist dafür verantwortlich, sicherzustellen, dass der durch FileOffset- definierte Bytebereich und Length keinen exklusiv gesperrten Bytebereich enthält, für den der Aufrufer nicht den entsprechenden LockKey Wert übergibt. Wenn das Dateisystem die FsRtlXxxLockYyy Supportroutinen zum Verwalten von Bytebereichssperren verwendet, kann dies durch Aufrufen FsRtlFastCheckLockForReadForRead aus der FastIoCheckIfPossible Routine erreicht werden, bevor FsRtlCopyReadaufgerufen wird.

Verwenden Sie zum Zwischenspeichern einer Datei die CcInitializeCacheMap Routine.

Anforderungen

Siehe auch

CcInitializeCacheMap-

FsRtlCopyWrite

FsRtlFastCheckLockForRead