Funzione CcPinRead (ntifs.h)

Articolo
12/20/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 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.

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

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

Osservazioni

Se il flag di PIN_WAIT è impostato, CcPinRead è garantito di 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 messo in uno stato di attesa fino a quando tutte le pagine richieste non sono state rese residenti e i dati possono essere aggiunti. Se il flag di PIN_WAIT non è impostato, ma i dati non possono essere aggiunti immediatamente, CcPinRead restituisce FALSEe i relativi valori dei parametri di output non sono significativi.

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 corrispondere a una chiamata successiva a CcUnpinData.

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

CcPinRead 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, CcPinRead genera un'eccezione di stato per quel particolare errore. 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, utilizzare la routine CcMapData. Per memorizzare nella cache un file, usare CcInitializeCacheMap.