struttura FILE_OBJECT (wdm.h)
La struttura FILE_OBJECT viene utilizzata dal sistema per rappresentare un oggetto file. Per i sottosistemi protetti in modalità utente, un oggetto file rappresenta un'istanza aperta di un file, un dispositivo, una directory o un volume. Per dispositivi e driver intermedi, un oggetto file rappresenta in genere un oggetto dispositivo. Per i driver nello stack del file system, un oggetto file rappresenta in genere una directory o un file.
Un oggetto file è parzialmente opaco. Alcuni tipi di driver, ad esempio driver di file system e driver di trasporto di rete, usano alcuni dei campi degli oggetti file.
Sintassi
typedef struct _FILE_OBJECT {
CSHORT Type;
CSHORT Size;
PDEVICE_OBJECT DeviceObject;
PVPB Vpb;
PVOID FsContext;
PVOID FsContext2;
PSECTION_OBJECT_POINTERS SectionObjectPointer;
PVOID PrivateCacheMap;
NTSTATUS FinalStatus;
struct _FILE_OBJECT *RelatedFileObject;
BOOLEAN LockOperation;
BOOLEAN DeletePending;
BOOLEAN ReadAccess;
BOOLEAN WriteAccess;
BOOLEAN DeleteAccess;
BOOLEAN SharedRead;
BOOLEAN SharedWrite;
BOOLEAN SharedDelete;
ULONG Flags;
UNICODE_STRING FileName;
LARGE_INTEGER CurrentByteOffset;
__volatile ULONG Waiters;
__volatile ULONG Busy;
PVOID LastLock;
KEVENT Lock;
KEVENT Event;
__volatile PIO_COMPLETION_CONTEXT CompletionContext;
KSPIN_LOCK IrpListLock;
LIST_ENTRY IrpList;
__volatile _IOP_FILE_OBJECT_EXTENSION *FileObjectExtension;
struct _IOP_FILE_OBJECT_EXTENSION;
} FILE_OBJECT, *PFILE_OBJECT;
Membri
Type
Membro di sola lettura utilizzato dal sistema per indicare che l'oggetto è un oggetto file. Se l'oggetto è un oggetto file, il valore di questo membro è 5.
Size
Membro di sola lettura che specifica le dimensioni, in byte, dell'oggetto file. Questa dimensione non include l'estensione dell'oggetto file, se presente.
DeviceObject
Puntatore all'oggetto dispositivo in cui viene aperto il file.
Vpb
Puntatore al blocco di parametri del volume associato all'oggetto file.
Si noti che se il membro Vpb non èNULL, il file si trova in un volume montato.
FsContext
Puntatore a qualsiasi stato facoltativo gestito da un driver sull'oggetto file; in caso contrario, null. Per i driver del file system, questo membro deve puntare a una struttura di intestazione FSRTL_ADVANCED_FCB_HEADER contenuta all'interno di una struttura specifica del file system; in caso contrario, l'instabilità del sistema può comportare. In genere, questa struttura di intestazione è incorporata in un blocco di controllo file (FCB). Tuttavia, in alcuni file system che supportano più flussi di dati, ad esempio NTFS, questa struttura di intestazione è un blocco di controllo di flusso (SCB).
In uno stack di dispositivi WDM, solo l'oggetto dispositivo funzionale (FDO) può usare i due puntatori di contesto. I driver del file system condividono questo membro in più si apre allo stesso flusso di dati.
FsContext2
Puntatore a qualsiasi stato aggiuntivo gestito da un driver sull'oggetto file; in caso contrario, null.
Questo membro è opaco per i driver nello stack del file system perché il file system sottostante utilizza questo membro.
SectionObjectPointer
Puntatore all'oggetto sezione di sola lettura dell'oggetto file. Questo membro viene impostato solo dai file system e usato per l'interazione con Gestione cache.
PrivateCacheMap
Membro opaco, impostato solo dai file system, che punta a gestire informazioni specifiche e che viene usato per l'interazione di Gestione cache.
FinalStatus
Membro di sola lettura utilizzato, in alcuni casi sincroni, per indicare lo stato finale della richiesta di I/O dell'oggetto file.
RelatedFileObject
Puntatore a una struttura di FILE_OBJECT utilizzata per indicare che l'oggetto file corrente è stato aperto rispetto a un oggetto file già aperto. L'oggetto file a cui punta questo membro è in genere una directory ( ovvero il file corrente è stato aperto rispetto a questa directory). Tuttavia, un file può essere riaperto rispetto a se stesso e i flussi di dati alternativi per un file possono essere aperti rispetto a un flusso di dati primario già aperto per lo stesso file. Il membro RelatedFileObject è valido solo durante l'elaborazione delle richieste di IRP_MJ_CREATE.
LockOperation
Membro di sola lettura. Se FALSE, un'operazione di blocco (NtLockFile) non è mai stata eseguita sull'oggetto file. Se TRUE, è stata eseguita almeno un'operazione di blocco sull'oggetto file. Dopo aver impostato su TRUE, questo membro rimane sempre TRUE( ad esempio, il rilascio dei blocchi di file nell'oggetto file non reimposta questo membro su FALSE).
DeletePending
Membro di sola lettura. Se TRUE, esiste un'operazione di eliminazione per il file associato all'oggetto file. Se FALSE, non è attualmente presente alcuna operazione di eliminazione in sospeso per l'oggetto file.
ReadAccess
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per l'accesso in lettura. Se FALSE, il file è stato aperto senza accesso in lettura. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso alla condivisione del file.
WriteAccess
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per l'accesso in scrittura. Se FALSE, il file è stato aperto senza accesso in scrittura. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso alla condivisione del file.
DeleteAccess
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per l'accesso all'eliminazione. Se FALSE, il file è stato aperto senza eliminare l'accesso. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso alla condivisione del file.
SharedRead
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per l'accesso in lettura alla condivisione. Se FALSE, il file è stato aperto senza accesso in lettura. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso alla condivisione del file.
SharedWrite
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per l'accesso alla condivisione di scrittura. Se FALSE, il file è stato aperto senza accesso alla condivisione di scrittura. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso alla condivisione del file.
SharedDelete
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per eliminare l'accesso alla condivisione. Se FALSE, il file è stato aperto senza eliminare l'accesso alla condivisione. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso alla condivisione del file.
Flags
Membro di sola lettura utilizzato dal sistema per contenere uno o più (combinazione OR inclusiva bit per bit) dei seguenti valori di flag privato.
| Bandiera | Significato |
|---|---|
| FO_FILE_OPEN | Deprecato. |
| FO_SYNCHRONOUS_IO | L'oggetto file viene aperto per le operazioni di I/O sincrone. |
| FO_ALERTABLE_IO | Qualsiasi attesa nel gestore di I/O, in seguito a una richiesta effettuata a questo oggetto file, è avvisabile. |
| FO_NO_INTERMEDIATE_BUFFERING | Il file associato all'oggetto file non può essere memorizzato nella cache o memorizzato nel buffer interno di un driver. |
| FO_WRITE_THROUGH | I servizi di sistema, i driver del file system e i driver che scrivono dati nel file devono trasferire i dati nel file prima che qualsiasi operazione di scrittura richiesta venga considerata completa. |
| FO_SEQUENTIAL_ONLY | Il file associato all'oggetto file è stato aperto solo per operazioni di I/O sequenziali. |
| FO_CACHE_SUPPORTED | Il file associato all'oggetto file è memorizzabile nella cache. Questo flag deve essere impostato solo da un driver del file system e solo se il membro FsContext punta a una struttura di FSRTL_ADVANCED_FCB_HEADER valida. |
| FO_NAMED_PIPE | L'oggetto file rappresenta una named pipe. |
| FO_STREAM_FILE | L'oggetto file rappresenta un flusso di file. |
| FO_MAILSLOT | L'oggetto file rappresenta un oggetto mailslot. |
| FO_GENERATE_AUDIT_ON_CLOSE | Deprecato. |
| FO_QUEUE_IRP_TO_THREAD | I runtime di integrazione non verranno accodati a questo oggetto file. |
| FO_DIRECT_DEVICE_OPEN | Il dispositivo di destinazione di questo oggetto file è stato aperto direttamente. |
| FO_FILE_MODIFIED | Il file associato all'oggetto file è stato modificato. |
| FO_FILE_SIZE_CHANGED | Il file associato all'oggetto file è cambiato in dimensioni. |
| FO_CLEANUP_COMPLETE | Il file system ha completato la pulizia per questo oggetto file. |
| FO_TEMPORARY_FILE | Il file associato all'oggetto file è un file temporaneo. |
| FO_DELETE_ON_CLOSE | Il file associato all'oggetto file verrà eliminato dal file system alla chiusura. |
| FO_OPENED_CASE_SENSITIVE | Il caso del nome file del file associato all'oggetto file viene rispettato. |
| FO_HANDLE_CREATED | È stato creato un handle di file per l'oggetto file. |
| FO_FILE_FAST_IO_READ | È stata eseguita una lettura di I/O veloce su questo oggetto file. |
| FO_RANDOM_ACCESS | Il file associato all'oggetto file è stato aperto per l'accesso casuale. |
| FO_FILE_OPEN_CANCELLED | La richiesta di creazione per questo oggetto file è stata annullata prima del completamento. |
| FO_VOLUME_OPEN | L'oggetto file rappresenta una richiesta di apertura del volume. |
| FO_REMOTE_ORIGIN | Richiesta di creazione per il file associato all'oggetto file originato in un computer remoto. |
| FO_SKIP_COMPLETION_PORT | Per un oggetto file associato a una porta, determina se il sistema deve ignorare l'accodamento alla porta di completamento quando l'IRP viene completato in modo sincrono con un valore restituito di stato non di errore. |
| FO_SKIP_SET_EVENT | Ignorare l'impostazione dell'evento per l'oggetto file al completamento di IRP. |
| FO_SKIP_SET_FAST_IO | Ignorare l'impostazione di un evento fornito a un servizio di sistema quando il percorso di I/O rapido ha esito positivo. |
FileName
Struttura UNICODE_STRING la cui buffer membro punta a una stringa Unicode di sola lettura che contiene il nome del file aperto nel volume. Se il volume viene aperto, il membro Length della struttura UNICODE_STRING sarà zero. Si noti che il nome del file in questa stringa è valido solo durante l'elaborazione iniziale di una richiesta di IRP_MJ_CREATE. Questo nome file non deve essere considerato valido dopo che il file system inizia a elaborare la richiesta di IRP_MJ_CREATE. Lo spazio di archiviazione per la stringa a cui punta il membro buffer della struttura UNICODE_STRING viene allocato nella memoria di sistema di paging. Per altre informazioni su come ottenere un nome file, vedere FltGetFileNameInformation.
CurrentByteOffset
Membro di sola lettura che specifica l'offset del file, in byte, associato all'oggetto file.
Waiters
Membro di sola lettura utilizzato dal sistema per contare il numero di camerieri in attesa su un oggetto file aperto per l'accesso sincrono.
Busy
Membro di sola lettura utilizzato dal sistema per indicare se un oggetto file aperto per l'accesso sincrono è attualmente occupato.
LastLock
Puntatore opaco all'ultimo blocco applicato all'oggetto file.
Lock
Membro opaco utilizzato dal sistema per contenere un blocco eventi dell'oggetto file. Il blocco eventi viene usato per controllare l'accesso sincrono all'oggetto file. Applicabile solo agli oggetti file aperti per l'accesso sincrono.
Event
Membro opaco utilizzato dal sistema per contenere un oggetto evento per l'oggetto file. L'oggetto evento viene usato per segnalare il completamento di una richiesta di I/O sull'oggetto file se non è stato fornito alcun evento utente o se è stata chiamata un'API sincrona.
CompletionContext
Puntatore opaco alle informazioni sulla porta di completamento (puntatore e chiave) associati all'oggetto file, se presente.
IrpListLock
Puntatore opaco a una struttura KSPIN_LOCK che funge da blocco di selezione usato per sincronizzare l'accesso all'elenco IRP dell'oggetto file.
IrpList
Puntatore opaco all'inizio dell'elenco IRP associato all'oggetto file.
FileObjectExtension
Puntatore opaco alla struttura dell'oggetto file (FOBX). La struttura di FOBX contiene vari contesti opachi usati internamente, nonché i contesti di oggetto per file disponibili tramite routine FsRtlXxx.
_IOP_FILE_OBJECT_EXTENSION
Struttura _IOP_FILE_OBJECT_EXTENSION.
Osservazioni
I driver possono utilizzare i membri FsContext e FsContext2 per mantenere lo stato determinato dal driver su un oggetto file aperto. Un driver non può usare questi membri a meno che l'oggetto file non sia accessibile nella posizione dello stack I/O del driver di un IRP.
Tutti i membri rimanenti in un oggetto file sono opachi o di sola lettura:
I membri opachi all'interno di un oggetto file devono essere considerati inaccessibili. I driver con dipendenze dalle posizioni dei campi degli oggetti o l'accesso a membri opachi potrebbero non rimanere portabili e interoperabili con altri driver nel tempo.
I driver possono utilizzare membri di sola lettura per acquisire informazioni pertinenti, ma non devono modificare i membri di sola lettura e, se un puntatore, l'oggetto a cui punta il membro.
Durante l'elaborazione di una richiesta di IRP_MJ_CREATE, un driver del file system chiama la routine IoSetShareAccess (se il client è il primo ad aprire il file) o la routine IoCheckShareAccess (per i client successivi che desiderano condividere il file). IoSetShareAccess e IoCheckShareAccess aggiornare ReadAccess, WriteAccesse membri deleteAccess per indicare i diritti di accesso concessi al client se il client ha accesso esclusivo al file. Inoltre, IoCheckShareAccess aggiorna i membri SharedRead, SharedWritee SharedDelete per indicare i diritti di accesso concessi simultaneamente a due o più client che condividono il file. Se il driver per un dispositivo diverso da un file system deve monitorare i diritti di accesso dei client, questo driver archivia in genere le informazioni sui diritti di accesso nei buffer di contesto a cui punta il FsContext e FsContext2 membri.
Il tipo di oggetto , ad esempio un file, una directory o un volume, che un determinato oggetto file rappresenta non può essere determinato esaminando solo il contenuto della struttura dell'oggetto file. Per informazioni su come determinare il tipo di oggetto rappresentato da un oggetto file, vedere ZwQueryInformationFile.
Common Log File System (CLFS) usa la struttura LOG_FILE_OBJECT per rappresentare i log. La funzione ClfsCreateLogFile restituisce un puntatore a una struttura LOG_FILE_OBJECT, che i client passano quindi ad altre funzioni CLFS.
I client CLFS non accedono direttamente ai membri di una struttura LOG_FILE_OBJECT.
typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;
Fabbisogno
| Requisito | Valore |
|---|---|
| intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |