FltCreateSectionForDataScan-Funktion (fltkernel.h)

Artikel
12/21/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 Instanzzeiger für die Minifiltertreiberinstanz, deren 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 Typ des Zugriffs für das Abschnittsobjekt als eine oder mehrere der folgenden ACCESS_MASK Flags.

Flagge	Ermöglicht den Anrufer
SECTION_MAP_READ	Leseansichten des Abschnitts.
SECTION_MAP_WRITE	Schreibansichten des Abschnitts.
SECTION_QUERY	Fragen Sie das Abschnittsobjekt nach Informationen zum Abschnitt ab. Treiber sollten dieses Kennzeichen festlegen.
SECTION_ALL_ACCESS	Alle Aktionen, die von den vorherigen Flags definiert wurden, sowie die durch STANDARD_RIGHTS_REQUIRED definierten Aktionen. 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 InitializeObjectAttributes- Makro, 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 null sein.

Flagge	Bedeutung
PAGE_READONLY	Ermöglicht schreibgeschützten Zugriff auf den zugesicherten Seitenbereich. Ein Versuch, in die zugesicherte Region zu schreiben, führt zu einer Zugriffsverletzung. Wenn das System zwischen schreibgeschütztem Zugriff und Ausführung des Zugriffs unterscheidet, führt ein Versuch, Code in der zugesicherten Region auszuführen, zu einer Zugriffsverletzung.
PAGE_READWRITE	Ermöglicht sowohl Lese- als auch Schreibzugriff auf den zugesicherten Seitenbereich.

[in] AllocationAttributes

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

Flagge	Bedeutung
SEC_COMMIT	Weist 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 vom 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 der 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 zum Zeitpunkt der Erstellung des Abschnittsobjekts in Bytes empfängt. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_END_OF_FILE	Die Größe der durch den FileObject Parameter angegebenen Datei ist null.
STATUS_FILE_LOCK_CONFLICT	Die vom FileObject Parameter angegebene Datei ist gesperrt.
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan ein Poolzuordnungsfehler aufgetreten.
STATUS_INVALID_FILE_FOR_SECTION	Die durch den parameter FileObject 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 parameter AllocationAttributes angegeben.
STATUS_NOT_SUPPORTED	Das an diese Instanz angefügte Volume unterstützt keine Abschnittskontexte.
STATUS_PRIVILEGE_NOT_HELD	Der Aufrufer verfügte nicht über die erforderlichen Berechtigungen zum Erstellen eines Abschnittsobjekts mit dem im parameter DesiredAccess angegebenen Zugriff.
STATUS_FILE_IS_A_DIRECTORY	Die vom FileObject Parameter angegebene Datei ist ein Verzeichnis.
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Die durch Instance angegebene Filterinstanz verfügt bereits über einen geöffneten Abschnitt für den Datenstrom. Es wird nur ein Abschnitt pro Datenstrom und daher pro Instanz unterstützt.

Bemerkungen

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

FltCreateSectionForDataScan fügt das Handle in das Objekt (SectionHandle) in die Prozesshandletabelle 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 in der OBJECT_ATTRIBUTES-Struktur erstellt wurde, auf die ObjectAttributes verweist, ist ein Kernelhandle und kann nur über den Kernelmodus zugegriffen werden. Ein Handle, das ohne das OBJ_KERNEL_HANDLE Flag erstellt wurde, ist ein Benutzerhandle, auf das über den Benutzer- oder Kernelmodus zugegriffen werden kann. Ein Filter kann ein Benutzerhandle erstellen und dann zur Verarbeitung an eine Benutzermodusanwendung übergeben. Beispielsweise kann ein Virenscanmodul in einer Benutzermodusanwendung leben und Benutzerhandles aus einem Dateisystemfilter einspeist werden.

Bestimmte Situationen können auftreten, in denen das Öffnen eines Abschnitts mit der aktuellen Datei-E/A nicht kompatibel ist. Insbesondere kann die Datei-E/A, die eine Cachelöschung auslöst, zu einer inkoheren Zwischenspeicherung führen, wenn die Cachelöschung aufgrund eines geöffneten Abschnitts verhindert wird. Ein Minifilter kann eine optionale Rückrufroutine für Benachrichtigungen dieser Ereignisse bereitstellen. Der Minifiltertreiber implementiert eine PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK, um diese Benachrichtigungen zu empfangen. Konfliktbenachrichtigungen werden aktiviert, wenn das SectionNotificationCallback- Mitglied 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.

Anmerkung

Ein Abschnittsbenachrichtigungsrückruf kann auftreten, bevor FltCreateSectionForDataScan zurückgegeben wird. Ein Minifilter muss den Rückruf empfangen und den Fall behandeln können, in dem SectionHandle- und SectionObject- noch nicht gültig sind.

Wenn das von dieser Routine erstellte Abschnittsobjekt nicht mehr erforderlich ist, schließen Sie unbedingt das Handle des Abschnittsobjekts (SectionHandle), indem Sie die ZwClose Routine aufrufen und das Abschnittsobjekt selbst ableiten (SectionObject), indem Sie die ObDereferenceObject Routine aufrufen.

Übersichtsinformationen zum Erstellen zugeordneter Abschnitte und Ansichten des Arbeitsspeichers finden Sie unter Section Objects and Views. Weitere Informationen finden Sie in der Dokumentation zur CreateFileMapping Routine im Microsoft Windows SDK.

Wichtig

Minifilter dürfen keinen expliziten Abschnittskontext löschen, der an FltCreateSectionForDataScanübergeben wird. Rufen Sie nicht FltDeleteContext- auf, nachdem ein Abschnittskontext an FltCreateSectionForDataScanübergeben wird. Ein Abschnittskontext wird durch Aufrufen von FltCloseSectionForDataScan- aus einem Datenstrom entfernt.

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

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 8
Zielplattform-	Universal
Header-	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
IRQL-	<= APC_LEVEL