Funzione CcPreparePinWrite (ntifs.h)

Articolo
08/07/2023

La routine CcPreparePinWrite aggiunge l'intervallo di byte specificato di un file memorizzato nella cache per l'accesso in scrittura.

Sintassi

BOOLEAN CcPreparePinWrite(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  BOOLEAN        Zero,
  [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 devono essere scritti i dati.

[in] FileOffset

Puntatore a una variabile che specifica l'offset di byte iniziale all'interno del file in cui devono essere scritti i dati.

[in] Length

Lunghezza dei dati desiderati in byte.

[in] Zero

Impostare su TRUE se il buffer deve essere zero al ritorno. Questo parametro viene ignorato se il flag di PIN_CALLER_TRACKS_DIRTY_DATA è impostato nel parametro Flags .

[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.
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 non riesce e non viene restituito bcB.
PIN_CALLER_TRACKS_DIRTY_DATA	Il chiamante è responsabile di tenere traccia delle pagine sporche. Se questo flag è impostato, tutti gli altri flag vengono ignorati. Questo flag è disponibile in Microsoft Windows Server 2003 SP1 e versioni successive.

[out] Bcb

Puntatore opaco a un blocco di controllo buffer aggiunto (BCB). Questo puntatore deve essere fornito come input per tutte le chiamate successive a CcPreparePinWrite o CcUnpinData per questo buffer.

[out] Buffer

Restituisce il puntatore ai dati desiderati, validi fino a quando il buffer non viene rimosso o liberato.

Valore restituito

CcPreparePinWrite restituisceTRUE se il file memorizzato nella cache è stato aggiunto correttamente, FALSE in caso contrario.

Commenti

CcPreparePinWrite aggiunge le pagine di file specificate nella cache di sistema. Le pagine da sovrascrivere completamente possono essere soddisfatte con pagine di zero.

Se il flag di PIN_WAIT è impostato, CcPreparePinWrite è garantito di completare la richiesta di preparazione e restituire TRUE. Se tutte le pagine possono essere preparate immediatamente, non si verifica alcun blocco. Se le pagine necessarie non sono residenti, il chiamante viene inserito in uno stato di attesa fino a quando tutte le pagine necessarie non sono state rese residenti e le pagine possono essere preparate. Se il flag di PIN_WAIT non è impostato, ma non tutte le pagine possono essere preparate immediatamente, CcPreparePinWrite restituisceFALSE e i relativi valori dei parametri di output sono senza significato.

Microsoft Windows Server 2003 SP1 e versioni successive: Il flag PIN_CALLER_TRACKS_DIRTY_DATA viene comunemente usato nei casi in cui un file system gestisce un file di log scritto in ma non letto da. Poiché i dati dei file esistenti verranno sovrascritti e non letti, la gestione cache potrebbe restituire pagine di zero anziché errori nelle pagine effettive dei dati dei file dal disco. Se questo flag è impostato, la gestione cache non tiene traccia delle pagine sporche. Il chiamante è responsabile di tenere traccia di tutte le pagine sporche. Si noti che CcPreparePinWrite deve essere usato solo per aggiungere dati in questo modo se il buffer verrà scaricato su disco. Prima di chiamare CcFlushCache per scaricare il buffer su disco, il chiamante deve prima chiamare MmSetAddressRangeModified per notificare alla gestione memoria che le pagine specificate nel buffer della cache di sistema sono sporche e devono essere scritte.

Ogni chiamata riuscita a CcPreparePinWrite deve essere corrispondente a una chiamata successiva a CcUnpinData. Se CcPreparePinWrite viene chiamato più volte per gli stessi dati, CcUnpinData deve essere chiamato lo stesso numero di volte.

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

CcPreparePinWrite non può aggiungere dati tra 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.

Non è necessario chiamare CcSetDirtyPinnedData dopo aver chiamato CcPreparePinWrite. Se CcPreparePinWrite restituisceTRUE, bcB è già contrassegnato come sporco.

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