estrutura IO_DRIVER_CREATE_CONTEXT (ntddk.h)

Artigo
03/13/2023

A estrutura IO_DRIVER_CREATE_CONTEXT é usada para passar parâmetros adicionais para as rotinas IoCreateFileEx e FltCreateFileEx2 . Essa estrutura é opcional.

A rotina IoCreateFileEx é usada por drivers de filtro herdados e a rotina FltCreateFileEx2 é usada por drivers de minifiltro.

Sintaxe

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;

Membros

Size

Um membro somente leitura inicializado pela rotina IoInitializeDriverCreateContext .

ExtraCreateParameter

Um ponteiro para uma estrutura ECP_LIST , que contém uma lista de entradas ECP (parâmetro de criação extra). Consulte a seção Comentários a seguir para obter informações importantes .

DeviceObjectHint

Se IO_DRIVER_CREATE_CONTEXT estiver sendo usado para passar parâmetros de criação adicionais para a rotina FltCreateFileEx2 , esse membro deverá ser NULL.

Se IO_DRIVER_CREATE_CONTEXT estiver sendo usado para passar parâmetros de criação adicionais para a rotina IoCreateFileEx , esse membro será um ponteiro para o objeto do dispositivo para o qual a solicitação de criação será enviada. O objeto do dispositivo deve ser um objeto de dispositivo de sistema de arquivos ou de filtro herdado na pilha de driver do sistema de arquivos para o volume no qual o arquivo ou diretório reside. No caso IoCreateFileEx , esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, a solicitação será enviada para o objeto do dispositivo na parte superior da pilha do driver.

TxnParameters

Um ponteiro para uma transação que você deseja associar à operação de criação. A operação de criação fará parte da transação se o valor desse membro for um ponteiro válido para a transação. Se o valor desse membro for NULL, a operação de criação não fará parte de uma transação.

SiloContext

O contêiner no qual o arquivo reside. Este membro foi introduzido no Windows 10, versão 1607.

Comentários

A estrutura IO_DRIVER_CREATE_CONTEXT pode ser alocada do pool paginado ou nãopagado. A rotina IoInitializeDriverCreateContext deve inicializar a estrutura IO_DRIVER_CREATE_CONTEXT antes que a estrutura possa ser usada.

Os membros da estrutura IO_DRIVER_CREATE_CONTEXT (excluindo o membro Size ) funcionam como parâmetros adicionais para as rotinas IoCreateFileEx e FltCreateFileEx2 . Em relação à interface da rotina IoCreateFileEx e FltCreateFileEx2 , as seguintes informações podem ser úteis:

Uma estrutura ECP_LIST contém uma lista de entradas ECP (parâmetro de criação extra). Cada entrada ECP (estrutura de contexto ECP) na lista ECP (estrutura ECP_LIST) funciona como um parâmetro de criação adicional para IoCreateFileEx e FltCreateFileEx2.

Para especificar um ECP como parte de uma operação de criação, inicialize o membro ExtraCreateParameter da estrutura IO_DRIVER_CREATE_CONTEXT com a rotina correta:
- Para drivers de filtro herdados, a rotina FsRtlAllocateExtraCreateParameterList deve ser usada para alocar o pool de memória para a estrutura de ECP_LIST. O sistema operacional não libera automaticamente ECP_LIST estruturas. Em vez disso, depois que a estrutura ECP_LIST for alocada, ela deverá eventualmente ser liberada usando a rotina FsRtlFreeExtraCreateParameterList .
- Para drivers de minifiltro, a rotina FltAllocateExtraCreateParameterList deve ser usada para alocar o pool de memória para a estrutura ECP_LIST. O sistema operacional não libera automaticamente ECP_LIST estruturas. Em vez disso, depois que a estrutura ECP_LIST for alocada, ela deverá eventualmente ser liberada usando a rotina FltFreeExtraCreateParameterList .
Se os ECPs forem usados, eles deverão ser criados, manipulados e liberados usando as rotinas apropriadas. Por exemplo, os drivers de minifiltro usam a rotina FltInsertExtraCreateParameter para inserir uma entrada ECP em uma lista ECP. A seção Veja também a seguir lista muitas dessas rotinas necessárias.

Após retornar de uma chamada para IoCreateFileEx ou FltCreateFileEx2, a lista ECP é inalterada e pode ser passada para chamadas adicionais IoCreateFileEx ou FltCreateFileEx2 para novas operações de criação.
Para criar ou abrir um arquivo no contexto de uma transação, defina o membro TxnParameters da estrutura IO_DRIVER_CREATE_CONTEXT para o valor retornado pela rotina IoGetTransactionParameterBlock .