FILE_OBJECT-Struktur (wdm.h)
Die FILE_OBJECT-Struktur wird vom System verwendet, um ein Dateiobjekt darzustellen. Für vom Benutzermodus geschützte Subsysteme stellt ein Dateiobjekt eine offene instance einer Datei, eines Geräts, eines Verzeichnisses oder volumes dar. Für Geräte- und Zwischentreiber stellt ein Dateiobjekt in der Regel ein Geräteobjekt dar. Für Treiber im Dateisystemstapel stellt ein Dateiobjekt in der Regel ein Verzeichnis oder eine Datei dar.
Ein Dateiobjekt ist teilweise undurchsichtig. Bestimmte Arten von Treibern, z. B. Dateisystemtreiber und Netzwerktransporttreiber, verwenden einige felder von Dateiobjekten.
Syntax
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;
Member
Type
Ein schreibgeschützter Member, der vom System verwendet wird, um anzugeben, dass das Objekt ein Dateiobjekt ist. Wenn es sich bei dem Objekt um ein Dateiobjekt handelt, ist der Wert dieses Members 5.
Size
Ein schreibgeschützter Member, der die Größe des Dateiobjekts in Bytes angibt. Diese Größe enthält nicht die Dateiobjekterweiterung, sofern vorhanden.
DeviceObject
Ein Zeiger auf das Geräteobjekt, auf dem die Datei geöffnet wird.
Vpb
Ein Zeiger auf den Volumeparameterblock, der dem Dateiobjekt zugeordnet ist.
Beachten Sie, dass sich die Datei auf einem bereitgestellten Volume befindet, wenn der Vpb-Member nicht NULL ist.
FsContext
Ein Zeiger auf den optionalen Zustand, den ein Treiber über das Dateiobjekt verwaltet; andernfalls NULL. Bei Dateisystemtreibern muss dieser Member auf eine FSRTL_ADVANCED_FCB_HEADER Headerstruktur verweisen, die in einer dateisystemspezifischen Struktur enthalten ist. Andernfalls kann es zu Systeminstabilität führen. Normalerweise wird diese Headerstruktur in einen Dateisteuerungsblock (FCB) eingebettet. Bei einigen Dateisystemen, die mehrere Datenströme unterstützen, z. B. NTFS, ist diese Headerstruktur jedoch ein Stream Control Block (SCB).
In einem WDM-Gerätestapel kann nur das funktionale Geräteobjekt (Functional Device Object, FDO) die beiden Kontextzeiger verwenden. Dateisystemtreiber teilen dieses Element über mehrere Geöffnete für denselben Datenstrom.
FsContext2
Ein Zeiger auf den zusätzlichen Zustand, den ein Treiber über das Dateiobjekt verwaltet; andernfalls NULL.
Dieser Member ist für Treiber im Dateisystemstapel nicht transparent, da das zugrunde liegende Dateisystem diesen Member verwendet.
SectionObjectPointer
Ein Zeiger auf das schreibgeschützte Abschnittsobjekt des Dateiobjekts. Dieser Member wird nur von Dateisystemen festgelegt und für die Cache-Manager-Interaktion verwendet.
PrivateCacheMap
Ein nicht transparentes Element, das nur von Dateisystemen festgelegt wird, das auf handle-spezifische Informationen verweist und für die Cache-Manager-Interaktion verwendet wird.
FinalStatus
Ein schreibgeschützter Member, der in bestimmten synchronen Fällen verwendet wird, um die endgültige status der E/A-Anforderung des Dateiobjekts anzugeben.
RelatedFileObject
Ein Zeiger auf eine FILE_OBJECT Struktur, die angibt, dass das aktuelle Dateiobjekt relativ zu einem bereits geöffneten Dateiobjekt geöffnet wurde. Das Dateiobjekt, auf das dieses Element verweist, ist in der Regel ein Verzeichnis (d. h. die aktuelle Datei wurde relativ zu diesem Verzeichnis geöffnet). Eine Datei kann jedoch relativ zu sich selbst erneut geöffnet werden, und alternative Datenströme für eine Datei können relativ zu einem bereits geöffneten primären Datenstrom für dieselbe Datei geöffnet werden. Das RelatedFileObject-Element ist nur während der Verarbeitung der IRP_MJ_CREATE-Anforderungen gültig.
LockOperation
Ein schreibgeschützter Member. Wenn FALSE, wurde noch nie ein Sperrvorgang (NtLockFile) für das Dateiobjekt ausgeführt. Wenn TRUE, wurde mindestens ein Sperrvorgang für das Dateiobjekt ausgeführt. Nach dem Festlegen auf TRUE bleibt dieser Member immer TRUE (z. B. wird durch das Freigeben von Dateisperren für das Dateiobjekt dieser Member nicht auf FALSE zurückgesetzt).
DeletePending
Ein schreibgeschützter Member. Wenn TRUE, ist ein Löschvorgang für die Datei vorhanden, die dem Dateiobjekt zugeordnet ist. Bei FALSE ist derzeit kein Löschvorgang für das Dateiobjekt ausstehend.
ReadAccess
Ein schreibgeschützter Member. True gibt an, dass die dem Dateiobjekt zugeordnete Datei für den Lesezugriff geöffnet wurde. Bei FALSE wurde die Datei ohne Lesezugriff geöffnet. Diese Informationen werden beim Überprüfen und/oder Festlegen des Freigabezugriffs auf die Datei verwendet.
WriteAccess
Ein schreibgeschützter Member. True gibt an, dass die dem Dateiobjekt zugeordnete Datei für den Schreibzugriff geöffnet wurde. Bei FALSE wurde die Datei ohne Schreibzugriff geöffnet. Diese Informationen werden beim Überprüfen und/oder Festlegen des Freigabezugriffs auf die Datei verwendet.
DeleteAccess
Ein schreibgeschützter Member. True gibt an, dass die dem Dateiobjekt zugeordnete Datei für den Löschzugriff geöffnet wurde. Bei FALSE wurde die Datei ohne Löschzugriff geöffnet. Diese Informationen werden beim Überprüfen und/oder Festlegen des Freigabezugriffs auf die Datei verwendet.
SharedRead
Ein schreibgeschützter Member. True gibt an, dass die dem Dateiobjekt zugeordnete Datei für den Lesefreigabezugriff geöffnet wurde. Bei FALSE wurde die Datei ohne Lesefreigabezugriff geöffnet. Diese Informationen werden beim Überprüfen und/oder Festlegen des Freigabezugriffs auf die Datei verwendet.
SharedWrite
Ein schreibgeschützter Member. True gibt an, dass die dem Dateiobjekt zugeordnete Datei für den Schreibfreigabezugriff geöffnet wurde. Bei FALSE wurde die Datei ohne Schreibfreigabezugriff geöffnet. Diese Informationen werden beim Überprüfen und/oder Festlegen des Freigabezugriffs auf die Datei verwendet.
SharedDelete
Ein schreibgeschützter Member. True gibt an, dass die dem Dateiobjekt zugeordnete Datei zum Löschen des Freigabezugriffs geöffnet wurde. Bei FALSE wurde die Datei ohne Freigabezugriff geöffnet. Diese Informationen werden beim Überprüfen und/oder Festlegen des Freigabezugriffs auf die Datei verwendet.
Flags
Ein schreibgeschützter Member, der vom System verwendet wird, um einen oder mehrere (eine bitweise inklusive OR-Kombination) der folgenden privaten Flagwerte zu enthalten.
| Flag | Bedeutung |
|---|---|
| FO_FILE_OPEN | Veraltet. |
| FO_SYNCHRONOUS_IO | Das Dateiobjekt wird für synchrone E/A-Vorgänge geöffnet. |
| FO_ALERTABLE_IO | Jede Wartezeit im E/A-Manager als Ergebnis einer Anforderung an dieses Dateiobjekt ist warnbar. |
| FO_NO_INTERMEDIATE_BUFFERING | Die dem Dateiobjekt zugeordnete Datei kann nicht zwischengespeichert oder in den internen Puffern eines Treibers gepuffert werden. |
| FO_WRITE_THROUGH | Systemdienste, Dateisystemtreiber und Treiber, die Daten in die Datei schreiben, müssen die Daten in die Datei übertragen, bevor ein angeforderter Schreibvorgang als abgeschlossen betrachtet wird. |
| FO_SEQUENTIAL_ONLY | Die dem Dateiobjekt zugeordnete Datei wurde nur für sequenzielle E/A-Vorgänge geöffnet. |
| FO_CACHE_SUPPORTED | Die dem Dateiobjekt zugeordnete Datei kann zwischengespeichert werden. Dieses Flag sollte nur von einem Dateisystemtreiber festgelegt werden, und nur, wenn der FsContext-Member auf eine gültige FSRTL_ADVANCED_FCB_HEADER-Struktur verweist. |
| FO_NAMED_PIPE | Das Dateiobjekt stellt eine Named Pipe dar. |
| FO_STREAM_FILE | Das Dateiobjekt stellt einen Dateidatenstrom dar. |
| FO_MAILSLOT | Das Dateiobjekt stellt ein Maillot dar. |
| FO_GENERATE_AUDIT_ON_CLOSE | Veraltet. |
| FO_QUEUE_IRP_TO_THREAD | IRPs werden nicht in die Warteschlange dieses Dateiobjekts eingereiht. |
| FO_DIRECT_DEVICE_OPEN | Das Gerät, auf das dieses Dateiobjekt abzielt, wurde direkt geöffnet. |
| FO_FILE_MODIFIED | Die dem Dateiobjekt zugeordnete Datei wurde geändert. |
| FO_FILE_SIZE_CHANGED | Die dem Dateiobjekt zugeordnete Datei hat sich in der Größe geändert. |
| FO_CLEANUP_COMPLETE | Das Dateisystem hat die Bereinigung für dieses Dateiobjekt abgeschlossen. |
| FO_TEMPORARY_FILE | Die dem Dateiobjekt zugeordnete Datei ist eine temporäre Datei. |
| FO_DELETE_ON_CLOSE | Die dem Dateiobjekt zugeordnete Datei wird beim Schließen vom Dateisystem gelöscht. |
| FO_OPENED_CASE_SENSITIVE | Der Dateiname der Datei, die dem Dateiobjekt zugeordnet ist, wird berücksichtigt. |
| FO_HANDLE_CREATED | Für das Dateiobjekt wurde ein Dateihandle erstellt. |
| FO_FILE_FAST_IO_READ | Für dieses Dateiobjekt wurde ein schneller E/A-Lesevorgang durchgeführt. |
| FO_RANDOM_ACCESS | Die dem Dateiobjekt zugeordnete Datei wurde für den zufälligen Zugriff geöffnet. |
| FO_FILE_OPEN_CANCELLED | Die Erstellungsanforderung für dieses Dateiobjekt wurde vor Abschluss abgebrochen. |
| FO_VOLUME_OPEN | Das Dateiobjekt stellt eine volume open request dar. |
| FO_REMOTE_ORIGIN | Die Erstellungsanforderung für die Datei, die dem Dateiobjekt zugeordnet ist, stammt auf einem Remotecomputer. |
| FO_SKIP_COMPLETION_PORT | Für ein einem Port zugeordnetes Dateiobjekt bestimmt, ob das System die Warteschlangen bis zum Vervollständigungsport überspringen soll, wenn der IRP synchron mit einem Nichtfehler status Rückgabewert abgeschlossen wird. |
| FO_SKIP_SET_EVENT | Überspringen Sie das Festlegen des Ereignisses für das Dateiobjekt nach IRP-Abschluss. |
| FO_SKIP_SET_FAST_IO | Überspringen Sie das Festlegen eines Für einen Systemdienst bereitgestellten Ereignisses, wenn der schnelle E/A-Pfad erfolgreich ist. |
FileName
Eine UNICODE_STRING-Struktur , deren Buffer-Member auf eine schreibgeschützte Unicode-Zeichenfolge verweist, die den Namen der datei enthält, die auf dem Volume geöffnet wurde. Wenn das Volume geöffnet wird, ist das Length-Element der UNICODE_STRING-Struktur 0. Beachten Sie, dass der Dateiname in dieser Zeichenfolge nur während der erstverarbeitung einer IRP_MJ_CREATE-Anforderung gültig ist. Dieser Dateiname sollte nicht als gültig betrachtet werden, nachdem das Dateisystem mit der Verarbeitung der IRP_MJ_CREATE Anforderung begonnen hat. Der Speicher für die Zeichenfolge, auf die der Puffermember der UNICODE_STRING-Struktur verweist, wird im ausgelagerten Systemspeicher zugeordnet. Weitere Informationen zum Abrufen eines Dateinamens finden Sie unter FltGetFileNameInformation.
CurrentByteOffset
Ein schreibgeschütztes Element, das den Dateioffset in Bytes angibt, der dem Dateiobjekt zugeordnet ist.
Waiters
Ein schreibgeschütztes Element, das vom System verwendet wird, um die Anzahl der ausstehenden Kellner für ein Dateiobjekt zu zählen, das für den synchronen Zugriff geöffnet wurde.
Busy
Ein schreibgeschütztes Element, das vom System verwendet wird, um anzugeben, ob ein für den synchronen Zugriff geöffnetes Dateiobjekt derzeit ausgelastet ist.
LastLock
Ein undurchsichtiger Zeiger auf die letzte Sperre, die auf das Dateiobjekt angewendet wurde.
Lock
Ein undurchsichtiges Element, das vom System verwendet wird, um eine Dateiobjektereignissperre zu speichern. Die Ereignissperre wird verwendet, um den synchronen Zugriff auf das Dateiobjekt zu steuern. Gilt nur für Dateiobjekte, die für den synchronen Zugriff geöffnet werden.
Event
Ein undurchsichtiger Member, der vom System zum Speichern eines Ereignisobjekts für das Dateiobjekt verwendet wird. Das Ereignisobjekt wird verwendet, um den Abschluss einer E/A-Anforderung für das Dateiobjekt zu signalisieren, wenn kein Benutzerereignis angegeben oder eine synchrone API aufgerufen wurde.
CompletionContext
Ein undurchsichtiger Zeiger auf die Vervollständigungsportinformationen (Portzeiger und Schlüssel), die dem Dateiobjekt zugeordnet sind, falls vorhanden.
IrpListLock
Ein undurchsichtiger Zeiger auf eine KSPIN_LOCK-Struktur , die als Drehsperre dient, mit der der Zugriff auf die IRP-Liste des Dateiobjekts synchronisiert wird.
IrpList
Ein undurchsichtiger Zeiger auf den Kopf der IRP-Liste, die dem Dateiobjekt zugeordnet ist.
FileObjectExtension
Ein undurchsichtiger Zeiger auf die FOBX-Struktur (File Object Extension) des Dateiobjekts. Die FOBX-Struktur enthält verschiedene undurchsichtige Kontexte, die intern verwendet werden, sowie die Objektkontexte pro Datei, die über FsRtlXxx-Routinen verfügbar sind.
_IOP_FILE_OBJECT_EXTENSION
Eine _IOP_FILE_OBJECT_EXTENSION-Struktur .
Hinweise
Treiber können die Elemente FsContext und FsContext2 verwenden, um den treiberbestimmten Zustand eines geöffneten Dateiobjekts beizubehalten. Ein Treiber kann diese Member nur verwenden, wenn auf das Dateiobjekt im E/A-Stapelspeicherort eines IRP des Treibers zugegriffen werden kann.
Alle verbleibenden Member in einem Dateiobjekt sind entweder undurchsichtig oder schreibgeschützt:
Undurchsichtige Elemente innerhalb eines Dateiobjekts sollten als nicht zugänglich betrachtet werden. Treiber mit Abhängigkeiten von Objektfeldstandorten oder Zugriff auf undurchsichtige Member bleiben möglicherweise nicht portabel und interoperabel mit anderen Treibern im Laufe der Zeit.
Treiber können schreibgeschützte Member verwenden, um relevante Informationen zu erhalten, dürfen aber nicht schreibgeschützte Member und, wenn ein Zeiger, das Objekt ändern, auf das das Element verweist.
Während der Verarbeitung einer IRP_MJ_CREATE Anforderung ruft ein Dateisystemtreiber die IoSetShareAccess-Routine (wenn der Client die Datei zuerst öffnet) oder die IoCheckShareAccess-Routine (für nachfolgende Clients, die die Datei freigeben möchten) auf. IoSetShareAccess und IoCheckShareAccess aktualisieren die Member ReadAccess, WriteAccess und DeleteAccess , um die Zugriffsrechte anzugeben, die dem Client gewährt werden, wenn der Client exklusiven Zugriff auf die Datei hat. Darüber hinaus aktualisiert IoCheckShareAccess die Member SharedRead, SharedWrite und SharedDelete , um die Zugriffsrechte anzugeben, die gleichzeitig zwei oder mehr Clients gewährt werden, die die Datei gemeinsam nutzen. Wenn der Treiber für ein anderes Gerät als ein Dateisystem die Zugriffsrechte von Clients überwachen muss, speichert dieser Treiber in der Regel Zugriffsberechtigungsinformationen in Kontextpuffern, auf die die Mitglieder fsContext und FsContext2 verweisen.
Der Typ des Objekts (z. B. eine Datei, ein Verzeichnis oder ein Volume), den ein bestimmtes Dateiobjekt darstellt, kann nicht nur durch die Untersuchung des Inhalts der Dateiobjektstruktur bestimmt werden. Informationen zum Bestimmen des Typs des Objekts, das ein Dateiobjekt darstellt, finden Sie unter ZwQueryInformationFile.
Das Common Log File System (CLFS) verwendet die LOG_FILE_OBJECT-Struktur , um Protokolle darzustellen. Die ClfsCreateLogFile-Funktion gibt einen Zeiger auf eine LOG_FILE_OBJECT-Struktur zurück, die clients dann an andere CLFS-Funktionen übergeben.
CLFS-Clients greifen nicht direkt auf die Member einer LOG_FILE_OBJECT-Struktur zu.
typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;
Anforderungen
| Anforderung | Wert |
|---|---|
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |