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 旗標。 如需詳細資訊，請參閱 FltCreateFileEx2之 FileAttributes 參數中有效旗標值的數據表。 |
| 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 的寫入許可權。 |
| SYNCHRONIZE | 呼叫端可以等候傳回的 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。 否則，呼叫端必須在 呼叫 InitializeObjectAttributes 中設定OBJ_KERNEL_HANDLE屬性。 下表列出此檔案物件結構的成員。
| 成員 | 值 |
|---|---|
| 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 成員會指定相對於此目錄的 mailslot 名稱。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | 要套用至 mailslot 的選擇性 SECURITY_DESCRIPTOR 。 這類安全性描述項指定的 ACL 只會在建立郵件集時套用至 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 時要套用的選項，做為下列旗標的相容組合。
| Flags | 意義 |
|---|---|
| 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 值，例如下列其中一項。
| 傳回碼 | Description |
|---|---|
| STATUS_FLT_DELETING_OBJECT | 篩選或實例參數中指定的 篩選 或 實例 正在損毀。 如果開啟的要求跨越磁碟區裝入點，而且 Instance 參數為非 NULL，則可以接收此狀態代碼。 這是錯誤碼。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD | ObjectAttributes 參數不包含 RootDirectory 成員，但OBJECT_ATTRIBUTES結構中的 ObjectName 成員是空字串，或不包含OBJECT_NAME_PATH_SEPARATOR字元。 這個錯誤碼表示物件路徑的語法不正確。 |
備註
FltCreateMailslotFile 函式可讓迷你篩選驅動程式建立或開啟 mailslot 實例。 這適用於建立虛擬 Mailslot，或建立可散發給數個其他 mailslot 的 mailslot 群組。
Instance 參數為 NULL，或先前藉由附加至 mailslot 磁碟區來設定。 磁碟區指標是藉由將 “\Device\Mailslot” 當做磁碟區名稱傳遞至 FltGetVolumeFromName 來取得。
若要在建立作業中指定額外的 create 參數 (ECP) ，請使用 FltAllocateExtraCreateParameterList 例程，初始化 IO_DRIVER_CREATE_CONTEXT 結構的 ExtraCreateParameter 成員。 如果使用 ECP，則必須使用其相關聯的支援例程來配置、初始化和釋放它們。 從 FltCreateMailslotFile 的呼叫傳回時，ECP 清單會保持不變，而且可能會傳遞給其他建立作業的 FltCreateMailslotFile 呼叫。 ECP 清單結構不會自動解除分配。 FltCreateMailslotFile 的呼叫端必須藉由呼叫 FltFreeExtraCreateParameterList 例程來解除分配此結構。
如果 Instance 不是 NULL，則來自 FltCreateMailslotFile 的建立要求只會傳送至附加在指定迷你篩選驅動程序實例下方的實例和 mailslot 文件系統。 上面附加的指定實例和實例不會收到建立要求。 如果未指定任何實例，則要求會移至堆疊頂端，並由所有實例和 mailslot 檔系統接收。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 可在 Windows 8 中使用。 |
| 目標平台 | Universal |
| 標頭 | fltkernel.h (包含 FltKernel.h) |
| 程式庫 | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
另請參閱
FltAllocateExtraCreateParameterList