struttura FSRTL_PER_FILE_CONTEXT (ntifs.h)

Articolo
12/21/2024

Un driver di filtro del file system legacy può usare una struttura di FSRTL_PER_FILE_CONTEXT per associare informazioni di contesto specifiche del driver a un file aperto.

Sintassi

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

Membri

Links

Collegamento per questa struttura nell'elenco di tutte le strutture di contesto per file associate allo stesso file. FsRtlInsertPerFileContext inserisce questo membro nell'elenco di tutte le strutture di contesto per file per un file.

OwnerId

Puntatore a un buffer allocato dal driver di filtro che identifica in modo univoco il proprietario della struttura del contesto per file. Il formato di questa variabile è specifico del driver di filtro. I driver di filtro devono impostare questo membro su un valoreNULL.

InstanceId

Puntatore a un buffer allocato dal driver di filtro che può essere usato per distinguere tra le strutture di contesto per file create dallo stesso driver di filtro. Il formato di questa variabile è specifico del driver di filtro. I driver di filtro possono impostare questo membro su NULL.

FreeCallback

Puntatore a una routine di callback che libera la struttura del contesto per file. I driver di filtro devono impostare questo membro su un valoreNULL.

Osservazioni

Per associare le informazioni di contesto a un file, un driver di filtro legacy alloca prima una struttura di FSRTL_PER_FILE_CONTEXT e la inizializza usando FsRtlInsertPerFileContext. Il driver usa quindi FsRtlInsertPerFileContext per associare tale oggetto FSRTL_PER_FILE_CONTEXT al file. Quando il sistema rimuove l'oggetto contesto di file per un file, chiama FsRtlTeardownPerFileContexts che chiama la routine FreeCallback specificata nell'oggetto FSRTL_PER_FILE_CONTEXT. Tale callback deve liberare l'oggetto contesto specifico del driver.

I writer di filtri devono scegliere un OwnerID valore significativo e pratico, ad esempio l'indirizzo di un oggetto driver o di un oggetto dispositivo.

I writer di filtri devono scegliere un valore InstanceID significativo e pratico, ad esempio l'indirizzo dell'oggetto contesto di file per il file. Utilizzare la macro FsRtlGetPerFileContextPointer per recuperare tale indirizzo da un oggetto file.

La struttura FSRTL_PER_FILE_CONTEXT può essere usata as-iso incorporata in una struttura di contesto definita dal driver per file.

La struttura FSRTL_PER_FILE_CONTEXT può essere allocata da un pool di pagine o non di paging.

La macro FsRtlInitPerFileContext inizializza una struttura FSRTL_PER_FILE_CONTEXT.

Parametri

FileContext

FSRTL_PER_FILE_CONTEXT

Oggetto FSRTL_PER_FILE_CONTEXT da inizializzare.

OwnerId

PVOID

Puntatore a una variabile allocata dal driver di filtro che identifica in modo univoco il proprietario della struttura del contesto per file. Il formato è specifico del driver di filtro. Questo parametro deve avere un valore di NULL non.

InstanceId

PVOID

FreeCallback

PFREE_FUNCTION

Puntatore a una routine di callback che libera la struttura del contesto per file.

Valore restituito

VOID

Nessuno.

Questa macro deve essere utilizzata prima di chiamare FsRtlInsertPerFileContext.

I writer di filtri devono scegliere un OwnerID valore significativo e pratico, ad esempio l'indirizzo di un oggetto driver o di un oggetto dispositivo.

I writer di filtri devono usare un valore InstanceID significativo e pratico, ad esempio l'indirizzo dell'oggetto contesto di file per il file. Utilizzare la macro FsRtlGetPerFileContextPointer per recuperare tale indirizzo da un oggetto file.

Per altre informazioni su come usare e creare oggetti contesto, vedere Per-File Context in a Legacy File System Filter Driver.