Funzione FsRtlCopyRead (ntifs.h)
Il FsRtlCopyRead copia i dati da un file memorizzato nella cache in un buffer utente.
Sintassi
BOOLEAN FsRtlCopyRead(
[in] PFILE_OBJECT FileObject,
[in] PLARGE_INTEGER FileOffset,
[in] ULONG Length,
[in] BOOLEAN Wait,
[in] ULONG LockKey,
[out] 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 da cui devono essere letti i dati.
[in] FileOffset
Offset di byte iniziale all'interno del file memorizzato nella cache.
[in] Length
Lunghezza in byte dei dati da leggere.
[in] Wait
Impostare su TRUE se il chiamante può essere inserito in uno stato di attesa fino a quando non vengono copiati tutti i dati, 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 o se l'intervallo da leggere è un intervallo secondario di un altro intervallo già bloccato in modo non esclusivo, il valore in questo parametro deve essere la chiave per tale blocco non esclusivo Il blocco deve essere mantenuto dal processo padre del thread chiamante. In caso contrario, questo parametro non ha alcun effetto.
[out] Buffer
Puntatore a un buffer in cui copiare i dati.
[out] IoStatus
Puntatore a una struttura allocata dal chiamante che riceve lo stato di completamento finale e 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
Oggetto dispositivo per il dispositivo che contiene i dati del file.
Valore restituito
FsRtlCopyRead restituisce TRUE se la richiesta di copia è stata completata, false in caso contrario. Si noti che un valore restituito true non significa necessariamente che l'operazione di copia sia riuscita.
Se FsRtlCopyRead restituisce FALSE o se il contenuto di IoStatus indicare che l'operazione di copia non è riuscita, il chiamante deve allocare un IRP di lettura anziché chiamare FsRtlCopyRead.
Osservazioni
Invece di implementare una routine di lettura di I/O veloce specifica del file system, gli sviluppatori di file system che supportano la memorizzazione nella cache dei file devono prendere in considerazione l'uso di FsRtlCopyRead come punto di ingresso del file system per l'elaborazione di richieste di lettura di I/O veloci. Ciò richiede che la routine DriverEntry del file system imposti il punto di ingresso FastIoRead su FsRtlCopyRead nella struttura FAST_IO_DISPATCH dell'oggetto driver del file system. Inoltre, il file system deve eseguire le operazioni seguenti:
Per ogni file in cui è possibile eseguire operazioni di I/O veloci, 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 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 paging.
Per ogni file in cui è possibile eseguire operazioni di I/O veloci, 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 in modo che punti a questa struttura (o fcb o altra struttura che contiene la struttura FSRTL_COMMON_FCB_HEADER).
Quando si memorizza nella cache un file, il file system deve impostare il IsFastIoPossible membro della struttura FSRTL_COMMON_FCB_HEADER del file su un valore appropriato. Questo valore deve essere aggiornato in base alle esigenze, purché il file rimanga memorizzato nella cache.
In particolare, i file system devono impostare il IsFastIoPossible membro della struttura FSRTL_COMMON_FCB_HEADER su FastIoIsQuestionable non appena esiste un blocco esclusivo di intervalli di byte nel file memorizzato nella cache.
Se Wait è TRUE, FsRtlCopyRead è garantito di completare la richiesta di copia e restituire TRUE. Se le pagine richieste 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à messo in uno stato di attesa fino a quando tutte le pagine richieste non sono state rese residenti e i dati possono essere copiati.
Se Wait è FALSE, FsRtlCopyRead rifiuterà di bloccare e restituirà FALSE, se non è possibile acquisire la risorsa principale del file o se le pagine richieste del file memorizzato nella cache non sono già residenti in memoria.
La routine FastIoCheckIfPossible del file system è responsabile di garantire 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 FsRtlXxxBloccoYyy per gestire i blocchi di intervallo di byte, è possibile chiamare FsRtlFastCheckLockForRead dalla routine FastIoCheckIfPossible prima di chiamare FsRtlCopyRead.
Per memorizzare nella cache un file, utilizzare la routine CcInitializeCacheMap.
Fabbisogno
| 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 | PowerIrpDDis(wdm) |