estrutura FSRTL_PER_FILE_CONTEXT (ntifs.h)

Artigo
08/07/2023

Um driver de filtro do sistema de arquivos herdado pode usar uma estrutura FSRTL_PER_FILE_CONTEXT para associar informações de contexto específicas do driver a um arquivo aberto.

Sintaxe

typedef struct _FSRTL_PER_FILE_CONTEXT {
  LIST_ENTRY     Links;
  PVOID          OwnerId;
  PVOID          InstanceId;
  PFREE_FUNCTION FreeCallback;
} FSRTL_PER_FILE_CONTEXT, *PFSRTL_PER_FILE_CONTEXT;

Membros

Links

Um link para essa estrutura na lista de todas as estruturas de contexto por arquivo associadas ao mesmo arquivo. FsRtlInsertPerFileContext insere esse membro na lista de todas as estruturas de contexto por arquivo para um arquivo.

OwnerId

Um ponteiro para um buffer alocado pelo driver de filtro que identifica exclusivamente o proprietário da estrutura de contexto por arquivo. O formato dessa variável é específico do driver de filtro. Os drivers de filtro devem definir esse membro como um valor não NULL .

InstanceId

Um ponteiro para um buffer alocado pelo driver de filtro que pode ser usado para distinguir entre as estruturas de contexto por arquivo criadas pelo mesmo driver de filtro. O formato dessa variável é específico do driver de filtro. Os drivers de filtro podem definir esse membro como NULL.

FreeCallback

Um ponteiro para uma rotina de retorno de chamada que libera a estrutura de contexto por arquivo. Os drivers de filtro devem definir esse membro como um valor não NULL .

Comentários

Para associar informações de contexto a um arquivo, um driver de filtro herdado primeiro aloca uma estrutura FSRTL_PER_FILE_CONTEXT e inicializa-a usando FsRtlInsertPerFileContext. Em seguida, o driver usa FsRtlInsertPerFileContext para associar esse objeto FSRTL_PER_FILE_CONTEXT ao arquivo. Quando o sistema remove o objeto de contexto de arquivo de um arquivo, ele chama FsRtlTeardownPerFileContexts , que chama a rotina FreeCallback especificada no objeto FSRTL_PER_FILE_CONTEXT . Esse retorno de chamada deve liberar o objeto de contexto específico do driver.

Os gravadores de filtro devem escolher um valor OwnerID significativo e conveniente, como o endereço de um objeto de driver ou objeto de dispositivo.

Os gravadores de filtro devem escolher um valor InstanceID que seja significativo e conveniente, como o endereço do objeto de contexto de arquivo para o arquivo. Use a macro FsRtlGetPerFileContextPointer para recuperar esse endereço de um objeto de arquivo.

A estrutura FSRTL_PER_FILE_CONTEXT pode ser usada como está ou inserida em uma estrutura de contexto por arquivo definida pelo driver.

A estrutura FSRTL_PER_FILE_CONTEXT pode ser alocada do pool paginado ou nãopagado.

A macro FsRtlInitPerFileContext inicializa uma estrutura FSRTL_PER_FILE_CONTEXT .

Parâmetros

FileContext

FSRTL_PER_FILE_CONTEXT

O objeto FSRTL_PER_FILE_CONTEXT a ser inicializado.

OwnerId

PVOID

Um ponteiro para uma variável alocada pelo driver de filtro que identifica exclusivamente o proprietário da estrutura de contexto por arquivo. O formato é específico do driver de filtro. Esse parâmetro deve ter um valor não NULL .

InstanceId

PVOID

FreeCallback

PFREE_FUNCTION

Um ponteiro para uma rotina de retorno de chamada que libera a estrutura de contexto por arquivo.

Retornar valor

VOID

Nenhum.

Essa macro deve ser usada antes de chamar FsRtlInsertPerFileContext.

Os gravadores de filtro devem escolher um valor OwnerID significativo e conveniente, como o endereço de um objeto de driver ou objeto de dispositivo.

Os gravadores de filtro devem usar um valor InstanceID que seja significativo e conveniente, como o endereço do objeto de contexto de arquivo para o arquivo. Use a macro FsRtlGetPerFileContextPointer para recuperar esse endereço de um objeto de arquivo.

Para obter mais informações sobre como usar e criar objetos de contexto, consulte Acompanhamento Per-File contexto em um driver de filtro do sistema de arquivos herdado.