FltCreateSectionForDataScan function

Download EaseFilter Filter Driver SDK Setup File
Download EaseFilter Filter Driver SDK Zip File

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

Parameters

Instance

The opaque instance pointer for the minifilter driver instance whose context is to be retrieved.

FileObject

The file object for an open file. The section object will be backed by the specified file. This parameter is required and cannot be NULL.

SectionContext

A pointer to a previously allocated section context.

DesiredAccess

The type of access for the section object as one or more of the following ACCESS_MASK flags.

ObjectAttributes

A pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use the InitializeObjectAttributes macro to initialize this structure. Because FltCreateSectionForDataScan inserts this object into the process handle table, the caller must specify the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.

MaximumSize

This parameter is reserved for future use.

SectionPageProtection

The protection to place on each page in the section. Specify one of the following values. This parameter is required and cannot be zero.

AllocationAttributes

Bitmasks of the SEC_XXX flags determine the allocation attributes of the section. Specify one or more of the following values. This parameter is required and cannot be zero.

Flags

This parameter is reserved for future use.

SectionHandle

A pointer to a caller-allocated variable that receives an opaque handle to the section handle.

SectionObject

A pointer to a caller-allocated variable that receives an opaque pointer to the section object.

SectionFileSize

A pointer to a caller-allocated variable that receives the size, in bytes, of the file at the time the section object was created. This parameter is optional and can be NULL.

Return value

FltCreateSectionForDataScan returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following.

Remarks

Prior to calling FltCreateSectionForDataScan, a minifilter must first register its volume for data scanning by calling FltRegisterForDataScan. As with other filter context elements, SectionContext is first allocated with FltAllocateContext.

Certain situations can occur where holding a section open is incompatible with current file I/O. In particular, file I/O that triggers a cache purge can cause cache incoherency if the cache purge is prevented because of an open section. A minifilter can provide an optional callback routine for notifications of these events. The minifilter driver implements a PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK to receive these notifications. Conflict notifications are enabled if the SectionNotificationCallback member of FLT_REGISTRATION is set to this callback routine when the minifilter is registered. When a notification is received, the section can be closed to allow the conflicting I/O operation to continue.

When the section object created by this routine is no longer necessary, be sure to close the section object's handle (SectionHandle) by calling the ZwClose routine and dereference the section object itself (SectionObject) by calling the ObDereferenceObject routine.

For overview information on creating mapped sections and views of memory, see Section Objects and Views. Also, see the documentation for the CreateFileMapping routine in the Microsoft Windows SDK.

Requirements