структура FILE_OBJECT (wdm.h)
Структура FILE_OBJECT используется системой для представления объекта файла. Для подсистем, защищенных в пользовательском режиме, объект file представляет открытый экземпляр файла, устройства, каталога или тома. Для драйверов устройства и промежуточных драйверов объект file обычно представляет объект устройства. Для драйверов в стеке файловой системы объект file обычно представляет каталог или файл.
Файловый объект является частично непрозрачным. Некоторые типы драйверов, например драйверы файловой системы и драйверы сетевого транспорта, используют некоторые поля файловых объектов.
Синтаксис
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;
Члены
Type
Элемент, доступный только для чтения, используемый системой для указания того, что объект является файлом. Если объект является файлом, значение этого элемента равно 5.
Size
Элемент, доступный только для чтения, который указывает размер объекта файла в байтах. Этот размер не включает расширение объекта файла, если таковое имеется.
DeviceObject
Указатель на объект устройства, в котором открыт файл.
Vpb
Указатель на блок параметров тома, связанный с объектом файла.
Обратите внимание, что если элемент Vpb не равен NULL, файл находится на подключенном томе.
FsContext
Указатель на любое необязательное состояние, которое драйвер поддерживает в отношении объекта файла; в противном случае — NULL. Для драйверов файловой системы этот элемент должен указывать на структуру заголовков FSRTL_ADVANCED_FCB_HEADER , которая содержится в структуре файловой системы; в противном случае может привести к нестабильной работе системы. Обычно эта структура заголовков внедряется в блок управления файлами (FCB). Однако в некоторых файловых системах, поддерживающих несколько потоков данных, таких как NTFS, эта структура заголовка является блоком управления потоком (SCB).
В стеке устройств WDM только объект функционального устройства (FDO) может использовать два указателя контекста. Драйверы файловой системы совместно используют этот элемент в нескольких открытиях одного потока данных.
FsContext2
Указатель на любое дополнительное состояние, которое драйвер поддерживает в отношении объекта файла; в противном случае — NULL.
Этот элемент непрозрачн для драйверов в стеке файловой системы, так как его использует базовая файловая система.
SectionObjectPointer
Указатель на объект раздела только для чтения объекта файла. Этот элемент задается только файловой системой и используется для взаимодействия с диспетчером кэша.
PrivateCacheMap
Непрозрачный элемент, заданный только файловыми системами, который указывает на обработку определенных сведений и используется для взаимодействия с диспетчером кэша.
FinalStatus
Элемент, доступный только для чтения, который используется в некоторых синхронных случаях для указания конечного состояния запроса ввода-вывода объекта файла.
RelatedFileObject
Указатель на структуру FILE_OBJECT , используемую для указания того, что текущий объект файла открыт относительно уже открытого объекта файла. Объект файла, на который указывает этот элемент, обычно является каталогом (это означает, что текущий файл был открыт относительно этого каталога). Однако файл можно повторно открыть относительно самого себя, а альтернативные потоки данных для файла можно открыть относительно уже открытого основного потока данных для этого же файла. Элемент RelatedFileObject действителен только во время обработки запросов IRP_MJ_CREATE .
LockOperation
Элемент, доступный только для чтения. Если задано значение FALSE, операция блокировки (NtLockFile) никогда не выполнялась с объектом файла. Если задано значение TRUE, для объекта файла выполнена по крайней мере одна операция блокировки. Если задано значение TRUE, этот элемент всегда остается TRUE (например, при освобождении блокировки файлов в объекте файла этот элемент не сбрасывается с значения FALSE).
DeletePending
Элемент, доступный только для чтения. Если значение РАВНО TRUE, для файла, связанного с объектом файла, существует операция удаления. Если значение РАВНО FALSE, в настоящее время для объекта файла нет ожидающих операций удаления.
ReadAccess
Элемент, доступный только для чтения. Если задано значение TRUE, файл, связанный с объектом file, был открыт для чтения. Если задано значение FALSE, файл был открыт без доступа на чтение. Эти сведения используются при проверке и (или) настройке общего доступа к файлу.
WriteAccess
Элемент, доступный только для чтения. Если задано значение TRUE, файл, связанный с объектом file, был открыт для записи. Если задано значение FALSE, файл был открыт без доступа на запись. Эти сведения используются при проверке и (или) настройке общего доступа к файлу.
DeleteAccess
Элемент, доступный только для чтения. Если задано значение TRUE, файл, связанный с объектом файла, был открыт для удаления. Если задано значение FALSE, файл был открыт без доступа к удалению. Эти сведения используются при проверке и (или) настройке общего доступа к файлу.
SharedRead
Элемент, доступный только для чтения. Если задано значение TRUE, файл, связанный с объектом файла, был открыт для доступа для чтения. Если задано значение FALSE, файл был открыт без доступа для чтения. Эти сведения используются при проверке и (или) настройке общего доступа к файлу.
SharedWrite
Элемент, доступный только для чтения. Если задано значение TRUE, файл, связанный с объектом файла, был открыт для общего доступа к записи. Если задано значение FALSE, файл был открыт без доступа к совместному использованию записи. Эти сведения используются при проверке и (или) настройке общего доступа к файлу.
SharedDelete
Элемент, доступный только для чтения. Если значение РАВНО TRUE, файл, связанный с объектом файла, был открыт для удаления общего доступа. Если задано значение FALSE, файл был открыт без удаления общего доступа. Эти сведения используются при проверке и (или) настройке общего доступа к файлу.
Flags
Элемент, доступный только для чтения, используемый системой для хранения одного или нескольких (побитовая инклюзивная комбинация ИЛИ) следующих значений закрытого флага.
| Flag | Значение |
|---|---|
| FO_FILE_OPEN | Не рекомендуется. |
| FO_SYNCHRONOUS_IO | Объект файла открыт для синхронного ввода-вывода. |
| FO_ALERTABLE_IO | Любое ожидание в диспетчере ввода-вывода в результате запроса к этому объекту файла может быть оповещено. |
| FO_NO_INTERMEDIATE_BUFFERING | Файл, связанный с объектом file, не может быть кэширован или помещен в буфер во внутренних буферах драйвера. |
| FO_WRITE_THROUGH | Системные службы, драйверы файловой системы и драйверы, записывющие данные в файл, должны передавать данные в файл, прежде чем любая запрошенная операция записи будет считаться завершенной. |
| FO_SEQUENTIAL_ONLY | Файл, связанный с объектом файла, был открыт только для последовательных операций ввода-вывода. |
| FO_CACHE_SUPPORTED | Файл, связанный с объектом файла, является кэшируемым. Этот флаг должен задаваться только драйвером файловой системы и только в том случае, если член FsContext указывает на допустимую FSRTL_ADVANCED_FCB_HEADER структуру. |
| FO_NAMED_PIPE | Объект file представляет именованный канал. |
| FO_STREAM_FILE | Объект file представляет файловый поток. |
| FO_MAILSLOT | Объект file представляет собой mailslot. |
| FO_GENERATE_AUDIT_ON_CLOSE | Не рекомендуется. |
| FO_QUEUE_IRP_TO_THREAD | Поставщики irP не будут помещены в очередь для этого объекта файла. |
| FO_DIRECT_DEVICE_OPEN | Устройство, на которое нацелен этот объект файла, было открыто напрямую. |
| FO_FILE_MODIFIED | Файл, связанный с объектом файла, был изменен. |
| FO_FILE_SIZE_CHANGED | Размер файла, связанного с объектом file, изменился. |
| FO_CLEANUP_COMPLETE | Файловая система завершила очистку для этого объекта файла. |
| FO_TEMPORARY_FILE | Файл, связанный с объектом file, является временным файлом. |
| FO_DELETE_ON_CLOSE | Файл, связанный с объектом file, будет удален файловой системой при закрытии. |
| FO_OPENED_CASE_SENSITIVE | Учитывается регистр имени файла, связанного с объектом файла. |
| FO_HANDLE_CREATED | Для объекта file был создан дескриптор файла. |
| FO_FILE_FAST_IO_READ | Для этого объекта файла было выполнено быстрое чтение операций ввода-вывода. |
| FO_RANDOM_ACCESS | Файл, связанный с объектом file, был открыт для произвольного доступа. |
| FO_FILE_OPEN_CANCELLED | Запрос на создание этого объекта файла был отменен до завершения. |
| FO_VOLUME_OPEN | Объект file представляет запрос на открытие тома. |
| FO_REMOTE_ORIGIN | Запрос на создание файла, связанного с объектом файла, был создан на удаленном компьютере. |
| FO_SKIP_COMPLETION_PORT | Для объекта файла, связанного с портом, определяет, следует ли системе пропускать очередь на порт завершения при синхронном завершении IRP с возвращаемым значением состояния без ошибок. |
| FO_SKIP_SET_EVENT | Пропустите настройку события для объекта файла после завершения IRP. |
| FO_SKIP_SET_FAST_IO | Пропустите настройку события, предоставляемого системной службе, при успешном выполнении пути быстрого ввода-вывода. |
FileName
Структура UNICODE_STRING, член буфера которой указывает на доступную только для чтения строку Юникода, содержащую имя файла, открытого на томе. Если том открывается, элемент Lengthструктуры UNICODE_STRING будет равен нулю. Обратите внимание, что имя файла в этой строке допустимо только во время начальной обработки запроса IRP_MJ_CREATE . Это имя файла не следует считать допустимым после того, как файловая система начнет обрабатывать запрос IRP_MJ_CREATE . Хранилище для строки, на которую указывает элемент Bufferструктуры UNICODE_STRING , выделяется в системной памяти с постраничной системой. Дополнительные сведения о получении имени файла см. в разделе FltGetFileNameInformation.
CurrentByteOffset
Доступный только для чтения элемент, указывающий смещение файла в байтах, связанное с объектом file.
Waiters
Элемент, доступный только для чтения, используемый системой для подсчета числа ожидающих ожиданий в объекте файла, открытом для синхронного доступа.
Busy
Элемент, доступный только для чтения, используемый системой для указания, занят ли в настоящее время объект файла, открытый для синхронного доступа.
LastLock
Непрозрачный указатель на последнюю блокировку, примененную к объекту файла.
Lock
Непрозрачный элемент, используемый системой для хранения блокировки событий объекта файла. Блокировка событий используется для управления синхронным доступом к объекту файла. Применимо только к файловым объектам, открытым для синхронного доступа.
Event
Непрозрачный элемент, используемый системой для хранения объекта события для объекта файла. Объект события используется для обозначения завершения запроса ввода-вывода в объекте файла, если не было предоставлено пользовательское событие или был вызван синхронный API.
CompletionContext
Непрозрачный указатель на сведения о порте завершения (указатель порта и ключ), связанный с объектом файла, если таковой есть.
IrpListLock
Непрозрачный указатель на структуру KSPIN_LOCK , которая служит в качестве блокировки спина, используемой для синхронизации доступа к списку IRP объекта файла.
IrpList
Непрозрачный указатель на главу списка IRP, связанного с объектом файла.
FileObjectExtension
Непрозрачный указатель на структуру расширения файлового объекта (FOBX). Структура FOBX содержит различные непрозрачные контексты, используемые внутри, а также контексты объектов для каждого файла, доступные в подпрограммах FsRtlXxx .
_IOP_FILE_OBJECT_EXTENSION
Структура _IOP_FILE_OBJECT_EXTENSION .
Комментарии
Драйверы могут использовать элементы FsContext и FsContext2 для поддержания определяемого драйвером состояния открытого объекта файла. Драйвер не может использовать эти элементы, если объект файла не доступен в расположении стека ввода-вывода драйвера IRP.
Все остальные элементы в объекте файла являются непрозрачными или доступны только для чтения:
Непрозрачные элементы в объекте файла следует считать недоступными. Драйверы с зависимостями от расположений полей объектов или доступом к непрозрачным элементам могут со временем оставаться переносимыми и совместимыми с другими драйверами.
Драйверы могут использовать доступные только для чтения элементы для получения релевантной информации, но не должны изменять доступные только для чтения элементы и, если указатель, объект, на который указывает элемент.
Во время обработки запроса IRP_MJ_CREATE драйвер файловой системы вызывает подпрограмму IoSetShareAccess (если клиент первым открывает файл) или процедуру IoCheckShareAccess (для последующих клиентов, которым требуется предоставить общий доступ к файлу). IoSetShareAccess и IoCheckShareAccess обновляют элементы ReadAccess, WriteAccess и DeleteAccess , чтобы указать права доступа, предоставляемые клиенту, если клиент имеет монопольный доступ к файлу. Кроме того, IoCheckShareAccess обновляет элементы SharedRead, SharedWrite и SharedDelete , чтобы указать права доступа, которые одновременно предоставляются двум или более клиентам, которые совместно используют файл. Если драйвер для устройства, отличного от файловой системы, должен отслеживать права доступа клиентов, этот драйвер обычно сохраняет сведения о правах доступа в контекстных буферах, на которые указывают члены FsContext и FsContext2 .
Тип объекта (например, файл, каталог или том), который представляет данный файловый объект, нельзя определить только путем изучения содержимого структуры файлового объекта. Сведения об определении типа объекта, который представляет файловый объект, см. в разделе ZwQueryInformationFile.
Общая файловая система журналов (CLFS) использует структуру LOG_FILE_OBJECT для представления журналов. Функция ClfsCreateLogFile возвращает указатель на структуру LOG_FILE_OBJECT , которую клиенты затем передают другим функциям CLFS.
Клиенты CLFS не обращаются напрямую к членам структуры LOG_FILE_OBJECT .
typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;
Требования
| Требование | Значение |
|---|---|
| Заголовок | wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |