FltCreateSectionForDataScan-Funktion (fltkernel.h)

Artikel
02/27/2024

Die FltCreateSectionForDataScan-Routine erstellt ein Abschnittsobjekt für eine Datei. Der Filter-Manager kann optional E/A mit dem erstellten Abschnitt synchronisieren.

Syntax

NTSTATUS FLTAPI FltCreateSectionForDataScan(
  [in]            PFLT_INSTANCE      Instance,
  [in]            PFILE_OBJECT       FileObject,
  [in]            PFLT_CONTEXT       SectionContext,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags,
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize
);

Parameter

[in] Instance

Der undurchsichtige instance Zeiger für den Minifiltertreiber instance dessen Kontext abgerufen werden soll.

[in] FileObject

Das Dateiobjekt für eine geöffnete Datei. Das Abschnittsobjekt wird von der angegebenen Datei unterstützt. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] SectionContext

Ein Zeiger auf einen zuvor zugewiesenen Abschnittskontext.

[in] DesiredAccess

Der Zugriffstyp für das Abschnittsobjekt als mindestens eines der folgenden ACCESS_MASK Flags.

Flag	Ermöglicht dem Anrufer,
SECTION_MAP_READ	Leseansichten des Abschnitts.
SECTION_MAP_WRITE	Schreiben Sie Ansichten des Abschnitts.
SECTION_QUERY	Fragen Sie das Abschnittsobjekt nach Informationen zum Abschnitt ab. Treiber sollten dieses Flag festlegen.
SECTION_ALL_ACCESS	Alle Aktionen, die durch die vorherigen Flags definiert wurden, sowie die aktionen, die durch STANDARD_RIGHTS_REQUIRED definiert wurden. Weitere Informationen zu STANDARD_RIGHTS_REQUIRED finden Sie unter ACCESS_MASK.

[in, optional] ObjectAttributes

Ein Zeiger auf eine optionale OBJECT_ATTRIBUTES-Struktur , die den Objektnamen und andere Attribute angibt. Verwenden Sie das Makro InitializeObjectAttributes , um diese Struktur zu initialisieren.

[in, optional] MaximumSize

Dieser Parameter ist für die zukünftige Verwendung reserviert.

[in] SectionPageProtection

Der Schutz, der auf jeder Seite im Abschnitt platziert werden soll. Geben Sie einen der folgenden Werte an. Dieser Parameter ist erforderlich und darf nicht 0 sein.

Flag	Bedeutung
PAGE_READONLY	Ermöglicht schreibgeschützten Zugriff auf den zugesicherten Seitenbereich. Ein Versuch, in die region zu schreiben, führt zu einer Zugriffsverletzung. Wenn das System zwischen schreibgeschütztem Zugriff und Ausführungszugriff unterscheidet, führt ein Versuch, Code in der committeten Region auszuführen, zu einer Zugriffsverletzung.
PAGE_READWRITE	Ermöglicht Lese- und Schreibzugriff auf den zugesicherten Seitenbereich.

[in] AllocationAttributes

Bitmasken der SEC_XXX-Flags bestimmen die Zuordnungsattribute des Abschnitts. Geben Sie mindestens einen der folgenden Werte an. Dieser Parameter ist erforderlich und darf nicht 0 sein.

Flag	Bedeutung
SEC_COMMIT	Ordnet physischen Speicher im Arbeitsspeicher oder in der Auslagerungsdatei auf dem Datenträger für alle Seiten eines Abschnitts zu. Dies ist die Standardeinstellung. Beachten Sie, dass dieses Flag erforderlich ist und nicht weggelassen werden kann.
SEC_FILE	Die durch den FileObject-Parameter angegebene Datei ist eine zugeordnete Datei.

[in] Flags

Dieser Parameter ist für die zukünftige Verwendung reserviert.

[out] SectionHandle

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein undurchsichtiges Handle für den Abschnitt empfängt. Standardmäßig ist das Abschnittshandle ein Benutzerhandle. Wenn der Aufrufer ein Kernelhandle benötigt, muss er einen Zeiger an eine initialisierte OBJECT_ATTRIBUTES Struktur im ObjectAttributes-Parameter übergeben, wobei das OBJ_KERNEL_HANDLE-Flag festgelegt ist.

[out] SectionObject

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen Zeiger auf das Abschnittsobjekt empfängt.

[out, optional] SectionFileSize

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Größe der Datei in Bytes zum Zeitpunkt der Erstellung des Abschnittsobjekts empfängt. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

FltCreateSectionForDataScan gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück, z. B. einen der folgenden.

Rückgabecode	Beschreibung
STATUS_END_OF_FILE	Die Größe der Datei, die durch den FileObject-Parameter angegeben wird, ist 0.
STATUS_FILE_LOCK_CONFLICT	Die durch den FileObject-Parameter angegebene Datei ist gesperrt.
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan ist ein Poolzuordnungsfehler aufgetreten.
STATUS_INVALID_FILE_FOR_SECTION	Die vom FileObject-Parameter angegebene Datei unterstützt keine Abschnitte.
STATUS_INVALID_PARAMETER	Der Minifilter ist nicht registriert.
STATUS_INVALID_PARAMETER_8	Der für den SectionPageProtection-Parameter angegebene Wert ist ungültig.
STATUS_INVALID_PARAMETER_9	Der Aufrufer hat einen ungültigen Wert für den AllocationAttributes-Parameter angegeben.
STATUS_NOT_SUPPORTED	Das Volume, das diesem instance angefügt ist, unterstützt keine Abschnittskontexte.
STATUS_PRIVILEGE_NOT_HELD	Der Aufrufer verfügte nicht über die erforderlichen Berechtigungen zum Erstellen eines Abschnittsobjekts mit dem im DesiredAccess-Parameter angegebenen Zugriff.
STATUS_FILE_IS_A_DIRECTORY	Die durch den FileObject-Parameter angegebene Datei ist ein Verzeichnis.
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Der von Instance angegebene Filter instance hat bereits einen geöffneten Abschnitt für den Stream. Es wird nur ein Abschnitt pro Stream und damit pro instance unterstützt.

Hinweise

Vor dem Aufrufen von FltCreateSectionForDataScan muss ein Minifilter zuerst sein Volume für die Datenüberprüfung registrieren, indem Er FltRegisterForDataScan aufruft. Wie bei anderen Filterkontextelementen wird SectionContext zuerst FltAllocateContext zugeordnet.

FltCreateSectionForDataScan fügt das Handle in das Objekt (SectionHandle) in die Prozesshandle-Tabelle für den Thread ein, für den FltCreateSectionForDataScan aufgerufen wird.

Handles können entweder Benutzerhandles oder Kernelhandles sein. Ein Handle, das mit OBJ_KERNEL_HANDLE erstellt wurde, das in der OBJECT_ATTRIBUTES-Struktur festgelegt ist, auf die ObjectAttributes verweist, ist ein Kernelhandle, auf das nur im Kernelmodus zugegriffen werden kann. Ein Ohne das OBJ_KERNEL_HANDLE-Flag erstelltes Handle ist ein Benutzerhandle, auf das über den Benutzer- oder Kernelmodus zugegriffen werden kann. Ein Filter kann ein Benutzerhandle erstellen und es dann zur Verarbeitung an eine Benutzermodusanwendung übergeben. Beispielsweise kann eine Virenscan-Engine in einer Anwendung im Benutzermodus leben und Benutzerhandles aus einem Dateisystemfilter erhalten.

In bestimmten Situationen kann es vorkommen, dass das Öffnen eines Abschnitts mit der aktuellen Datei-E/A nicht kompatibel ist. Insbesondere datei-E/A, die eine Cachelöschung auslöst, können Cacheinkohärenz verursachen, wenn die Cachelöschung aufgrund eines geöffneten Abschnitts verhindert wird. Ein Minifilter kann eine optionale Rückrufroutine für Benachrichtigungen zu diesen Ereignissen bereitstellen. Der Minifiltertreiber implementiert eine PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK , um diese Benachrichtigungen zu empfangen. Konfliktbenachrichtigungen werden aktiviert, wenn das SectionNotificationCallback-Element von FLT_REGISTRATION auf diese Rückrufroutine festgelegt ist, wenn der Minifilter registriert wird. Wenn eine Benachrichtigung empfangen wird, kann der Abschnitt geschlossen werden, damit der konfliktierende E/A-Vorgang fortgesetzt werden kann.

Hinweis

Vor der Rückgabe von FltCreateSectionForDataScan kann ein Abschnittsbenachrichtigungsrückruf erfolgen. Ein Minifilter muss in der Lage sein, den Rückruf zu empfangen und den Fall zu behandeln, in dem SectionHandle und SectionObject noch nicht gültig sind.

Wenn das von dieser Routine erstellte Section-Objekt nicht mehr erforderlich ist, müssen Sie das Handle des Abschnittsobjekts (SectionHandle) schließen, indem Sie die ZwClose-Routine aufrufen und das Abschnittsobjekt selbst (SectionObject) durch Aufrufen der ObDereferenceObject-Routine deference zurückleiten .

Eine Übersicht zum Erstellen zugeordneter Abschnitte und Ansichten des Arbeitsspeichers finden Sie unter Abschnittsobjekte und Ansichten. Lesen Sie auch die Dokumentation zur CreateFileMapping-Routine im Microsoft Windows SDK.

Wichtig

Minifilter dürfen einen Abschnittskontext, der an FltCreateSectionForDataScan übergeben wurde, nicht explizit löschen. Rufen Sie FltDeleteContext nicht auf, nachdem ein Abschnittskontext an FltCreateSectionForDataScan übergeben wurde. Ein Abschnittskontext wird zugeordnet und aus einem Stream entfernt, indem in diesem Fall FltCloseSectionForDataScan aufgerufen wird.

Im Allgemeinen sollten Abschnitte schreibgeschützt erstellt werden. Insbesondere wenn sich eine schreibgeschützte Datei in einer Transaktion befindet und ein Minifilter keinen schreibgeschützten Abschnitt erstellt, wird ein Schreibvorgang in den Abschnitt verworfen und nicht als Teil der Transaktion eingeschlossen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8
Zielplattform	Universell
Header	fltkernel.h (include Fltkernel.h)
Bibliothek	FltMgr.lib
IRQL	<= APC_LEVEL