CcPreparePinWrite-Funktion (ntifs.h)

Artikel
02/29/2024

Die CcPreparePinWrite-Routine pint den angegebenen Bytebereich einer zwischengespeicherten Datei für den Schreibzugriff an.

Syntax

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

Parameter

[in] FileObject

Zeiger auf ein Dateiobjekt für die zwischengespeicherte Datei, in die die Daten geschrieben werden sollen.

[in] FileOffset

Zeiger auf eine Variable, die den Anfangsbyteoffset innerhalb der Datei angibt, in die die Daten geschrieben werden sollen.

[in] Length

Länge der gewünschten Daten in Bytes.

[in] Zero

Legen Sie auf TRUE fest, wenn der Puffer bei der Rückgabe auf null gesetzt werden soll. Dieser Parameter wird ignoriert, wenn das flag PIN_CALLER_TRACKS_DIRTY_DATA im Flags-Parameter festgelegt ist.

[in] Flags

Bitmaske von Flags, die angeben, wie der Anheftungsvorgang ausgeführt werden soll. ORed-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 Pufferkontrollblock (BUFFER Control Block, BCB) soll ausschließlich abgerufen 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 es wird kein BCB zurückgegeben.
PIN_CALLER_TRACKS_DIRTY_DATA	Der Aufrufer ist dafür verantwortlich, modifiziert Seiten nachzuverfolgen. Wenn dieses Flag festgelegt ist, werden alle anderen Flags ignoriert. Dieses Flag ist unter Microsoft Windows Server 2003 SP1 und höher verfügbar.

[out] Bcb

Undurchsichtiger Zeiger auf einen angehefteten Pufferkontrollblock (BCB). Dieser Zeiger muss als Eingabe für alle nachfolgenden Aufrufe von CcPreparePinWrite oder CcUnpinData für diesen Puffer bereitgestellt werden.

[out] Buffer

Gibt den Zeiger auf die gewünschten Daten zurück, gültig, bis der Puffer aufgehoben oder freigegeben wurde.

Rückgabewert

CcPreparePinWrite gibt TRUE zurück, wenn die zwischengespeicherte Datei erfolgreich angeheftet wurde, andernfalls FALSE .

Hinweise

CcPreparePinWrite pint die angegebenen Dateiseiten im Systemcache an. Seiten, die vollständig überschrieben werden sollen, können mit Seiten mit Nullen zufrieden sein.

Wenn das flag PIN_WAIT festgelegt ist, wird ccPreparePinWrite garantiert, dass die Vorbereitungsanforderung abgeschlossen und TRUE zurückgegeben wird. Wenn alle Seiten sofort vorbereitet werden können, erfolgt keine Blockierung. Wenn benötigte Seiten nicht resident sind, wird der Aufrufer in einen Wartezustand versetzt, bis alle erforderlichen Seiten als resident festgelegt wurden und die Seiten vorbereitet werden können. Wenn das PIN_WAIT Flag nicht festgelegt ist, aber nicht alle Seiten sofort vorbereitet werden können, gibt CcPreparePinWriteFALSE zurück, und die Ausgabeparameterwerte sind bedeutungslos.

Microsoft Windows Server 2003 SP1 und höher: Das flag PIN_CALLER_TRACKS_DIRTY_DATA wird häufig in Fällen verwendet, in denen ein Dateisystem eine Protokolldatei verwaltet, die in geschrieben, aber nicht ausgelesen wird. Da die vorhandenen Dateidaten überschrieben und nicht gelesen werden, gibt der Cache-Manager möglicherweise Seiten mit Nullen zurück, anstatt die tatsächlichen Seiten der Dateidaten vom Datenträger zu beeinträchtigen. Wenn dieses Flag festgelegt ist, verfolgt der Cache-Manager modifiziert Seiten nicht nach. Der Aufrufer ist dafür verantwortlich, alle modifiziert Seiten nachzuverfolgen. Beachten Sie, dass CcPreparePinWrite nur verwendet werden sollte, um Daten auf diese Weise anzuheften, wenn der Puffer schließlich auf den Datenträger geleert wird. Bevor CcFlushCache aufgerufen wird, um den Puffer auf den Datenträger zu leeren, muss der Aufrufer zuerst MmSetAddressRangeModified aufrufen, um den Speicher-Manager zu benachrichtigen, dass die angegebenen Seiten im Systemcachepuffer modifiziert sind und geschrieben werden sollen.

Jeder erfolgreiche Aufruf von CcPreparePinWrite muss durch einen nachfolgenden Aufruf von CcUnpinData abgeglichen werden. Wenn CcPreparePinWrite für die gleichen Daten mehrmals aufgerufen wird, muss CcUnpinData genauso oft aufgerufen 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).

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

Es ist nicht erforderlich, CcSetDirtyPinnedData nach dem Aufruf von CcPreparePinWrite aufzurufen. Wenn CcPreparePinWriteTRUE zurückgibt, ist der BCB bereits als modifiziert gekennzeichnet.

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