struttura FILE_OBJECT (wdm.h)
La struttura FILE_OBJECT viene usata 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;
Members
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ò causare. 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 di file system condividono questo membro tra più apre lo stesso flusso di dati.
FsContext2
Puntatore a qualsiasi altro stato 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 usa questo membro.
SectionObjectPointer
Puntatore all'oggetto di sola lettura dell'oggetto file. Questo membro viene impostato solo dai file system e usato per l'interazione con Cache Manager.
PrivateCacheMap
Un membro opaco, impostato solo da file system, che punta a gestire informazioni specifiche e che viene usato per l'interazione con Cache Manager.
FinalStatus
Membro di sola lettura usato in determinati casi sincroni per indicare lo stato finale della richiesta di I/O dell'oggetto file.
RelatedFileObject
Puntatore a una struttura FILE_OBJECT utilizzata per indicare che l'oggetto file corrente è stato aperto rispetto a un oggetto file già aperto. L'oggetto file a cui fa riferimento 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, almeno un'operazione di blocco è stata eseguita sull'oggetto file. Dopo aver impostato su TRUE, questo membro rimane sempre TRUE , ad esempio rilasciando blocchi di file sull'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 esiste attualmente 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 di 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 di condivisione del file.
DeleteAccess
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per eliminare l'accesso. Se FALSE, il file è stato aperto senza eliminare l'accesso. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso di condivisione del file.
SharedRead
Membro di sola lettura. Se TRUE, il file associato all'oggetto file è stato aperto per l'accesso alla condivisione in lettura. Se FALSE, il file è stato aperto senza l'accesso in lettura. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso di 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 l'accesso alla condivisione di scrittura. Queste informazioni vengono usate durante il controllo e/o l'impostazione dell'accesso di 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 di condivisione del file.
Flags
Membro di sola lettura usato dal sistema per contenere una o più (combinazione OR inclusiva bit per bit) dei valori del flag privato seguenti.
| Contrassegno | Significato |
|---|---|
| FO_FILE_OPEN | Deprecato. |
| FO_SYNCHRONOUS_IO | L'oggetto file viene aperto per I/O sincrono. |
| FO_ALERTABLE_IO | Qualsiasi attesa nella gestione 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 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 venga considerata completata qualsiasi operazione di scrittura richiesta. |
| 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 è memorizzato nella cache. Questo flag deve essere impostato solo da un driver di 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 pipe denominata. |
| FO_STREAM_FILE | L'oggetto file rappresenta un flusso di file. |
| FO_MAILSLOT | L'oggetto file rappresenta una mailslot. |
| FO_GENERATE_AUDIT_ON_CLOSE | Deprecato. |
| FO_QUEUE_IRP_TO_THREAD | Gli irP 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 al termine della 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 | Una lettura di I/O rapida è stata eseguita 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 aperta 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 il cui membro buffer 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 l'avvio del file system per elaborare la richiesta di IRP_MJ_CREATE . L'archiviazione per la stringa a cui punta il membro Buffer della struttura UNICODE_STRING viene allocata nella memoria di sistema in pagina. Per altre informazioni sull'acquisizione di 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 sospeso su un oggetto file aperto per l'accesso sincrono.
Busy
Un membro di sola lettura usato 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
Un membro opaco usato dal sistema per contenere un blocco evento di un 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 nell'oggetto file se non è stato fornito alcun evento utente o è stata chiamata un'API sincrona.
CompletionContext
Puntatore opaco alle informazioni sulla porta di completamento (puntatore porta e chiave) associato all'oggetto file, se presente.
IrpListLock
Puntatore opaco a una struttura KSPIN_LOCK che funge da blocco di rotazione usato per sincronizzare l'accesso all'elenco IRP dell'oggetto file.
IrpList
Puntatore opaco alla testa dell'elenco IRP associato all'oggetto file.
FileObjectExtension
Puntatore opaco alla struttura dell'oggetto file (FOBX) dell'oggetto file. La struttura FOBX contiene vari contesti opachi usati internamente e i contesti per oggetto per file disponibili tramite le routine FsRtlXxx .
_IOP_FILE_OBJECT_EXTENSION
Struttura _IOP_FILE_OBJECT_EXTENSION .
Commenti
I driver possono usare 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'istanza di 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 sulle posizioni dei campi oggetto o l'accesso ai membri opachi potrebbero non rimanere portabili e interoperabili con altri driver nel tempo.
I driver possono usare 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 di file system chiama la routine IoSetShareAccess (se il client è il primo a aprire il file) o la routine IoCheckShareAccess (per i client successivi che vogliono condividere il file). IoSetShareAccess e IoCheckShareAccess aggiornano i membri ReadAccess, WriteAccess e DeleteAccess per indicare i diritti di accesso concessi al client se il client ha accesso esclusivo al file. Inoltre, IoCheckShareAccess aggiorna i membri SharedRead, SharedWrite e 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 puntano i membri FsContext e FsContext2 .
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;
Requisiti
| Requisito | Valore |
|---|---|
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |