Funzione CcPinRead (ntifs.h)

Articolo
02/26/2024

La routine CcPinRead aggiunge l'intervallo di byte specificato di un file memorizzato nella cache e legge i dati aggiunti in un buffer in memoria.

Sintassi

BOOLEAN CcPinRead(
  [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 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 dei dati desiderati in byte.

[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:

Valore	Significato
PIN_WAIT	Il chiamante può essere inserito in uno stato di attesa fino a quando non sono stati aggiunti i dati.
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.

[out] Bcb

Nella prima chiamata viene restituito un puntatore a un blocco di controllo buffer (BCB). Questo puntatore deve essere fornito come input per tutte le chiamate successive per questo buffer.

[out] Buffer

Puntatore a un buffer contenente i dati aggiunti.

Valore restituito

CcPinRead restituisce TRUE se i dati per il file memorizzato nella cache sono stati aggiunti e letti correttamente, FALSE in caso contrario.

Commenti

Se il flag di PIN_WAIT è impostato, CcPinRead è garantito completare la richiesta di aggiunta e restituire TRUE. Se le pagine necessarie del file memorizzato nella cache sono già residenti in memoria, i dati vengono aggiunti immediatamente e non si verifica alcun blocco. Se le pagine necessarie non sono residenti, il chiamante viene inserito in uno stato di attesa fino a quando non sono state aggiunte tutte le pagine necessarie e i dati possono essere aggiunti. Se il flag PIN_WAIT non è impostato, ma i dati non possono essere aggiunti immediatamente, CcPinRead restituisce FALSE e i relativi valori dei parametri di output sono senza significato.

Se il chiamante modifica successivamente i dati letti da CcPinRead, deve anche chiamare CcSetDirtyPinnedData in modo che i dati modificati vengano scritti su disco.

Ogni chiamata riuscita a CcPinRead deve essere corrispondente a una chiamata successiva a CcUnpinData.

Il puntatore restituito nel buffer è valido finché 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 alla chiamata a CcUnpinData ).

CcPinRead non può aggiungere dati tra i limiti di visualizzazione nella gestione cache. La gestione cache gestisce i file nel sistema in 256 visualizzazioni allineate a KB. Le dimensioni della visualizzazione della gestione cache vengono specificate dalla costante definita dal sistema VACB_MAPPING_GRANULARITY, impostato 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 è 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 in memoria. Purché le pagine vengano aggiunte, l'intervallo di byte è garantito rimanere mappato nello spazio indirizzi virtuale della cache di sistema, ma la gestione memoria può visualizzare le pagine fisiche in quanto richiede la richiesta di memoria del sistema.

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

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