struttura FSRTL_PER_FILE_CONTEXT (ntifs.h)

Articolo
03/05/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;

Members

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 ogni 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 valore non NULL .

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 valore non NULL .

Commenti

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 valore OwnerID 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 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 così come è o incorporata in una struttura di contesto per file definita dal driver.

La struttura FSRTL_PER_FILE_CONTEXT può essere allocata da un pool di paging 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 non NULL .

InstanceId

PVOID

FreeCallback

PFREE_FUNCTION

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

Valore restituito

VUOTO

Nessuno.

Questa macro deve essere utilizzata prima di chiamare FsRtlInsertPerFileContext.

I writer di filtri devono scegliere un valore OwnerID 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 sull'uso e la creazione di oggetti di contesto, vedere Tracking Per-File Context in a Legacy File System Filter Driver.For more information about how to use and create context objects, see Tracking Per-File Context in a Legacy File System Filter Driver.