Funzione FsRtlCopyWrite (ntifs.h)

La routine FsRtlCopyWrite copia i dati da un buffer utente a un file memorizzato nella cache.

Sintassi

BOOLEAN FsRtlCopyWrite(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [in]  PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

Parametri

[in] FileObject

Puntatore a un oggetto file per il file memorizzato nella cache in cui scrivere i dati.

[in] FileOffset

Puntatore a una variabile che specifica l'offset di byte iniziale all'interno del file memorizzato nella cache.

[in] Length

Lunghezza in byte dei dati da scrivere.

[in] Wait

Impostare su TRUE se il chiamante può essere inserito in uno stato di attesa fino a quando tutti i dati non sono stati copiati, FALSE in caso contrario.

[in] LockKey

Valore associato all'intervallo di byte da bloccare. Se l'intervallo da bloccare si sovrappone a un altro intervallo già bloccato con un blocco non esclusivo oppure se l'intervallo da leggere è una sottorange di un altro intervallo già bloccato in modo non esclusivo, il valore in questo parametro deve essere la chiave per tale blocco non esclusive Il blocco deve essere mantenuto dal processo padre del thread chiamante. In caso contrario, questo parametro non ha alcun effetto.

[in] Buffer

Puntatore al buffer da cui copiare i dati.

[out] IoStatus

Puntatore a una struttura allocata dal chiamante che riceve lo stato di completamento finale e le informazioni sull'operazione. Se i dati vengono copiati correttamente, IoStatus.Status contiene STATUS_SUCCESS. Se non tutti i dati vengono copiati correttamente, IoStatus.Information contiene il numero effettivo di byte copiati.

[in] DeviceObject

Puntatore all'oggetto dispositivo per il volume montato che contiene i dati del file.

Valore restituito

FsRtlCopyWrite restituisce TRUE se la richiesta di copia è stata completata, FALSE in caso contrario. Si noti che un valore restituito di TRUE non significa necessariamente che l'operazione di copia sia riuscita.

Se FsRtlCopyWrite restituisce FALSE o se il contenuto di IoStatus indica che l'operazione di copia non è riuscita, il chiamante deve allocare un'IRP di scrittura anziché chiamare FsRtlCopyWrite.

Commenti

Anziché implementare una routine di scrittura di I/O specifica del file system, gli sviluppatori di file system che supportano la memorizzazione nella cache dei file devono considerare l'uso di FsRtlCopyWrite come punto di ingresso del file system per l'elaborazione di richieste di scrittura di I/O veloci. Ciò richiede che la routine DriverEntry del file system imposta il punto di ingresso FastIoWrite su FsRtlCopyWrite nella struttura FAST_IO_DISPATCH dell'oggetto driver del file system. Inoltre, il file system deve eseguire le operazioni seguenti:

1. Per ogni file in cui è possibile eseguire l'I/O veloce, il file system deve allocare e inizializzare una struttura FSRTL_COMMON_FCB_HEADER.

   Nella maggior parte dei file system, questa operazione viene eseguita includendo la struttura FSRTL_COMMON_FCB_HEADER in un blocco di controllo file (FCB) o una struttura paragonabile usata per mantenere lo stato di un file aperto.

   L'archiviazione per la struttura FSRTL_COMMON_FCB_HEADER viene in genere allocata dal pool di pagine.

2. Per ogni file in cui è possibile eseguire l'I/O veloce, il file system deve collegare tutti gli oggetti file per il file alla struttura FSRTL_COMMON_FCB_HEADER. Questa operazione viene eseguita impostando il membro FsContext di ogni oggetto file per puntare a questa struttura (o alla struttura FCB o ad altra struttura contenente la struttura di FSRTL_COMMON_FCB_HEADER).

3. Quando si memorizza nella cache un file, il file system deve impostare il membro IsFastIoPossible della struttura FSRTL_COMMON_FCB_HEADER del file su un valore appropriato. Questo valore deve essere aggiornato in base alle esigenze finché il file rimane memorizzato nella cache.

   In particolare, i file system devono impostare il membro IsFastIoPossible della struttura FSRTL_COMMON_FCB_HEADER su FastIoIsQuestionable non appena esiste un blocco dell'intervallo di byte esclusivo nel file memorizzato nella cache.

Se Wait è TRUE, FsRtlCopyWrite è garantito copiare i dati e restituire TRUE. Se le pagine necessarie del file memorizzato nella cache sono già residenti in memoria, i dati verranno copiati immediatamente e non si verificherà alcun blocco. Se le pagine necessarie non sono residenti, il chiamante verrà inserito in uno stato di attesa fino a quando tutte le pagine necessarie non sono state effettuate e i dati possono essere copiati.

Se Wait è FALSE, FsRtlCopyWrite rifiuterà di bloccare e restituirà FALSE, se non è in grado di acquisire la risorsa principale del file o se le pagine necessarie del file memorizzato nella cache non sono già residenti in memoria.

La routine FastIoCheckIfPossible del file system è responsabile della garanzia che l'intervallo di byte definito da FileOffset e Length non includa alcun intervallo di byte bloccato esclusivamente per il quale il chiamante non passa il valore LockKey appropriato. Se il file system usa le routine di supporto di FsRtlXxxLockYyy per gestire i blocchi di intervallo di byte, questa operazione può essere eseguita chiamando FsRtlFastCheckLockForWrite dalla routine FastIoCheckIfPossible prima di chiamare FsRtlCopyRead.

Per memorizzare nella cache un file, usare la routine CcInitializeCacheMap .

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Vedi anche

CcInitializeCacheMap

FsRtlCopyRead

FsRtlFastCheckLockForWrite