CcMapData-Funktion (ntifs.h)

Artikel
12/21/2024

Die CcMapData Routine ordnet einen angegebenen Bytebereich einer zwischengespeicherten Datei einem Puffer im Arbeitsspeicher zu.

Syntax

BOOLEAN CcMapData(
  [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 Datei, deren Daten für den Lesezugriff zugeordnet werden sollen.

[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 angibt, wie der Zuordnungsvorgang ausgeführt werden soll. Dies ist eine bitweise OR-Kombination aus einem oder mehreren der folgenden Werte:

Wert	Bedeutung
MAP_WAIT	Der Aufrufer kann in einen Wartezustand versetzt werden, bis die Daten zugeordnet wurden.
MAP_NO_READ	Es werden nur Seiten zugeordnet, die bereits im Arbeitsspeicher vorhanden sind.

Hinweis In Windows 2000und früher war dieser Parameter ein BOOLESCHER Wert mit dem Namen Wait:

Warte

Legen Sie auf TRUE fest, wenn der Aufrufer in einen Wartezustand versetzt werden kann, bis die Daten zugeordnet wurden, FALSE andernfalls.

[out] Bcb

Beim ersten Aufruf wird ein Zeiger auf eine BCB-Struktur (Buffer Control Block) 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 zugeordneten Daten enthält.

Rückgabewert

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

Bemerkungen

CcMapData- ordnet Daten in einer zwischengespeicherten Datei für den Lesezugriff zu. Beachten Sie, dass nach dem Aufruf CcMapData- die Daten zugeordnet werden; aber nicht angeheftet. Diese Unterscheidung ist wichtig. Daten, die zugeordnet, aber nicht angeheftet sind, können nicht sicher geändert werden. Um die Daten anzuheften, verwenden Sie CcPinMappedData-, CcPinRead-oder CcPreparePinWrite.

Jeder erfolgreiche Aufruf von CcMapData- muss mit einem nachfolgenden Aufruf von CcUnpinDataabgeglichen werden.

CcMapData- daten im Cache-Manager nicht über Ansichtsgrenzen hinweg zuordnen 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.) Zugeordnete Bereiche können nicht mehr als eine 256 KB-Ansicht umfassen. Daher beträgt der größte Bereich, der zugeordnet werden kann, 256 KB, beginnend mit einem 256 KB ausgerichteten Offset in der Datei.

Durch die Zuordnung eines Bytebereichs in einer zwischengespeicherten Datei wird nicht sichergestellt, dass die Seiten im Arbeitsspeicher verbleiben. Solange die Seiten zugeordnet sind, bleibt der Bytebereich garantiert dem virtuellen Adressraum des Systemcaches zugeordnet, aber der Speicher-Manager kann die physischen Seiten aussortieren, da die Speichernachfrage des Systems erforderlich ist.

Wenn das MAP_WAIT Flag festgelegt ist (oder WaitTRUEist), ist CcMapData- garantiert, die Zuordnungsanforderung abzuschließen und TRUE-zurückzugeben. Wenn die erforderlichen Seiten der zwischengespeicherten Datei bereits im Arbeitsspeicher vorhanden sind, werden die Daten sofort zugeordnet, 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 zugeordnet werden können. Wenn das MAP_WAIT Flag nicht festgelegt ist (oder WaitFALSEist) und die Daten nicht sofort zugeordnet werden können, gibt CcMapData-FALSE-zurück.

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

Wenn ein Fehler auftritt, löst CcMapData eine Status ausnahme für diesen bestimmten Fehler aus. Wenn beispielsweise ein Poolzuordnungsfehler auftritt, löst CcMapData- eine STATUS_INSUFFICIENT_RESOURCES Ausnahme aus; wenn ein E/A-Fehler auftritt, löst CcMapData die Status ausnahme des E/A-Fehlers aus. Um die Kontrolle zu erlangen, wenn ein Fehler auftritt, sollte der Treiber den Aufruf von CcMapData- in einem try-except oder try-finally Anweisung umschließen.

Verwenden Sie CcInitializeCacheMap, um eine Datei zwischenzuspeichern.