Funzione CcPinMappedData (ntifs.h)

Articolo
12/21/2024

La routine CcPinMappedData aggiunge l'intervallo di byte specificato di un file memorizzato nella cache.

Sintassi

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

Parametri

[in] FileObject

Puntatore a un oggetto file per il file memorizzato nella cache in cui deve essere aggiunto un intervallo di dati.

[in] FileOffset

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

[in] Length

Lunghezza in byte dei dati da aggiungere.

[in] Flags

Maschera di bit dei flag che specificano la modalità di esecuzione dell'operazione di aggiunta. Combinazione ORed di uno o più dei valori seguenti:

Bandiera	Significato
PIN_WAIT	Il chiamante può essere inserito in uno stato di attesa fino a quando i dati non sono stati aggiunti.
PIN_EXCLUSIVE	Il blocco di controllo buffer (BCB) deve essere acquisito esclusivamente. Se questo flag è impostato, è necessario impostare anche PIN_WAIT.
PIN_NO_READ	Solo le pagine già residenti in memoria devono essere aggiunte. Se questo flag è impostato, è necessario impostare anche PIN_WAIT.
PIN_IF_BCB	I dati devono essere aggiunti solo se esiste già un BCB. In caso contrario, il pin ha esito negativo e Bcb è impostato su NULL.

[in, out] Bcb

Nella prima chiamata viene restituito un puntatore a un blocco di controllo buffer .BCB.On the first call this returns a pointer to a buffer control block (BCB). Questo puntatore deve essere fornito come input per tutte le chiamate successive per questo buffer.

Valore restituito

CcPinMappedData restituisce true se i dati per il file memorizzato nella cache sono stati aggiunti correttamente, false in caso contrario.

Osservazioni

Una restituzione riuscita da CcPinMappedData garantisce che i dati mappati in precedenza in una chiamata a CcMapData vengono aggiunti nella cache e i dati nell'intervallo specificato possono essere modificati in modo sicuro. Se il chiamante modifica successivamente i dati aggiunti da CcPinMappedData, deve anche chiamare CcSetDirtyPinnedData in modo che i dati modificati vengano scritti su disco.

CcPinMappedData non è possibile aggiungere dati oltre i limiti di visualizzazione nella gestione cache. Gestione cache gestisce i file nel sistema in visualizzazioni allineate a 256 KB. Le dimensioni della visualizzazione di Gestione cache vengono specificate dalla costante definita dal sistema VACB_MAPPING_GRANULARITY, che è impostata su 256 KB in ntifs.h.) Le aree aggiunte non possono estendersi su più di una visualizzazione di 256 KB. Pertanto, l'area più grande che può essere aggiunta è di 256 KB, a partire da un offset allineato a 256 KB nel file.

L'aggiunta di un intervallo di byte in un file memorizzato nella cache non garantisce che le pagine rimangano residenti in memoria. Finché le pagine vengono aggiunte, l'intervallo di byte rimane mappato allo spazio indirizzi virtuale della cache di sistema, ma il gestore della memoria può eseguire la pagina delle pagine fisiche in base alle esigenze della richiesta di memoria del sistema.

Se si verifica un errore, CcPinMappedData genera un'eccezione di stato per quel particolare errore. Ad esempio, se si verifica un errore di allocazione del pool, CcPinMappedData genera un'eccezione STATUS_INSUFFICIENT_RESOURCES; se si verifica un errore di I/O, CcPinMappedData 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 CcPinMappedData in un 'istruzione try-except o try-finally.

Per eseguire il mapping dei dati per un file memorizzato nella cache, utilizzare la routine CcMapData. Per memorizzare nella cache un file, usare CcInitializeCacheMap.

Non è necessario chiamare CcUnpinData dopo aver chiamato CcPinMappedData poiché il riferimento pin viene confrontato con CcMapData.