CcPinRead-Funktion (ntifs.h)

Artikel
02/29/2024

Die CcPinRead-Routine pint den angegebenen Bytebereich einer zwischengespeicherten Datei an und liest die angehefteten Daten in einen Puffer im Arbeitsspeicher.

Syntax

BOOLEAN CcPinRead(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  ULONG          Flags,
  [out] PVOID          *Bcb,
  [out] PVOID          *Buffer
);

Parameter

[in] FileObject

Zeiger auf ein Dateiobjekt für die zwischengespeicherte Datei, in der ein Datenbereich angeheftet werden soll.

[in] FileOffset

Zeiger auf eine Variable, die den Anfangsbyteoffset in der zwischengespeicherten Datei angibt, in der sich die gewünschten Daten befinden.

[in] Length

Länge der gewünschten Daten in Bytes.

[in] Flags

Bitmaske von Flags, die angeben, wie der Anheftvorgang ausgeführt werden soll. ORed-Kombination aus mindestens einem der folgenden Werte:

Wert	Bedeutung
PIN_WAIT	Der Aufrufer kann in einen Wartezustand versetzt werden, bis die Daten angeheftet wurden.
PIN_EXCLUSIVE	Der Puffersteuerungsblock (Buffer Control Block, BCB) soll ausschließlich abgerufen werden. Wenn dieses Flag festgelegt ist, muss auch PIN_WAIT festgelegt werden.
PIN_NO_READ	Nur Seiten, die sich bereits im Arbeitsspeicher befinden, sollen angeheftet werden. Wenn dieses Flag festgelegt ist, muss auch PIN_WAIT festgelegt werden.
PIN_IF_BCB	Die Daten dürfen nur angeheftet werden, wenn bereits ein BCB vorhanden ist. Andernfalls schlägt der Pin fehl, und Bcb ist auf NULL festgelegt.

[out] Bcb

Beim ersten Aufruf wird dadurch ein Zeiger auf einen Puffersteuerungsblock (Buffer Control Block, BCB) zurückgegeben. Dieser Zeiger muss als Eingabe für alle nachfolgenden Aufrufe für diesen Puffer angegeben werden.

[out] Buffer

Zeiger auf einen Puffer, der die angehefteten Daten enthält.

Rückgabewert

CcPinRead gibt TRUE zurück, wenn die Daten für die zwischengespeicherte Datei erfolgreich angeheftet und gelesen wurden, andernfalls FALSE .

Hinweise

Wenn das PIN_WAIT-Flag festgelegt ist, wird von CcPinRead garantiert, dass die Anheftanforderung abgeschlossen und TRUE zurückgegeben wird. Wenn sich die erforderlichen Seiten der zwischengespeicherten Datei bereits im Arbeitsspeicher befinden, werden die Daten sofort angeheftet, und es erfolgt keine Blockierung. Wenn keine benötigten Seiten vorhanden sind, wird der Aufrufer in einen Wartezustand versetzt, bis alle erforderlichen Seiten als resident festgelegt wurden und die Daten angeheftet werden können. Wenn das flag PIN_WAIT nicht festgelegt ist, die Daten aber nicht sofort angeheftet werden können, gibt CcPinReadFALSE zurück, und die Ausgabeparameterwerte sind bedeutungslos.

Wenn der Aufrufer anschließend die von CcPinRead gelesenen Daten ändert, muss er auch CcSetDirtyPinnedData aufrufen, damit die geänderten Daten schließlich auf den Datenträger geschrieben werden.

Jeder erfolgreiche Aufruf von CcPinRead muss durch einen nachfolgenden Aufruf von CcUnpinData abgeglichen werden.

Der in Buffer zurückgegebene Zeiger ist gültig, bis CcUnpinData aufgerufen wird. Wenn CcPinMappedData aufgerufen wird, während dieser Zeiger noch gültig ist, bleibt der Zeiger nach dem Aufruf von CcPinMappedData gültig (aber nur bis CcUnpinData aufgerufen wird).

CcPinRead kann keine Daten über Ansichtsgrenzen im Cache-Manager anheften. Der Cache-Manager verwaltet Dateien im System in 256 KB ausgerichteten Ansichten. (Die Größe der Ansicht des Cache-Managers wird durch die systemdefinierte Konstante VACB_MAPPING_GRANULARITY angegeben, die in ntifs.h auf 256 KB festgelegt ist.) Angeheftete Regionen können nicht mehr als eine 256 KB-Ansicht umfassen. Daher ist die größte Region, die angeheftet werden kann, 256 KB, beginnend mit einem 256 KB ausgerichteten Offset in der Datei.

Das Anheften eines Bytebereichs in einer zwischengespeicherten Datei stellt nicht sicher, dass die Seiten im Arbeitsspeicher verbleiben. Solange die Seiten angeheftet sind, bleibt der Bytebereich garantiert dem virtuellen Adressraum des Systemcaches zugeordnet, aber der Speicher-Manager kann die physischen Seiten ausblättern, wie der Arbeitsspeicherbedarf des Systems erfordert.

Wenn ein Fehler auftritt, löst CcPinRead eine status Ausnahme für diesen bestimmten Fehler aus. Wenn beispielsweise ein Poolzuordnungsfehler auftritt, löst CcPinRead eine STATUS_INSUFFICIENT_RESOURCES Ausnahme aus. Wenn ein E/A-Fehler auftritt, löst CcPinRead die status Ausnahme des E/A-Fehlers aus. Daher sollte der Treiber den Aufruf von CcPinRead in eine try-except- oder try-finally-Anweisung umschließen, um die Kontrolle zu erlangen, wenn ein Fehler auftritt.

Verwenden Sie zum Zuordnen von Daten für eine zwischengespeicherte Datei die CcMapData-Routine . Um eine Datei zwischenzuspeichern, verwenden Sie CcInitializeCacheMap.