структура IO_DRIVER_CREATE_CONTEXT (ntddk.h)

Статья
02/29/2024

Структура IO_DRIVER_CREATE_CONTEXT используется для передачи дополнительных параметров подпрограммам IoCreateFileEx и FltCreateFileEx2 . Эта структура является необязательной.

Подпрограмма IoCreateFileEx используется устаревшими драйверами фильтров, а подпрограмма FltCreateFileEx2 используется драйверами минифильтров.

Синтаксис

typedef struct _IO_DRIVER_CREATE_CONTEXT {
  CSHORT               Size;
  struct _ECP_LIST     *ExtraCreateParameter;
  PVOID                DeviceObjectHint;
  PTXN_PARAMETER_BLOCK TxnParameters;
  PESILO               SiloContext;
} IO_DRIVER_CREATE_CONTEXT, *PIO_DRIVER_CREATE_CONTEXT;

Члены

Size

Элемент только для чтения, инициализированный подпрограммой IoInitializeDriverCreateContext .

ExtraCreateParameter

Указатель на структуру ECP_LIST , которая содержит список дополнительных записей параметра создания (ECP). Важные сведения см. в следующем разделе Примечаний .

DeviceObjectHint

Если IO_DRIVER_CREATE_CONTEXT используется для передачи дополнительных параметров создания в подпрограмму FltCreateFileEx2 , этот член должен иметь значение NULL.

Если IO_DRIVER_CREATE_CONTEXT используется для передачи дополнительных параметров создания в подпрограмму IoCreateFileEx , этот член является указателем на объект устройства, которому будет отправлен запрос на создание. Объект устройства должен быть устаревшим фильтром или объектом устройства файловой системы в стеке драйверов файловой системы для тома, на котором находится файл или каталог. В случае IoCreateFileEx этот параметр является необязательным и может иметь значение NULL. Если этот параметр имеет значение NULL, запрос будет отправлен объекту устройства в верхней части стека драйверов.

TxnParameters

Указатель на транзакцию, которую необходимо связать с операцией создания. Операция создания будет частью транзакции, если значение этого элемента является допустимым указателем на транзакцию. Если значение этого элемента равно NULL, операция создания не будет частью транзакции.

SiloContext

Контейнер, в котором находится файл. Этот элемент появился в Windows 10 версии 1607.

Структуру IO_DRIVER_CREATE_CONTEXT можно выделить из выгружаемого или невыгружаемого пула. Подпрограмма IoInitializeDriverCreateContext должна инициализировать структуру IO_DRIVER_CREATE_CONTEXT, прежде чем можно будет использовать структуру.

Члены структуры IO_DRIVER_CREATE_CONTEXT (за исключением элемента Size ) в качестве дополнительных параметров подпрограмм IoCreateFileEx и FltCreateFileEx2 . Относительно интерфейса подпрограмм IoCreateFileEx и FltCreateFileEx2 могут быть полезны следующие сведения:

Структура ECP_LIST содержит список дополнительных записей параметров создания (ECP). Каждая запись ECP (структура контекста ECP) в списке ECP (ECP_LIST структура) функционирует как дополнительный параметр создания для IoCreateFileEx и FltCreateFileEx2.

Чтобы указать ECP в рамках операции создания, инициализируйте элемент ExtraCreateParameter структуры IO_DRIVER_CREATE_CONTEXT правильной подпрограммой:
- Для устаревших драйверов фильтров для выделения пула памяти для структуры ECP_LIST необходимо использовать подпрограмму FsRtlAllocateExtraCreateParameterList . Операционная система не освобождает ECP_LIST структуры автоматически. Вместо этого после выделения структуры ECP_LIST она должна быть освобождена с помощью подпрограммы FsRtlFreeExtraCreateParameterList .
- Для драйверов минифильтра подпрограмма FltAllocateExtraCreateParameterList должна использоваться для выделения пула памяти для структуры ECP_LIST. Операционная система не освобождает ECP_LIST структуры автоматически. Вместо этого после выделения структуры ECP_LIST она должна быть освобождена с помощью подпрограммы FltFreeExtraCreateParameterList .
Если используются ECP, их необходимо создавать, обрабатывать и освобождать с помощью соответствующих подпрограмм. Например, драйверы минифильтров используют подпрограмму FltInsertExtraCreateParameter для вставки записи ECP в список ECP. В следующем разделе См. также перечислены многие из этих обязательных процедур.

При возвращении из вызова IoCreateFileEx или FltCreateFileEx2 список ECP не изменяется и может быть передан в дополнительные вызовы IoCreateFileEx или FltCreateFileEx2 для новых операций создания.
Чтобы создать или открыть файл в контексте транзакции, задайте для элемента TxnParameters структуры IO_DRIVER_CREATE_CONTEXT значение, возвращаемое подпрограммой IoGetTransactionParameterBlock .