FltCreateFileEx2 函式 (fltkernel.h)

發行項
02/29/2024

迷你篩選驅動程式會呼叫 FltCreateFileEx2 來建立新檔案或開啟現有的檔案。此例程包含選擇性的建立內容參數 (ECP) 。

語法

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

參數

[in] Filter

呼叫端的不透明篩選指標。

[in, optional] Instance

要傳送建立要求之迷你篩選驅動程序實例的不透明實例指標。實例必須附加至檔案或目錄所在的磁碟區。這個參數是選擇性的，而且可以是 NULL。如果此參數為 NULL，要求會傳送至磁碟區文件系統驅動程式堆疊頂端的裝置物件。如果此參數為非 NULL，則要求只會傳送至附加在指定實例下方的迷你篩選驅動程序實例。

[out] FileHandle

呼叫端配置變數的指標，如果 呼叫 FltCreateFileEx2 成功，則會接收檔句柄。

[out, optional] FileObject

呼叫端配置的變數指標，如果 呼叫 FltCreateFileEx2 成功，就會接收檔案物件指標。這個參數是選擇性的，而且可以是 NULL。

[in] DesiredAccess

旗標的位掩碼，指定呼叫端所需的檔案或目錄存取類型。如需此參數的詳細資訊和旗標值清單，請參閱IoCreateFileEx的 DesiredAccess 參數。

[in] ObjectAttributes

已使用 InitializeObjectAttributes 初始化之不透明OBJECT_ATTRIBUTES結構的指標。如需詳細資訊和每個結構成員的描述，請參閱IoCreateFileEx的 ObjectAttributes 參數。

[out] IoStatusBlock

接收最終完成狀態和所要求作業相關信息 之IO_STATUS_BLOCK 結構的指標。如需此參數的詳細資訊，請參閱IoCreateFileEx的IoStatusBlock參數。

[in, optional] AllocationSize

選擇性地指定檔案數據流的初始配置大小，以位元組為單位。除非正在建立、覆寫或取代檔案，否則非零值沒有任何作用。

[in] FileAttributes

指定一或多個FILE_ATTRIBUTE_XXX 旗標，代表如果您要建立、取代或覆寫檔案時所要設定的檔案屬性。如需詳細資訊和旗標清單，請參閱IoCreateFileEx的FileAttributes參數。

[in] ShareAccess

指定呼叫端所需的檔案共用存取類型、零或一個，或旗標的組合。如需詳細資訊和旗標清單，請參閱IoCreateFileEx的ShareAccess參數。

[in] CreateDisposition

指定值，根據檔案是否已經存在，決定要採取的動作。如需可能的值清單，請參閱IoCreateFileEx的 Disposition 參數。

[in] CreateOptions

指定要在建立或開啟檔案時套用的選項。此參數是IoCreateFileEx的 CreateOptions 參數所列出的旗標相容組合。

[in, optional] EaBuffer

呼叫端提供的 FILE_FULL_EA_INFORMATION 緩衝區指標，其中包含要套用至檔案之 EA) 擴充屬性 (屬性。

[in] EaLength

EaBuffer 的長度，以位元組為單位。

[in] Flags

指定要在建立要求期間使用的選項。如需可能的選項清單，請參閱IoCreateFileEx的Options參數。

[in, optional] DriverContext

IoInitializeDriverCreateContext 已初始化IO_DRIVER_CREATE_CONTEXT結構的選擇性指標。

傳回值

FltCreateFileEx2 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值。如需可能的傳回碼清單，請參閱IoCreateFileEx的傳回值一節。

注意

FltCreateFileEx2 可能會傳回STATUS_FILE_LOCK_CONFLICT做為傳回值，或在 IoStatusBlock 參數所指向之IO_STATUS_BLOCK結構的 Status 成員中。只有在NTFS記錄檔已滿，且 FltCreateFileEx2 嘗試處理這種情況時，才會發生錯誤。

備註

FltCreateFileEx2 類似於 FltCreateFile 和 FltCreateFileEx，不同之處在於它支援 DriverContext 輸入參數。

若要在建立作業中指定 ECP，請使用 FltAllocateExtraCreateParameterList 例程，初始化 IO_DRIVER_CREATE_CONTEXT 結構的 ExtraCreateParameter 成員。如果使用 ECP，則必須使用適當的例程來建立、操作和釋放它們。

在 FltCreateFileEx2 呼叫端下方篩選驅動程式不應在呼叫端上新增或刪除 ECP。因此，從 呼叫 FltCreateFileEx2 傳回時，ECP 清單應該保持不變，而且可能會傳遞給其他建立作業的 FltCreateFileEx2 呼叫。請注意，操作系統不會自動解除分配 ECP 清單結構 - FltCreateFileEx2 的呼叫端必須藉由呼叫 FltFreeExtraCreateParameterList 例程來解除分配此結構。

若要在交易的內容中建立/開啟檔案，請將 IO_DRIVER_CREATE_CONTEXT 結構的 TxnParameters 成員設定為 IoGetTransactionParameterBlock 例程所傳回的值。

FltCreateFileEx2 只會將建立要求傳送至附加在指定迷你篩選驅動程序實例和文件系統下方的實例。上面附加的指定實例和實例不會收到建立要求。如果未指定任何實例，則要求會移至堆疊頂端，並由所有實例和文件系統接收。

有兩種替代方式可以指定要使用 FltCreateFileEx2 建立或開啟的檔名：

作為完整路徑名稱，提供於輸入 ObjectAttributes 的 ObjectName 成員中。
路徑名稱，相對於輸入 ObjectAttributes之 RootDirectory 成員中句柄所代表的目錄檔案。

任何從 FltCreateFileEx2 取得的 FileHandle 最終都必須藉由呼叫 FltClose 來釋放。此外，呼叫 ObDereferenceObject 時，任何傳回的 FileObject 指標都必須取值。

未在系統進程內容中執行的驅動程式例程必須為 FltCreateFileEx2 的 ObjectAttributes 參數設定 OBJ_KERNEL_HANDLE 屬性。設定此屬性會將 FltCreateFileEx2 所傳回的句柄，限制為在內核模式中執行的進程。否則，進程可以在其內容中執行驅動程式的句柄來存取。

注意

請勿使用非 NULL 最上層 IRP 值呼叫此例程，因為這可能會導致系統死結。

某些 DesiredAccess 旗標和旗標組合具有下列效果：

若要讓呼叫端等候傳回的 FileHandle 設定為 Signaled 狀態，以同步處理 I/O 完成，必須設定 SYNCHRONIZE 旗標。
如果只設定FILE_APPEND_DATA和 SYNCHRONIZE 旗標，則呼叫端只能寫入檔案結尾，並忽略對檔案寫入要求的任何位移資訊。不過，此檔案會視需要自動擴充此類型的寫入作業。
設定檔案的FILE_WRITE_DATA旗標，也可允許在檔案結尾以外的寫入要求發生。此檔案也會針對這種類型的寫入要求自動擴充。
如果只設定FILE_EXECUTE和 SYNCHRONIZE 旗標，呼叫端就無法使用 FileHandle 參數中傳回的句柄，直接讀取或寫入檔案中的任何數據。也就是說，檔案上的所有作業都必須使用系統分頁 I/O 來讀取或寫入檔案數據。

ShareAccess 參數會判斷個別線程是否可以同時存取相同的檔案。如果這兩個檔案開啟者都具備以指定方式存取檔案的許可權，則可以成功開啟和共用檔案。如果 FltCreateFileEx2 的原始呼叫端未指定FILE_SHARE_READ、FILE_SHARE_WRITE或FILE_SHARE_DELETE，則無法對檔案執行其他開啟作業，因為原始呼叫端具有檔案的獨佔存取權。

若要成功開啟共享檔案，要求之 DesiredAccess 至檔案必須與所有先前尚未透過 FltClose 發行之開啟要求的 DesiredAccess 和 ShareAccess 規格相容。也就是說，指定給 FltCreateFileEx2 指定給指定檔案的 DesiredAccess 參數不得與其他檔案開啟者不允許的存取相衝突。

注意

如果在 Flags 參數中指定IO_IGNORE_SHARE_ACCESS_CHECK，I/O 管理員會忽略 ShareAccess 參數。不過，檔案系統仍可能會執行存取檢查。因此，請務必指定 ShareAccess參數想要的共用模式，即使使用 IO_IGNORE_SHARE_ACCESS_CHECK 旗標也一樣。此外，請注意，指定IO_IGNORE_SHARE_ACCESS_CHECK時，文件系統不會追蹤目前開啟所需的存取權或共用存取。因此，相同檔案上的後續開啟呼叫可能會成功。

CreateDisposition 值FILE_SUPERSEDE要求呼叫端具有現有檔案物件的 DELETE 存取權。如果是的話，在現有檔案上成功呼叫 FltCreateFileEx2 並FILE_SUPERSEDE會有效地刪除該檔案，然後重新建立該檔案。這表示，如果檔案已經由另一個線程開啟，它會指定 shareAccess參數並設定FILE_SHARE_DELETE旗標來開啟檔案。請注意，這種類型的處置與覆寫檔案的POSIX樣式一致。

CreateDisposition 值FILE_OVERWRITE_IF和FILE_SUPERSEDE類似。如果使用現有的檔案和其中一個 CreateDisposition 值呼叫 FltCreateFileEx2，則會取代檔案。

覆寫檔案的語意相當於取代作業，但下列情況除外：

呼叫端必須具有檔案的寫入許可權，而不是刪除存取權。這表示，如果檔案已由另一個線程開啟，則會開啟檔案，並在輸入 ShareAccess 參數中設定FILE_SHARE_WRITE旗標。
指定的檔案屬性會與已經使用位 OR 運算套用至檔案的屬性結合。這表示如果檔案已由另一個線程開啟， 則 FltCreateFileEx2 的後續呼叫端無法停用現有的 FileAttributes 旗標，但可以啟用相同檔案的其他旗標。請注意，此覆寫檔案的樣式與 MS-DOS、Windows 3.1 和 OS/2 一致。

CreateOptions FILE_DIRECTORY_FILE 值會指定要建立或開啟的檔案是目錄檔案。建立目錄檔案時，文件系統會在磁碟上建立適當的結構，以代表該特定文件系統的磁碟上結構的空白目錄。如果指定此選項且要開啟的指定檔案不是目錄檔案，或呼叫端指定不一致的 CreateOptions 或 CreateDisposition 值， 則 FltCreateFileEx2 的呼叫會失敗。

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 旗標可防止文件系統代表呼叫端執行任何中繼緩衝。指定此值會將呼叫端參數的某些限制放在其他 Flt。檔案 例程或 Zw.。檔案 例程，包括下列專案：

傳遞至 FltReadFile、ZwReadFile、FltWriteFile 或 ZwWriteFile 之 ByteOffset 參數的任何位元組位移值都必須是扇區大小的倍數。
傳遞至 FltReadFile、ZwReadFile、FltWriteFile 或 ZwWriteFile 的 Length 參數必須是扇區大小的倍數。請注意，指定讀取作業給長度完全是扇區大小的緩衝區，可能會導致在傳輸期間到達檔案結尾時，傳送到該緩衝區的顯著位元組較少。
緩衝區必須符合基礎儲存裝置的對齊需求。您可以呼叫 FltCreateFileEx2 來取得此資訊，以取得代表實體裝置的檔案物件句柄，然後使用該句柄呼叫 ZwQueryInformationFile ，並將 FileAlignmentInformation 指定為 FileInformationClass 參數的值。如需系統FILE_XXX_ALIGNMENT值的詳細資訊，這些值定義於 Ntifs.h 中，請參閱 DEVICE_OBJECT 和 初始化 Device 物件。
呼叫將 FileInformationClass 參數設為 FilePositionInformationFile 的 FltSetInformationFile 或 ZwSetInformation 必須指定扇區大小的倍數位移。

CreateOptions FILE_SYNCHRONOUS_IO_ALERT和FILE_SYNCHRONOUS_IO_NONALERT旗標，這些旗標與其名稱建議互斥，請指定正在針對同步 I/O 開啟檔案。這表示，只要檔案上傳回的 FileHandle 所參考的檔案物件發生，檔案上的所有 I/O 作業都會同步。這類檔案上的所有 I/O 都會使用傳回的句柄，跨所有線程串行化。其中一個 CreateOptions 旗標設定後，I/O 管理員會在檔案物件的 CurrentByteOffset 字段中維護目前的檔案位置位移。這個位移可用於對 ZwReadFile 和 ZwWriteFile 的呼叫。您也可以呼叫 ZwQueryInformationFile 或 ZwSetInformationFile 來查詢或設定它。

如果未指定CreateOptions FILE_OPEN_REPARSE_POINT 旗標，且 FltCreateFileEx2 嘗試開啟具有重新分析點的檔案，則檔案會進行一般的重新分析點處理。另一方面，如果指定FILE_OPEN_REPARSE_POINT旗標，則不會發生一般重新分析處理， 而且 FltCreateFileEx2 會嘗試直接開啟重新分析點檔案。在任一情況下，如果開啟作業成功， FltCreateFileEx2 會傳回STATUS_SUCCESS;否則，例程會傳回NTSTATUS錯誤碼。 FltCreateFileEx2 永遠不會傳回STATUS_REPARSE。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK 旗標會消除開啟檔案並要求作業鎖定之間的時間，這可能會讓第三方開啟檔案並取得共享違規。應用程式可以在 FltCreateFileEx2 上使用 FILE_OPEN_REQUIRING_OPLOCK 旗標，然後要求任何 oplock。這可確保 oplock 擁有者會收到任何後續開啟要求而導致共用違規的通知。

在 Windows 7 中，如果應用程式使用 FILE_OPEN_REQUIRING_OPLOCK 旗標時，檔案上有其他句柄，則建立作業將會失敗，且STATUS_OPLOCK_NOT_GRANTED。從 Windows 8 開始，此限制已不存在。

如果此建立作業會中斷檔案上已經存在的 oplock，則設定 FILE_OPEN_REQUIRING_OPLOCK 旗標會導致建立作業失敗，並出現STATUS_CANNOT_BREAK_OPLOCK。此建立作業不會中斷現有的 oplock。

使用此旗標的應用程式必須在呼叫成功之後要求 oplock，或者所有稍後嘗試開啟檔案都會遭到封鎖，而不需要一般 Oplock 處理的優點。同樣地，如果此呼叫成功，但稍後的 oplock 要求失敗，則使用此旗標的應用程式必須在偵測到 oplock 要求失敗之後關閉其句柄。

注意

windows 7、Windows Server 2008 R2 和更新版本的 Windows 操作系統提供FILE_OPEN_REQUIRING_OPLOCK旗標。在 Windows 7 中實作此旗標的 Microsoft 文件系統為 NTFS、FAT 和 exFAT。

CreateOptions 旗標FILE_RESERVE_OPFILTER可讓應用程式要求層級 1、批次或篩選 oplock，以防止其他應用程式收到共享違規。不過，FILE_RESERVE_OPFILTER只適用於篩選 oplock。若要使用它，您必須完成下列步驟：

使用FILE_RESERVE_OPFILTER的 CreateOptions 、完全FILE_READ_ATTRIBUTES的 DesiredAccess 和完全FILE_SHARE_READ的 ShareAccess 發出建立要求 |FILE_SHARE_WRITE |FILE_SHARE_DELETE。
- 如果已經有開啟的句柄，則建立要求會失敗並STATUS_OPLOCK_NOT_GRANTED，而下一個要求的 oplock 也會失敗。
- 如果您以更多存取權或較少的共享開啟，也會造成STATUS_OPLOCK_NOT_GRANTED失敗。
如果建立要求成功，請要求 oplock。
開啟檔案的另一個句柄以執行 I/O。

NTFS 是唯一實作FILE_RESERVE_OPFILTER的 Microsoft 文件系統。

Minifilter 驅動程序必須使用 FltSetInformationFile，而不是 ZwSetInformationFile 來重新命名檔案。

注意

如果您嘗試開啟磁碟區，但只指定 DesiredAccess 參數的下列旗標組合， FltCreateFileEx2 將會開啟與文件系統無關的句柄，而該句柄與磁碟區的儲存裝置直接存取。

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

您不得使用 FltCreateFileEx2 開啟可直接存取磁碟區儲存裝置的句柄，否則您將流失系統資源。如果您想要開啟直接存取存儲設備的句柄，請改為呼叫 IoCreateFileEx、 IoCreateFileSpecifyDeviceObjectHint 或 ZwCreateFile 函式。

當 FltCreateFileEx2 的呼叫端想要啟用磁碟區目標的重新分析時， FLT_CREATEFILE_TARGET_ECP_CONTEXT 可以包含為 DriverContext 參數中 ECP 清單的 ECP。如果此 ECP 存在， FltCreateFileEx2 將會調整建立作業的目標裝置，並嘗試尋找適合指定檔案資訊的已篩選磁碟區實例。從 Windows 8 開始，即可使用此 ECP。

規格需求

需求	值
最低支援的用戶端	從 Windows Vista 開始提供。
目標平台	Universal
標頭	fltkernel.h (包括 FltKernel.h)
程式庫	Fltmgr.lib
IRQL	PASSIVE_LEVEL