FSRTL_PER_FILE_CONTEXT Struktur (ntifs.h)

Artikel
12/21/2024

Ein älteren Dateisystemfiltertreiber kann eine FSRTL_PER_FILE_CONTEXT Struktur verwenden, um treiberspezifische Kontextinformationen einer geöffneten Datei zuzuordnen.

Syntax

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

Angehörige

Links

Ein Link für diese Struktur in der Liste aller Kontextstrukturen pro Datei, die derselben Datei zugeordnet sind. FsRtlInsertPerFileContext fügt dieses Element in die Liste aller Dateikontextstrukturen für eine Datei ein.

OwnerId

Ein Zeiger auf einen vom Filtertreiber zugewiesenen Puffer, der den Besitzer der Kontextstruktur pro Datei eindeutig identifiziert. Das Format dieser Variablen ist filtertreiberspezifisch. Filtertreiber müssen dieses Element auf einen Wert ohneNULL festlegen.

InstanceId

Ein Zeiger auf einen vom Filtertreiber zugewiesenen Puffer, der verwendet werden kann, um zwischen den Dateikontextstrukturen zu unterscheiden, die vomselben Filtertreiber erstellt werden. Das Format dieser Variablen ist filtertreiberspezifisch. Filtertreiber können dieses Element auf NULL-festlegen.

FreeCallback

Ein Zeiger auf eine Rückrufroutine, die die Kontextstruktur pro Datei freigibt. Filtertreiber müssen dieses Element auf einen Wert ohneNULL festlegen.

Bemerkungen

Um Kontextinformationen einer Datei zuzuordnen, weist ein Legacyfiltertreiber zunächst eine FSRTL_PER_FILE_CONTEXT Struktur zu und initialisiert sie mithilfe von FsRtlInsertPerFileContext. Der Treiber verwendet dann FsRtlInsertPerFileContext-, um das FSRTL_PER_FILE_CONTEXT Objekt der Datei zuzuordnen. Wenn das System das Dateikontextobjekt für eine Datei abreißt, ruft es FsRtlTeardownPerFileContexts auf, die die FreeCallback Routine aufruft, die im FSRTL_PER_FILE_CONTEXT-Objekt angegeben ist. Dieser Rückruf muss das treiberspezifische Kontextobjekt freigeben.

Filterautoren sollten einen OwnerID Wert auswählen, der sowohl sinnvoll als auch praktisch ist, z. B. die Adresse eines Treiberobjekts oder Geräteobjekts.

Filterautoren sollten einen InstanceID- Wert auswählen, der sowohl sinnvoll als auch praktisch ist, z. B. die Adresse des Dateikontextobjekts für die Datei. Verwenden Sie das FsRtlGetPerFileContextPointer Makro, um diese Adresse aus einem Dateiobjekt abzurufen.

Die FSRTL_PER_FILE_CONTEXT-Struktur kann as-isverwendet oder in eine treiberdefinierte Kontextstruktur pro Datei eingebettet werden.

Die FSRTL_PER_FILE_CONTEXT Struktur kann aus seitenseitigem oder nicht seitengebundenen Pool zugeordnet werden.

Das FsRtlInitPerFileContext Makro initialisiert eine FSRTL_PER_FILE_CONTEXT Struktur.

Parameter

FileContext-

FSRTL_PER_FILE_CONTEXT

Das zu initialisierende FSRTL_PER_FILE_CONTEXT-Objekt.

OwnerId-

PVOID-

Ein Zeiger auf eine vom Filtertreiber zugewiesene Variable, die den Besitzer der Kontextstruktur pro Datei eindeutig identifiziert. Das Format ist filtertreiberspezifisch. Dieser Parameter muss einen Wert ohneNULL aufweisen.

InstanceId-

PVOID-

FreeCallback-

PFREE_FUNCTION

Ein Zeiger auf eine Rückrufroutine, die die Kontextstruktur pro Datei freigibt.

Rückgabewert

VOID

Nichts.

Dieses Makro muss verwendet werden, bevor FsRtlInsertPerFileContextaufgerufen wird.

Filterautoren sollten einen OwnerID Wert auswählen, der sowohl sinnvoll als auch praktisch ist, z. B. die Adresse eines Treiberobjekts oder Geräteobjekts.

Filterautoren sollten einen InstanceID- Wert verwenden, der sowohl sinnvoll als auch praktisch ist, z. B. die Adresse des Dateikontextobjekts für die Datei. Verwenden Sie das FsRtlGetPerFileContextPointer Makro, um diese Adresse aus einem Dateiobjekt abzurufen.

Weitere Informationen zur Verwendung und Erstellung von Kontextobjekten finden Sie unter Tracking Per-File Context in einem Legacy File System Filter Driver.