CcPinMappedData-Funktion (ntifs.h)

Artikel
08/07/2023

Die CcPinMappedData-Routine pint den angegebenen Bytebereich einer zwischengespeicherten Datei an.

Syntax

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

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 innerhalb der zwischengespeicherten Datei angibt, in der sich die gewünschten Daten befinden.

[in] Length

Länge der anzuheftenden Daten in Byte.

[in] Flags

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

Flag	Bedeutung
PIN_WAIT	Der Aufrufer kann in einen Wartezustand versetzt werden, bis die Daten angeheftet wurden.
PIN_EXCLUSIVE	Der Pufferkontrollblock (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 sollen nur angeheftet werden, wenn bereits ein BCB vorhanden ist. Andernfalls schlägt der Pin fehl, und Bcb ist auf NULL festgelegt.

[in, out] Bcb

Beim ersten Aufruf wird 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 bereitgestellt werden.

Rückgabewert

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

Hinweise

Eine erfolgreiche Rückgabe von CcPinMappedData garantiert, dass die Daten, die zuvor in einem Aufruf von CcMapData zugeordnet wurden, im Cache angeheftet werden und Daten im angegebenen Bereich sicher geändert werden können. Wenn der Aufrufer anschließend die von CcPinMappedData angehefteten Daten ändert, muss er auch CcSetDirtyPinnedData aufrufen, damit die geänderten Daten schließlich auf den Datenträger geschrieben werden.

CcPinMappedData kann im Cache-Manager keine Daten über Ansichtsgrenzen hinweg anheften. Der Cache-Manager verwaltet Dateien im System in Ansichten mit 256 KB-Ausrichtung. (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 Bereiche dürfen nicht mehr als eine Ansicht mit 256 KB umfassen. Daher ist der größte Bereich, der angeheftet werden kann, 256 KB, beginnend bei 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 entsprechend dem Arbeitsspeicherbedarf des Systems ausblättern.

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

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

Es ist nicht erforderlich, CcUnpinData nach dem Aufruf von CcPinMappedData aufzurufen, da der Pinverweis mit CcMapData übereinstimmt.