Поделиться через


структура 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)

См. также раздел

DEVICE_OBJECT

FOBX

FSRTL_ADVANCED_FCB_HEADER

IRP_MJ_CREATE

IoCheckShareAccess

IoGetDeviceObjectPointer

IoSetShareAccess

ObDereferenceObject

ZwQueryInformationFile