共用方式為


FltCreateSectionForDataScan 函式 (fltkernel.h)

FltCreateSectionForDataScan 例程會建立檔案的區段物件。 篩選管理員可以選擇性地同步處理 I/O 與建立的 區段。

語法

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
);

參數

[in] Instance

要擷取其內容之迷你篩選驅動程序實例的不透明實例指標。

[in] FileObject

開啟檔案的檔案物件。 區段物件將由指定的檔案支援。 這個參數是必要的,而且不能是 NULL。

[in] SectionContext

先前配置的區段內容的指標。

[in] DesiredAccess

區段物件的存取類型,做為下列一或多個 ACCESS_MASK 旗標。

旗標 允許呼叫端
SECTION_MAP_READ 讀取區段的檢視。
SECTION_MAP_WRITE 撰寫區段的檢視。
SECTION_QUERY 查詢區段物件以取得區段的相關信息。 驅動程式應設定此旗標。
SECTION_ALL_ACCESS 先前旗標所定義的所有動作,以及由STANDARD_RIGHTS_REQUIRED所定義的動作。 如需STANDARD_RIGHTS_REQUIRED的詳細資訊,請參閱 ACCESS_MASK

[in, optional] ObjectAttributes

指定物件名稱和其他屬性之選擇性 OBJECT_ATTRIBUTES 結構的指標。 使用 InitializeObjectAttributes 宏來初始化這個結構。

[in, optional] MaximumSize

這個參數保留給未來使用。

[in] SectionPageProtection

要放在區段中每個頁面的保護。 指定下列其中一個值。 這個參數是必要的,而且不能是零。

旗標 意義
PAGE_READONLY 啟用頁面認可區域的唯讀存取。 嘗試寫入已認可的區域會導致存取違規。 如果系統區分只讀存取和執行存取權,則嘗試在認可的區域中執行程式代碼會導致存取違規。
PAGE_READWRITE 啟用對已認可頁面區域的讀取和寫入存取。

[in] AllocationAttributes

SEC_XXX 旗標的位掩碼會決定區段的配置屬性。 指定下列一或多個值。 這個參數是必要的,而且不能是零。

旗標 意義
SEC_COMMIT 針對區段的所有頁面,在記憶體或磁碟上的分頁檔案中配置實體記憶體。 這是預設值。 請注意,此旗標是必要的,因此無法省略。
SEC_FILE FileObject 參數指定的檔案是對應的檔案。

[in] Flags

這個參數保留給未來使用。

[out] SectionHandle

呼叫端配置的變數指標,可接收區段的不透明句柄。 根據預設,區段句柄是使用者句柄。 如果呼叫端需要核心句柄,則必須將指標傳入 ObjectAttributes 參數中初始化的OBJECT_ATTRIBUTES結構,並設定OBJ_KERNEL_HANDLE旗標。

[out] SectionObject

呼叫端配置的變數指標,可接收區段物件的不透明指標。

[out, optional] SectionFileSize

呼叫端配置的變數指標,該變數會在建立區段物件時接收檔案的大小,以位元組為單位。 此參數是選擇性的,可以是 NULL。

傳回值

FltCreateSectionForDataScan 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值,例如下列其中一項。

傳回碼 Description
STATUS_END_OF_FILE FileObject 參數所指定的檔案大小為零。
STATUS_FILE_LOCK_CONFLICT FileObject 參數指定的檔案已鎖定。
STATUS_INSUFFICIENT_RESOURCES FltCreateSectionForDataScan 發生集區配置失敗。
STATUS_INVALID_FILE_FOR_SECTION FileObject 參數指定的檔案不支援區段。
STATUS_INVALID_PARAMETER 未註冊迷你篩選。
STATUS_INVALID_PARAMETER_8 針對 SectionPageProtection 參數指定的值無效。
STATUS_INVALID_PARAMETER_9 呼叫端為 AllocationAttributes 參數指定了無效的值。
STATUS_NOT_SUPPORTED 附加至這個實例的磁碟區不支援區段內容。
STATUS_PRIVILEGE_NOT_HELD 呼叫端沒有必要的許可權,無法建立具有 DesiredAccess 參數中所指定存取權的區段物件。
STATUS_FILE_IS_A_DIRECTORY FileObject 參數指定的檔案是目錄。
STATUS_FLT_CONTEXT_ALREADY_DEFINED 實例指定的篩選實例已經有數據流的開啟區段。 每個數據流只支援一個區段,因此支援每個實例。

備註

在呼叫 FltCreateSectionForDataScan 之前,minifilter 必須先呼叫 FltRegisterForDataScan 來註冊其磁碟區以進行數據掃描。 如同其他篩選內容元素, SectionContext 會先使用 FltAllocateContext 配置。

FltCreateSectionForDataScan 會將句柄插入物件 (SectionHandle) 至 呼叫 FltCreateSectionForDataScan 之線程的進程句柄數據表中。

句柄可以是使用者句柄或核心句柄。 在 ObjectAttributes 指向的OBJECT_ATTRIBUTES結構中設定OBJ_KERNEL_HANDLE所建立的句柄是核心句柄,而且只能從核心模式存取。 在沒有OBJ_KERNEL_HANDLE旗標的情況下建立的句柄是使用者句柄,可從使用者或核心模式存取。 篩選條件可以建立使用者句柄,然後將它傳遞給使用者模式應用程式進行處理。 例如,病毒掃描引擎可以存在於使用者模式應用程式中,並從檔案系統篩選提供使用者句柄。

在某些情況下,保留開啟的區段與目前的檔案 I/O 不相容。 特別是觸發快取清除的檔案 I/O,如果因為開啟區段而防止快取清除,可能會導致快取不一致。 迷你篩選程式可以提供選擇性的回呼例程來通知這些事件的通知。 迷你篩選驅動程式會實作 PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK 來接收這些通知。 如果註冊迷你篩選程式時,FLT_REGISTRATIONSectionNotificationCallback 成員設定為這個回呼例程,就會啟用衝突通知。 收到通知時,可以關閉 區段,以允許衝突的 I/O 作業繼續。

注意

在 FltCreateSectionForDataScan 傳回之前,可能會發生區段通知回呼。 迷你篩選必須能夠接收回呼,並處理 SectionHandleSectionObject 尚無效的情況。

當不再需要此例程所建立的 section 物件時,請務必藉由呼叫 ZwClose 例程來關閉 section 物件的句柄 (SectionHandle) ,並藉由呼叫 ObDereferenceObject 例程來取值 section 物件本身 (SectionObject) 。

如需建立記憶體對應區段和檢視的概觀資訊,請參閱 一節。 另請參閱 Microsoft Windows SDK 中 CreateFileMapping 例程的檔。

重要

迷你篩選不得明確刪除傳遞至 FltCreateSectionForDataScan 的區段內容。 將區段內容傳遞至 FltCreateSectionForDataScan 之後,請勿呼叫 FltDeleteContext。 在此案例中,區段內容會藉由呼叫 FltCloseSectionForDataScan ,從數據流解除分配和移除。

一般而言,區段應建立為唯讀。 特別是,如果只讀檔案位於交易中,而且迷你篩選不會建立只讀區段,則會捨棄對區段的寫入,而且不會包含在交易中。

規格需求

需求
最低支援的用戶端 Windows 8
目標平台 Universal
標頭 fltkernel.h (包含 Fltkernel.h)
程式庫 FltMgr.lib
IRQL <= APC_LEVEL

另請參閱

ACCESS_MASK

CcPurgeCacheSection

FLT_REGISTRATION

FltAllocateContext

FltCloseSectionForDataScan

FltRegisterForDataScan

ObDereferenceObject

PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK

ZwClose

ZwCreateSection