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

Статья
12/21/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

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

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 и интерфейса подпрограммы FltCreateFileEx 2, могут быть полезны следующие сведения:

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

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

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