FSRTL_PER_FILE_CONTEXT-Struktur (ntifs.h)

Artikel
02/29/2024

Ein Legacy-Dateisystemfiltertreiber kann eine FSRTL_PER_FILE_CONTEXT-Struktur verwenden, um einer geöffneten Datei treiberspezifische Kontextinformationen 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;

Member

Links

Ein Link für diese Struktur in der Liste aller Kontextstrukturen pro Datei, die derselben Datei zugeordnet sind. FsRtlInsertPerFileContext fügt diesen Member 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 diesen Member auf einen Wert ungleich NULL festlegen.

InstanceId

Ein Zeiger auf einen vom Filtertreiber zugeordneten Puffer, der verwendet werden kann, um zwischen den Kontextstrukturen pro Datei zu unterscheiden, die vom gleichen 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 diesen Member auf einen Wert ungleich NULL festlegen.

Hinweise

Um Einer Datei Kontextinformationen zuzuordnen, ordnet ein Legacyfiltertreiber zunächst eine FSRTL_PER_FILE_CONTEXT-Struktur zu und initialisiert sie mithilfe von FsRtlInsertPerFileContext. Der Treiber verwendet dann FsRtlInsertPerFileContext , um dieses FSRTL_PER_FILE_CONTEXT -Objekt der Datei zuzuordnen. Wenn das System das Dateikontextobjekt für eine Datei abreißt, ruft es FsRtlTeardownPerFileContexts auf, wodurch die FreeCallback-Routine aufgerufen wird, 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 Treiber- 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 unverändert verwendet oder in eine treiberdefinierte Dateikontextstruktur eingebettet werden.

Die FSRTL_PER_FILE_CONTEXT-Struktur kann aus einem ausgelagerten oder nicht ausgelagerten Pool zugeordnet werden.

Das FsRtlInitPerFileContext-Makro initialisiert eine FSRTL_PER_FILE_CONTEXT-Struktur .

Parameter

FileContext

FSRTL_PER_FILE_CONTEXT

Das FSRTL_PER_FILE_CONTEXT zu initialisierende Objekt.

OwnerID

PVOID

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

InstanceId

PVOID

FreeCallback

PFREE_FUNCTION

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

Rückgabewert

VOID

Keine.

Dieses Makro muss vor dem Aufrufen von FsRtlInsertPerFileContext verwendet werden.

Filterautoren sollten einen OwnerID-Wert auswählen, der sowohl sinnvoll als auch praktisch ist, z. B. die Adresse eines Treiber- 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 zum Verwenden und Erstellen von Kontextobjekten finden Sie unter Nachverfolgen Per-File Kontext in einem Legacy-Dateisystemfiltertreiber.