FltCreateMailslotFile 函式 （fltkernel.h）
迷你篩選驅動程式會呼叫 FltCreateMailslotFile，以建立新的管道或開啟現有的 mailslot。
語法
NTSTATUS FLTAPI FltCreateMailslotFile(
[in] PFLT_FILTER Filter,
[in, optional] PFLT_INSTANCE Instance,
[out] PHANDLE FileHandle,
[out, optional] PFILE_OBJECT *FileObject,
[in] ULONG DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG CreateOptions,
[in] ULONG MailslotQuota,
[in] ULONG MaximumMessageSize,
[in] PLARGE_INTEGER ReadTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
參數
[in] Filter
呼叫端的不透明篩選指標。
[in, optional] Instance
要傳送建立要求之迷你篩選驅動程序實例的不透明實例指標。 實例必須附加至 mailslot 文件系統的磁碟區。 這個參數是選擇性的，而且可以 NULL。 如果此參數 NULL，則要求會傳送至磁碟區檔系統驅動程式堆疊頂端的裝置物件。 如果它是非NULL，則要求只會傳送至附加在指定實例下方的小型篩選驅動程序實例。
[out] FileHandle
呼叫端配置的變數指標，如果呼叫 FltCreateMailslotFile 成功，就會接收檔句柄。
[out, optional] FileObject
呼叫端配置的變數指標，如果呼叫 FltCreateMailslotFile 成功，就會接收檔案物件指標。 這個參數是選擇性的，而且可以 NULL。
[in] DesiredAccess
旗標的位掩碼，指定呼叫端對檔案或目錄所需的存取類型。 一組系統定義的 DesiredAccess 旗標會決定下列檔案物件的特定訪問許可權。
| DesiredAccess 旗標 | 意義 |
|---|---|
| FILE_READ_DATA | 您可以從具名 mailslot 讀取數據。 |
| FILE_READ_ATTRIBUTES | FileAttributes 旗標可以讀取。 如需詳細資訊，請參閱 FltCreateFileEx2FileAttributes 參數中的有效旗標值數據表。 |
| READ_CONTROL | 您可以讀取與 mailslot 相關聯的存取控制清單 ACL 和擁有權資訊。 |
| FILE_WRITE_DATA | 數據可以寫入 mailslot。 |
| FILE_WRITE_ATTRIBUTES | FileAttributes 旗標可以寫入。 |
| FILE_APPEND_DATA | 數據可以附加至 mailslot。 |
| WRITE_DAC | 您可以撰寫與 mailslot 相關聯之 DACL 選擇性存取控制清單。 |
| WRITE_OWNER | 您可以撰寫與 mailslot 相關聯的擁有權資訊。 |
| ACCESS_SYSTEM_SECURITY | 呼叫端將具有 mailslot 之 SACL 的寫入許可權。 |
| 同步 | 呼叫端可以等候傳回的 FileHandle 設定為 Signaled 狀態，以同步處理 I/O 作業的完成。 如果設定 CreateOptions FILE_SYNCHRONOUS_IO_ALERT 或FILE_SYNCHRONOUS_IO_NONALERT旗標，則必須設定此旗標。 |
或者，對於任何不代表目錄的檔案物件，您可以指定下列一或多個泛型 ACCESS_MASK 旗標。 （STANDARD_RIGHTS_XXX 旗標是預先定義的系統值，用來在系統對象上強制執行安全性。您也可以將這些泛型旗標與上表的其他旗標結合。
| DesiredAccess 至檔案值 | 對應至 DesiredAccess 旗標 |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ、FILE_READ_DATA和 SYNCHRONIZE。 |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_APPEND_DATA和 SYNCHRONIZE。 |
[in] ObjectAttributes
已使用 InitializeObjectAttributes初始化之不透明 OBJECT_ATTRIBUTES 結構的指標。 如果呼叫端正在系統進程內容中執行，這個參數可以 NULL。 否則，呼叫端必須在呼叫中將 OBJ_KERNEL_HANDLE 屬性設定為 InitializeObjectAttributes。 下表列出此檔案物件結構的成員。
| 成員 | 價值 |
|---|---|
| ULONG 長度 |
ObjectAttributes 所指向之 結構中包含的數據位元組數目，。 這個值必須至少 sizeof(OBJECT_ATTRIBUTES)。 |
| PUNICODE_STRING ObjectName | UNICODE_STRING 結構的指標，其中包含要建立或開啟之 mailslot 的名稱。 此名稱必須是完整檔案規格或裝置對象的名稱，除非它是與 RootDirectory所指定的目錄相對的檔名。 例如，“\Device\Mailslot\myslot” 或 “？？\mailslot\myslot“ 可以是有效的檔案規格。 （注意：“？？” 會將 “\DosDevices” 取代為 Win32 物件命名空間的名稱。 “\DosDevices” 仍可運作，但物件管理員會更快翻譯 “？？” 。 |
| HANDLE RootDirectory | 選擇性的目錄句柄，由先前呼叫 FltCreateFileEx2取得。 如果此值 NULL，則 ObjectName 成員必須是包含目標 mailslot 完整路徑的完整檔案規格。 如果此值非NULL，則 ObjectName 成員會指定相對於此目錄的郵件集名稱。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | 要套用至 mailslot 的選擇性 SECURITY_DESCRIPTOR。 這類安全性描述元所指定的 A CL，只會在建立郵件集時套用至 mailslot。 如果建立mailslot時，此值 NULL，則放置於mailslot上的 ACL 會相依於mailslot檔案系統，並允許具有任何存取權的用戶端建立實例。 |
| ULONG 屬性 | 一組旗標，可控制檔案對象屬性。 如果呼叫端正在系統進程內容中執行，這個參數可以是零。 否則，呼叫端必須設定OBJ_KERNEL_HANDLE旗標。 呼叫端也可以選擇性地設定OBJ_CASE_INSENSITIVE旗標，這表示名稱查閱程式代碼應該忽略 objectName 大小寫，而不是執行完全相符的搜尋。 |
[out] IoStatusBlock
IO_STATUS_BLOCK 結構的指標，該結構會接收最終完成狀態和要求之作業的相關信息。 從 FltCreateMailslotFile傳回時，變數 資訊 成員包含下列其中一個值：
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
建立或開啟 mailslot 時要套用的選項，做為下列旗標的相容組合。
| 標誌 | 意義 |
|---|---|
| FILE_WRITE_THROUGH | 將數據寫入mailslot的系統服務、檔案系統和驅動程式，在將任何要求的寫入作業視為完成之前，必須實際將數據傳輸到mailslot。 如果設定 CreateOptions 旗標FILE_NO_INTERMEDIATE_BUFFERING，則會自動設定此旗標。 |
| FILE_SYNCHRONOUS_IO_ALERT | mailslot 上的所有作業都會同步執行。 代表呼叫端的任何等候，都受限於警示的過早終止。 此旗標也會讓 I/O 系統維護 mailslot 位置內容。 如果設定此旗標，也必須設定 DesiredAccess SYNCHRONIZE 旗標，讓 I/O 管理員使用檔案物件做為同步處理物件。 |
| FILE_SYNCHRONOUS_IO_NONALERT | mailslot 上的所有作業都會同步執行。 系統等候同步處理 I/O 佇列和完成，不受警示限制。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果設定此旗標，也必須設定 DesiredAccess SYNCHRONIZE 旗標，讓 I/O 管理員使用檔案物件做為同步處理物件。 |
[in] MailslotQuota
寫入mailslot之緩衝區的大小，以位元組為單位。
[in] MaximumMessageSize
要寫入mailslot之郵件的大小上限，以位元組為單位。 任何大小的訊息是由值 0 所指定。
[in] ReadTimeout
讀取作業等候郵件在mailslot中使用的時間。 默認逾時會以 100 奈秒的增量表示為負整數。 例如，將 250 毫秒指定為 –10*1000*250。 此外，下列值具有特殊意義。
| 價值 | 意義 |
|---|---|
| 0 | 如果沒有訊息存在，則立即傳回 。 |
| -1 | 永遠等候訊息。 |
[in, optional] DriverContext
IoInitializeDriverCreateContext初始化之 IO_DRIVER_CREATE_CONTEXT 結構的選擇性指標。
傳回值
FltCreateMailslotFile 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一項。
| 傳回碼 | 描述 |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Filter 或 Instance 參數中指定的篩選或實例正在中斷。 如果開啟的要求跨越磁碟區裝入點，而且 實例 參數不是非NULL，就可以接收此狀態代碼。 這是錯誤碼。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD | ObjectAttributes 參數未包含 RootDirectory 成員，但 OBJECT_ATTRIBUTES 結構中的 ObjectName 成員是空字串，或不包含OBJECT_NAME_PATH_SEPARATOR字元。 此錯誤碼表示物件路徑的語法不正確。 |
言論
FltCreateMailslotFile 函式可讓小型篩選驅動程式建立或開啟 mailslot 實例。 這對於建立虛擬Mailslot或建立散發給其他數個mailslotslot的mailslot群組很有用。
Instance 參數是 NULL，或先前透過附加至 mailslot 磁碟區來設定。 磁碟區指標是透過傳遞 「\Device\Mailslot」 作為磁碟區名稱來取得，以 FltGetVolumeFromName。
若要將額外的 create 參數 （ECP） 指定為建立作業的一部分，請使用 FltAllocateExtraCreateParameterList 例程，初始化 IO_DRIVER_CREATE_CONTEXT 結構 成員。 如果使用 ECP，則必須使用其相關聯的支援例程來配置、初始化和釋放它們。 從 FltCreateMailslotFile呼叫傳回時，ECP 清單會保持不變，而且可能會傳遞給其他建立作業 FltCreateMailslotFile 的其他呼叫。 ECP 清單結構不會自動解除分配。 FltCreateMailslotFile 的呼叫端必須呼叫 FltFreeExtraCreateParameterList 例程來解除分配此結構。
如果 實例 未 NULL，則從 FltCreateMailslotFile 建立要求只會傳送至附加在指定迷你篩選驅動程序實例和 mailslot 文件系統下方的實例。 上面附加的指定實例和實例不會收到建立要求。 如果未指定任何實例，則要求會移至堆疊頂端，並由所有實例和 mailslot 檔系統接收。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | 可在 Windows 8 中使用。 |
| 目標平臺 | 普遍 |
| 標頭 | fltkernel.h （包括 FltKernel.h） |
| 連結庫 | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
另請參閱
FltAllocateExtraCreateParameterList