Funzione CcPreparePinWrite (ntifs.h)

Articolo
12/21/2024

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

[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.
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 non viene restituito alcun 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 bloccato (BCB). Questo puntatore deve essere fornito come input per qualsiasi chiamata successiva a CcPreparePinWrite o CcUnpinData per questo buffer.

[out] Buffer

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

Valore restituito

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

Osservazioni

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

Se il flag PIN_WAIT è impostato, CcPreparePinWrite viene 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 messo 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 restituisce FALSEe 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 ma non letto da. Poiché i dati dei file esistenti verranno sovrascritti e non letti, la gestione cache può restituire pagine di zeri invece di generare errori nelle pagine effettive dei dati dei file dal disco. Se questo flag è impostato, gestione cache non tiene traccia delle pagine dirty. Il chiamante è responsabile di tenere traccia di eventuali pagine sporche. Si noti che CcPreparePinWrite deve essere usato solo per aggiungere i 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 al gestore della memoria che le pagine specificate nel buffer della cache di sistema sono dirty e devono essere scritte.

Ogni chiamata riuscita a CcPreparePinWrite deve corrispondere 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 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).

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

Non è necessario chiamare CcSetDirtyPinnedData dopo aver chiamato CcPreparePinWrite. Se CcPreparePinWrite restituisce TRUE, il BCB è già contrassegnato come dirty.

Se si verifica un errore, CcPreparePinWrite genera un'eccezione di stato per quel particolare errore. 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.