Funzione CcMapData (ntifs.h)

Articolo
08/07/2023

La routine CcMapData esegue il mapping di un intervallo di byte specificato di un file memorizzato nella cache a un buffer in memoria.

Sintassi

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

Parametri

[in] FileObject

Puntatore a un oggetto file per il file di cui eseguire il mapping dei dati per l'accesso in lettura.

[in] FileOffset

Puntatore a una variabile che specifica l'offset dei byte iniziale all'interno del file memorizzato nella cache in cui risiedono i dati desiderati.

[in] Length

Lunghezza dei dati desiderati in byte.

[in] Flags

Maschera di bit dei flag che specificano la modalità di esecuzione dell'operazione di mapping. Si tratta di una combinazione OR bit per bit di uno o più dei valori seguenti:

Valore	Significato
MAP_WAIT	Il chiamante può essere inserito in uno stato di attesa fino a quando non viene eseguito il mapping dei dati.
MAP_NO_READ	Verranno mappate solo le pagine già residenti in memoria.

Nota In Windows 2000 e versioni precedenti, questo parametro era un valore BOOLEAN denominato Wait:

Attesa

Impostare su TRUE se il chiamante può essere inserito in uno stato di attesa fino a quando non viene eseguito il mapping dei dati, FALSE in caso contrario.

[out] Bcb

Nella prima chiamata viene restituito un puntatore a una struttura BCB (Buffer Control Block). Questo puntatore deve essere fornito come input per tutte le chiamate successive, per questo buffer.

[out] Buffer

Puntatore a un buffer contenente i dati mappati.

Valore restituito

CcMapData restituisce TRUE se i dati per il file memorizzato nella cache sono stati mappati correttamente, FALSE in caso contrario.

Commenti

CcMapData esegue il mapping dei dati in un file memorizzato nella cache per l'accesso in lettura. Si noti che dopo la chiamata a CcMapData , i dati vengono mappati; ma non è bloccato. Questa distinzione è importante. I dati mappati ma non aggiunti non possono essere modificati in modo sicuro. Per aggiungere i dati, usare CcPinMappedData, CcPinRead o CcPreparePinWrite.

Ogni chiamata a CcMapData deve corrispondere a una chiamata successiva a CcUnpinData.

CcMapData non può eseguire il mapping dei dati tra i limiti di visualizzazione nella gestione cache. Gestione cache gestisce i file nel sistema in visualizzazioni allineate a 256 KB. Le dimensioni di visualizzazione di Gestione cache vengono specificate dalla costante definita dal sistema VACB_MAPPING_GRANULARITY, che è impostata su 256 KB in ntifs.h. Le aree mappate non possono estendersi su più di una visualizzazione di 256 KB. Di conseguenza, l'area più grande di cui è possibile eseguire il mapping è 256 KB, a partire da un offset allineato a 256 KB nel file.

Il mapping di un intervallo di byte in un file memorizzato nella cache non garantisce che le pagine rimangano in memoria. Purché le pagine siano mappate, l'intervallo di byte rimane mappato nello spazio indirizzi virtuale della cache di sistema, ma gestione memoria può eseguire la pagina delle pagine fisiche in base alle esigenze della richiesta di memoria del sistema.

Se il flag MAP_WAIT è impostato (o Wait è TRUE), CcMapData viene garantito di completare la richiesta di mapping e restituire TRUE. Se le pagine necessarie del file memorizzato nella cache sono già residenti in memoria, i dati vengono mappati immediatamente e non si verificherà alcun blocco. Se le pagine necessarie non sono residenti, il chiamante viene messo in uno stato di attesa fino a quando tutte le pagine necessarie non sono state rese residenti e i dati possono essere mappati. Se il flag MAP_WAIT non è impostato (o Wait è FALSE) e i dati non possono essere mappati immediatamente, CcMapData restituisce FALSE.

Il puntatore restituito in Buffer è valido fino a quando non viene chiamato CcUnpinData . Se CcPinMappedData viene chiamato mentre questo puntatore è ancora valido, il puntatore rimane valido dopo la chiamata a CcPinMappedData (ma solo fino a quando non viene chiamato CcUnpinData ).

Se si verifica un errore, CcMapData genera un'eccezione di stato per quel particolare errore. Ad esempio, se si verifica un errore di allocazione del pool, CcMapData genera un'eccezione STATUS_INSUFFICIENT_RESOURCES ; se si verifica un errore di I/O, CcMapData genera l'eccezione di stato dell'errore di I/O. Pertanto, per ottenere il controllo se si verifica un errore, il driver deve eseguire il wrapping della chiamata a CcMapData in un'istruzione try-except o try-finally .

Per memorizzare nella cache un file, usare CcInitializeCacheMap.