CcPinRead-Funktion (ntifs.h)

Artikel
12/20/2024

Die CcPinRead Routine pins the specified byte range of a cached file and reads the pinned data into a buffer in memory.

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

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

[in] FileOffset

Zeigen Sie auf eine Variable, die den Anfangsbyte-Offset 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. Kombination aus einem oder mehreren der folgenden Werte:

Wert	Bedeutung
PIN_WAIT	Der Aufrufer kann in einen Wartezustand versetzt werden, bis die Daten angeheftet wurden.
PIN_EXCLUSIVE	Der Puffersteuerelementblock (BCB) ist ausschließlich zu erwerben. Wenn dieses Kennzeichen festgelegt ist, muss auch PIN_WAIT festgelegt werden.
PIN_NO_READ	Es müssen nur Seiten angeheftet werden, die bereits im Arbeitsspeicher vorhanden sind. Wenn dieses Kennzeichen festgelegt ist, muss auch PIN_WAIT festgelegt werden.
PIN_IF_BCB	Die Daten sind nur dann anzuheften, wenn bereits ein BCB vorhanden ist. Andernfalls schlägt der Pin fehl, und Bcb- auf NULL-festgelegt ist.

[out] Bcb

Beim ersten Aufruf wird ein Zeiger auf einen Puffersteuerelementblock (BCB) zurückgegeben. Dieser Zeiger muss als Eingabe für alle nachfolgenden Aufrufe für diesen Puffer bereitgestellt werden.

[out] Buffer

Zeigen Sie 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, FALSE andernfalls.

Bemerkungen

Wenn das PIN_WAIT-Flag festgelegt ist, wird CcPinRead- garantiert die Anheftanforderung abschließen und TRUE-zurückgeben. Wenn die erforderlichen Seiten der zwischengespeicherten Datei bereits im Arbeitsspeicher vorhanden sind, werden die Daten sofort angeheftet 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 angeheftet werden können. Wenn das PIN_WAIT Flag nicht festgelegt ist, die Daten jedoch nicht sofort angeheftet werden können, gibt CcPinRead-FALSE-zurück, und die Ausgabeparameterwerte sind bedeutungslos.

Wenn der Aufrufer die von CcPinReadgelesenen Daten anschließend ä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 mit einem 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- können daten nicht über Ansichtsgrenzen im Cache-Manager anheften. Der Cache-Manager verwaltet Dateien im System in 256 KB ausgerichteten Ansichten. (Die Ansichtsgröße des Cache-Managers wird durch die vom System definierte Konstante VACB_MAPPING_GRANULARITY angegeben, die auf 256 KB in ntifs.h festgelegt ist.) Angeheftete Bereiche können nicht mehr als eine 256 KB-Ansicht umfassen. Daher beträgt der größte Bereich, der angeheftet werden kann, 256 KB, beginnend mit einem 256 KB ausgerichteten Offset in der Datei.

Durch das Anheften eines Bytebereichs in einer zwischengespeicherten Datei wird nicht sichergestellt, 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, da die Speichernachfrage des Systems erforderlich ist.

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. Um die Kontrolle zu erlangen, wenn ein Fehler auftritt, sollte der Treiber den Aufruf von CcPinRead- in einem try-except oder try-finally Anweisung umschließen.

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