CcPreparePinWrite-Funktion (ntifs.h)

Die CcPreparePinWrite Routine pins the specified byte range of a cached file for write access.

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

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

[in] FileOffset

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

[in] Length

Länge der gewünschten Daten in Bytes.

[in] Zero

Wird auf TRUE- festgelegt, wenn der Puffer beim Zurückgeben null sein soll. Dieser Parameter wird ignoriert, wenn das PIN_CALLER_TRACKS_DIRTY_DATA Flag im Flags Parameter festgelegt ist.

[in] Flags

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

[out] Bcb

Undurchsichtiger Zeiger auf einen angehefteten Puffersteuerelementblock (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 wird.

Rückgabewert

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

Bemerkungen

CcPreparePinWrite die angegebenen Dateiseiten im Systemcache anheftet. Seiten, die vollständig überschrieben werden, sind möglicherweise mit Seiten von Nullen zufrieden.

Wenn das PIN_WAIT Flag festgelegt ist, ist CcPreparePinWrite garantiert, die Vorbereitungsanforderung abzuschließen und TRUEzurückzugeben. Wenn alle Seiten sofort vorbereitet werden können, 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 Seiten vorbereitet werden können. Wenn das PIN_WAIT Flag nicht festgelegt ist, aber nicht alle Seiten sofort vorbereitet werden können, gibt CcPreparePinWriteFALSEzurück, und die Ausgabeparameterwerte sind bedeutungslos.

Microsoft Windows Server 2003 SP1 und höher: Das kennzeichen PIN_CALLER_TRACKS_DIRTY_DATA wird häufig verwendet, wenn ein Dateisystem eine Protokolldatei verwaltet, in die geschrieben, aber nicht gelesen wird. Da die vorhandenen Dateidaten überschrieben und nicht gelesen werden, gibt der Cache-Manager möglicherweise Seiten von Nullen zurück, anstatt auf den tatsächlichen Seiten von Dateidaten vom Datenträger zu fehlern. Wenn dieses Kennzeichen festgelegt ist, verfolgt der Cache-Manager keine schmutzigen Seiten. Der Anrufer ist dafür verantwortlich, alle schmutzigen 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 Sie CcFlushCache- aufrufen, 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 schmutzig sind und geschrieben werden sollen.

Jeder erfolgreiche Aufruf von CcPreparePinWrite- muss durch einen nachfolgenden Aufruf von CcUnpinData-abgeglichen werden. Wenn CcPreparePinWrite- mehrmals für dieselben Daten aufgerufen wird, muss CcUnpinData- dieselbe Anzahl von Malen 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 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_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.

Es ist nicht erforderlich, CcSetDirtyPinnedData- nach dem Aufrufen von CcPreparePinWriteaufzurufen. Wenn CcPreparePinWriteTRUE-zurückgibt, wird der BCB bereits als geändert markiert.

Wenn ein Fehler auftritt, löst CcPreparePinWrite eine Status ausnahme für diesen bestimmten Fehler aus. Wenn beispielsweise ein Poolzuweisungsfehler 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. Um die Kontrolle zu erlangen, wenn ein Fehler auftritt, sollte der Treiber den Aufruf von CcPreparePinWrite in einem try-except oder try-finally Anweisung umschließen.

Anforderungen

Siehe auch

CcFlushCache-

CcMapData-

CcPinMappedData-

CcPinRead-

CcSetDirtyPinnedData-

CcUnpinData-

MmSetAddressRangeModified