IRP_MJ_CREATE (FS 和 FS 篩選條件)

發行項
02/02/2024

傳送時

I/O 管理員會在下列情況下傳送IRP_MJ_CREATE要求：

通常，此 IRP 會代表呼叫 Microsoft Win32 函式的使用者模式應用程式傳送，例如 CreateFile 或代表核心模式元件，該元件已呼叫 IoCreateFile、 IoCreateFileSpecifyDeviceObjectHint、 ZwCreateFile 或 ZwOpenFile 等函式。

如果建立要求成功完成，應用程式或核心模式元件會收到檔案物件的句柄。

作業：檔案系統驅動程式

如果目標裝置對像是文件系統的控制裝置物件，則文件系統驅動程式的分派例程必須在將 Irp-IoStatus.Status 和 Irp-IoStatus.Information>> 設定為適當的值之後，完成 IRP 並傳回適當的 NTSTATUS 值。

否則，文件系統驅動程式應該處理建立要求。

作業：舊版文件系統篩選驅動程式

如果目標裝置對像是篩選驅動程式的控制裝置對象，篩選驅動程式的分派例程必須在將Irp-IoStatus.Status 和 Irp-IoStatus.Information>> 設定為適當的值之後，完成 IRP 並傳回適當的 NTSTATUS 值。

否則，篩選驅動程式應該執行任何必要的處理。然後，根據篩選的本質，它應該完成 IRP，或將其向下傳遞至堆棧上的下一個較低驅動程式。

一般而言，篩選驅動程式不應該傳回 STATUS_PENDING 以回應 IRP_MJ_CREATE。不過，如果較低層級的驅動程式傳回 STATUS_PENDING，篩選驅動程式應該會將此狀態值傳遞至驅動程序鏈結。

文件系統篩選驅動程式寫入器應該注意 IoCreateStreamFileObject 會導致 IRP_MJ_CLEANUP 要求傳送至磁碟區的文件系統驅動程式堆疊。由於文件系統通常會建立串流檔案對象作為 IRP_MJ_CREATE以外作業的副作用，因此篩選驅動程式很難可靠地偵測串流檔案物件建立。因此，篩選驅動程式應該會收到先前未看到檔案物件的 IRP_MJ_CLEANUP 和 IRP_MJ_CLOSE 要求。針對 IoCreateStreamFileObjectLite，不會傳送 IRP_MJ_CLEANUP 要求。

當舊版篩選驅動程式在建立後回呼中重新發出建立要求時，它們必須釋放並設定與其重新分析點相關聯的緩衝區， (輔助緩衝區) 為 NULL。如果舊版篩選驅動程式未釋放此緩衝區，並將它設定為 NULL，驅動程式將會流失記憶體。迷你篩選驅動程式不需要這麼做，因為篩選管理員會為其執行此動作。

參數

文件系統或舊版篩選驅動程式會使用指定的 IRP 呼叫 IoGetCurrentIrpStackLocation ，以取得 IRP 中本身堆疊位置的指標。在下列參數中， Irp 指向 IRP ， 而 IrpSp 指向 IO_STACK_LOCATION。驅動程式可以使用 IRP 和 IRP 堆疊位置下列成員中設定的資訊來處理建立要求。

DeviceObject 是目標裝置物件的指標。
Irp->如果 file 物件代表具有擴充屬性的檔案，AssociatedIrp.SystemBuffer 會指向 FILE_FULL_EA_INFORMATION結構化緩衝區。否則，此成員會設定為 NULL。
Irp->旗標 會設定為此要求的下列旗標：
- IRP_CREATE_OPERATION
- IRP_DEFER_IO_COMPLETION
- IRP_SYNCHRONOUS_API
Irp->RequestorMode 指出要求作業之進程的執行模式，也就是 KernelMode 或 UserMode。如果已設定SL_FORCE_ACCESS_CHECK旗標，則即使 Irp-RequestorMode> 是 KernelMode，也必須執行存取檢查。
Irp->IoStatus 指向 IO_STATUS_BLOCK結構， 該結構會接收最終完成狀態和所要求作業的相關信息。檔案系統 會將此 結構的信息成員設定為下列其中一個值：
- FILE_CREATED
- FILE_DOES_NOT_EXIST
- FILE_EXISTS
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
Irp->Overlay.AllocationSize 是檔案的初始配置大小，以位元組為單位。除非檔案正在建立、覆寫或取代，否則非零值沒有任何作用。
IrpSp->FileObject 指向 I/O 管理員建立的檔案物件，代表要建立或開啟的檔案。當文件系統處理IRP_MJ_CREATE要求時，它會將此檔案物件中的 FsContext 和可能 FsContext2 字段設定為檔案系統特定值。因此，在文件系統處理建立要求之前， FsContext 和 FsContext2 字段的值無法視為有效。如需詳細資訊，請參閱檔案數據流、串流內容和 Per-Stream 內容。

FltCancelFileOpen 和 IoCancelFileOpen 會在檔案物件的 Flags 字段中設定FO_FILE_OPEN_CANCELLED旗標。設定此旗標表示已取消IRP_MJ_CREATE要求，而此檔案物件將會發出 IRP_MJ_CLOSE 要求。一旦取消建立要求，就無法重新發出。

IrpSp-FileObject> 參數包含 RelatedFileObject 字段的指標，這也是FILE_OBJECT結構。 FILE_OBJECT 結構的 RelatedFileObject 字段是用來指出指定的檔案已相對於已經開啟的檔案對象開啟。這通常表示相對檔案是目錄，但串流型檔案可能會相對於檔案的現有數據流開啟。 FILE_OBJECT 結構的 RelatedFileObject 字段只有在處理IRP_MJ_CREATE期間才有效。

IrpSp->旗標 可以設定為下列一或多個值：

旗標	意義
SL_FORCE_ACCESS_CHECK 0x01	如果設定此旗標，即使 IRP-RequestorMode> 的值是 KernelMode，也必須執行存取檢查。
SL_OPEN_PAGING_FILE 0x02	如果已設定此旗標，則檔案是分頁檔案。
SL_OPEN_TARGET_DIRECTORY 0x04	如果設定此旗標，則應該開啟檔案的父目錄。
SL_STOP_ON_SYMLINK 0x08	如果設定此旗標，I/O 管理員的接點自動周遊和符號鏈接會隱藏，導致連接點和符號連結的開啟傳回STATUS_REPARSE。
SL_IGNORE_READONLY_ATTRIBUTE 0x40	如果已設定此旗標，它允許建立具有 FILE_DELETE_ON_CLOSE 選項的唯讀檔案。此選項會導致關閉句柄時刪除檔案。
SL_CASE_SENSITIVE 0x80	如果設定，檔名比較應該區分大小寫。

IrpSp->MajorFunction 設定為 IRP_MJ_CREATE。
IrpSp->Parameters.Create.EaLength 是 Irp-AssociatedIrp.SystemBuffer> 緩衝區的位元組大小。如果 Irp*->AssociatedIrp.SystemBuffer 的值是 NULL，這個成員必須是零。
IrpSp->Parameters.Create.FileAttributes 是建立或開啟檔案時要套用的屬性旗標位掩碼。只有在檔案建立、取代或在某些情況下覆寫時，才會套用明確指定的屬性。根據預設，這個值是FILE_ATTRIBUTE_NORMAL，任何其他旗標或相容旗標的組合都可以覆寫。此成員會對應至 IoCreateFileSpecifyDeviceObjectHint 的 FileAttributes 參數。
IrpSp->Parameters.Create.Options 是旗標的位掩碼，可指定要在建立或開啟檔案時套用的選項，以及如果檔案已經存在時要採取的動作。

此參數的高 8 位對應至 IoCreateFileSpecifyDeviceObjectHint 的 Disposition 參數。

此成員的低 24 位會對應至 IoCreateFileSpecifyDeviceObjectHint 的 CreateOptions 參數。執行檔案掃描的文件系統篩選和迷你篩選驅動程式 (，例如防毒程式) 應該特別注意FILE_COMPLETE_IF_OPLOCKED旗標。如果設定此旗標，篩選不得封鎖或延遲IRP_MJ_CREATE作業。

如果在預先建立 (建立分派) 路徑中設定FILE_COMPLETE_IF_OPLOCKED旗標，則篩選不得起始下列任何一種作業類型，因為它們可能會造成 oplock 中斷：
- IRP_MJ_CLEANUP
- IRP_MJ_CREATE
- IRP_MJ_FILE_SYSTEM_CONTROL
- IRP_MJ_FLUSH_BUFFERS
- IRP_MJ_LOCK_CONTROL
- IRP_MJ_READ
- IRP_MJ_SET_INFORMATION
- IRP_MJ_WRITE
如果篩選或迷你篩選無法接受FILE_COMPLETE_IF_OPLOCKED旗標，則必須使用 STATUS_SHARING_VIOLATION 完成IRP_MJ_CREATE要求。

如果在建立后) 路徑 (完成 (設定FILE_COMPLETE_IF_OPLOCKED旗標，篩選應該檢查文件系統是否已將 Irp-IoStatus.Status> 設定為STATUS_OPLOCK_BREAK_IN_PROGRESS狀態值。如果未設定此狀態值，篩選條件可以放心地在檔案上起始上述其中一項作業。如果已設定此狀態值，則 oplock 尚未中斷，而且篩選條件不得起始任何可能導致 oplock 中斷的作業。因此，篩選條件必須延後檔案上的所有作業，直到下列其中一個條件成立為止：
- oplock 的擁有者會將FSCTL_OPLOCK_BREAK_ACKNOWLEDGE要求傳送至文件系統。
- 篩選或迷你篩選以外的系統元件會傳送文件系統 I/O 要求，該要求必須等到 oplock 中斷完成 (，例如IRP_MJ_READ或IRP_MJ_WRITE) 。篩選或迷你篩選可以從其分派 (或預先操作回呼起始上述其中一個作業，) 這個新作業的例程，因為分派或預先操作回呼例程會進入等候狀態，直到作業中斷完成為止。
*IrpSp->Parameters.Create.SecurityContext-AccessState> 指向包含對象主體內容、授與存取類型和剩餘所需存取類型的ACCESS_STATE結構。
IrpSp->Parameters.Create.SecurityContext-DesiredAccess> 是一個ACCESS_MASK結構，指定為檔案所要求的訪問許可權。如需詳細資訊，請參閱 IoCreateFileSpecifyDeviceObjectHint 的 DesiredAccess 參數描述。
IrpSp->Parameters.Create.ShareAccess 是檔案所要求的共用訪問許可權位掩碼。如果這個成員為零，則會要求獨佔存取權。如需詳細資訊，請參閱 IoCreateFileSpecifyDeviceObjectHint 的 ShareAccess 參數描述。