CcPinMappedData-Funktion (ntifs.h)

Artikel
12/21/2024

Mit dem CcPinMappedData Routine wird der angegebene Bytebereich einer zwischengespeicherten Datei angeheftet.

Syntax

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

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 in Byte der daten, die angeheftet werden sollen.

[in] Flags

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

Flagge	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.

[in, 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.

Rückgabewert

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

Bemerkungen

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

CcPinMappedData- daten nicht über Ansichtsgrenzen im Cache-Manager anheften können. 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_GRANULARITYangegeben, die in ntifs.hauf 256 KB 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 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. Um die Kontrolle zu erlangen, wenn ein Fehler auftritt, sollte der Treiber den Aufruf von CcPinMappedData- 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.

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