共用方式為

FltCreateNamedPipeFile 函式 （fltkernel.h）

  • 發行項

迷你篩選驅動程式會呼叫 FltCreateNamedPipeFile，以建立新的管道或開啟現有的管道。

語法

NTSTATUS FLTAPI FltCreateNamedPipeFile(
  [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                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in]            ULONG                     NamedPipeType,
  [in]            ULONG                     ReadMode,
  [in]            ULONG                     CompletionMode,
  [in]            ULONG                     MaximumInstances,
                  ULONG                     InboundQuota,
                  ULONG                     OutboundQuota,
  [in, optional]  PLARGE_INTEGER            DefaultTimeout,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

參數

[in] Filter

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

[in, optional] Instance

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

[out] FileHandle

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

[out, optional] FileObject

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

[in] DesiredAccess

旗標的位掩碼，指定呼叫端對檔案或目錄所需的存取類型。 一組系統定義的 DesiredAccess 旗標會決定下列檔案物件的特定訪問許可權。

DesiredAccess 旗標 意義
FILE_READ_DATA 您可以從命名管道讀取資料。
FILE_READ_ATTRIBUTES FileAttributes 旗標可以讀取。 如需詳細資訊，請參閱 FileAttributesFltCreateFileEx2中的有效旗標值數據表。
READ_CONTROL 可以讀取與命名管道相關聯的訪問控制清單（ACL）和擁有權資訊。
FILE_WRITE_DATA 數據可以寫入命名管道。
FILE_WRITE_ATTRIBUTES FileAttributes 旗標可以寫入。
FILE_APPEND_DATA 數據可以附加至檔案。
WRITE_DAC 您可以撰寫與命名管道相關聯的任意存取控制清單（DACL）。
WRITE_OWNER 您可以撰寫與命名管道相關聯的擁有權資訊。
ACCESS_SYSTEM_SECURITY 呼叫端將具有具名管道 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 結構的指標，其中包含要建立或開啟之管道的名稱。 此名稱必須是完整檔案規格或裝置對象的名稱，除非它是與 RootDirectory所指定的目錄相對的檔名。 例如，“\Device\NamedPipe\mypipe” 或 “\？？\pipe\mypipe“ 可以是有效的檔案規格。 （注意：“\？？” 會取代 “\DosDevices” 作為 Win32 物件命名空間的名稱。“\DosDevices” 仍可運作，但物件管理員會更快翻譯 “\？？”
HANDLE RootDirectory 目錄的選擇性句柄，由先前呼叫 fltCreateFileEx2 取得。 如果此值 NULL，則 ObjectName成員必須是包含目標管道完整路徑的完整檔案規格。 如果此值非NULL，則 ObjectName 成員會指定相對於此目錄的管道名稱。
PSECURITY_DESCRIPTOR SecurityDescriptor 要套用至管道的選擇性安全性描述元 （SECURITY_DESCRIPTOR）。 這類安全性描述元所指定的 ACL，只會在建立管道時套用至管道。 如果在建立管道時 NULL 值，則放置於管道上的 ACL 會相依於命名管道文件系統，並允許具有任何存取權的用戶端建立實例。
ULONG 屬性 一組旗標，可控制檔案對象屬性。 如果呼叫端正在系統進程內容中執行，這個參數可以是零。 否則，呼叫端必須設定OBJ_KERNEL_HANDLE旗標。 呼叫端也可以選擇性地設定OBJ_CASE_INSENSITIVE旗標，這表示名稱查閱程式代碼應該忽略 objectName 大小寫，而不是執行完全相符的搜尋。

[out] IoStatusBlock

IO_STATUS_BLOCK 結構的指標，可接收最終完成狀態和所要求作業的相關信息。 從 FltCreateCreatePipeFile傳回時，變數的 Information 成員包含下列其中一個值：

FILE_CREATED

FILE_OPENED

[in] ShareAccess

呼叫端需要作為一個或下列旗標組合之檔案的共用存取類型。 為避免共用違規錯誤的最大機會，請指定下列所有共用存取旗標。

ShareAccess 旗標 意義
FILE_SHARE_READ 檔案可以透過其他線程呼叫 fltCreateNamedPipeFile 開啟以讀取存取。
FILE_SHARE_WRITE 檔案可以透過其他線程呼叫 FltCreateNamedPipeFile來開啟檔案以進行寫入存取。

[in] CreateDisposition

值，根據檔案是否已經存在，決定要採取的動作。 此值可以是下表所述的任一值。

CreateDisposition 值 意義
FILE_CREATE 如果檔案已經存在，則要求失敗，且不會建立或開啟指定的檔案。 如果沒有，請建立檔案。
FILE_OPEN 如果檔案已經存在，請開啟它，而不是建立新的檔案。 如果沒有，請失敗要求，且不會建立新的檔案。
FILE_OPEN_IF 如果檔案已經存在，請加以開啟。 如果沒有，請建立檔案。

[in] CreateOptions

建立或開啟管道時要套用的選項，做為下列旗標的相容組合。

CreateOptions 旗標 意義
FILE_WRITE_THROUGH 將數據寫入管道的系統服務、管道系統和驅動程式必須實際將數據傳送至管道，才能將任何要求的寫入作業視為完成。 如果設定 CreateOptions 旗標FILE_NO_INTERMEDIATE_BUFFERING，則會自動設定此旗標。
FILE_SYNCHRONOUS_IO_ALERT 管道上的所有作業都會同步執行。 代表呼叫端的任何等候，都受限於警示的過早終止。 此旗標也會讓 I/O 系統維護管道位置內容。 如果設定此旗標，也必須設定 DesiredAccess SYNCHRONIZE 旗標，讓 I/O 管理員使用檔案物件做為同步處理物件。
FILE_SYNCHRONOUS_IO_NONALERT 管道上的所有作業都會同步執行。 系統等候同步處理 I/O 佇列和完成，不受警示限制。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果設定此旗標，也必須設定 DesiredAccess SYNCHRONIZE 旗標，讓 I/O 管理員使用檔案物件做為同步處理物件。

[in] NamedPipeType

要建立的命名管道類型。 可以是下列其中一個值：

價值 意義
FILE_PIPE_BYTE_STREAM_TYPE
 數據會以位元組數據流的形式寫入管道。 若要使用此類型，ReadMode 不得FILE_PIPE_MESSAGE_MODE。
FILE_PIPE_MESSAGE_TYPE
 數據會以訊息的形式寫入管道。

[in] ReadMode

要從管道讀取的模式。

價值 意義
FILE_PIPE_BYTE_STREAM_MODE
 管道數據會以位元組數據流的形式讀取。
FILE_PIPE_MESSAGE_MODE
 管道數據會讀取為訊息。 若要使用此模式，NamedPipeType 必須是FILE_PIPE_MESSAGE_TYPE。

[in] CompletionMode

管道讀取和寫入的完成模式。

價值 意義
FILE_PIPE_QUEUE_OPERATION
 管道讀取和寫入要求會排入佇列，而且可以封鎖直到完成為止。
FILE_PIPE_COMPLETE_OPERATION
 管道讀取和寫入要求會立即完成。

[in] MaximumInstances

這個命名管道允許的實例數目上限。

InboundQuota

要保留給輸入緩衝區的位元組數目。

OutboundQuota

要保留輸出緩衝區的位元組數目。

[in, optional] DefaultTimeout

100 奈秒增量的預設逾時。 這個值會以負整數表示。 例如，250 毫秒指定為 –10 * 1000 * 250。

[in, optional] DriverContext

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

傳回值

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

傳回碼 描述
STATUS_FLT_DELETING_OBJECT
 Filter 或 Instance 參數中指定的篩選或實例正在中斷。 如果開啟的要求跨越磁碟區裝入點，而且 實例 參數不是非NULL，就可以接收此狀態代碼。 這是錯誤碼。
STATUS_OBJECT_PATH_SYNTAX_BAD
 ObjectAttributes 參數未包含 RootDirectory 成員，但 OBJECT_ATTRIBUTES 結構中的 ObjectName 成員是空字串，或不包含OBJECT_NAME_PATH_SEPARATOR字元。 此錯誤碼表示物件路徑的語法不正確。

言論

FltCreateNamedPipeFile 函式可讓小型篩選驅動程式建立或開啟管道實例。 這對於建立虛擬管道或建立多任務 I/O 的管道聯集很有用。

實例 參數 NULL，或先前透過附加至命名管道磁碟區來設定。 磁碟區指標是透過傳遞 「\Device\NamedPipe」 作為磁碟區名稱來取得，以 FltGetVolumeFromName。

若要將額外的 create 參數 （ECP） 指定為建立作業的一部分，請使用 FltAllocateExtraCreateParameterList 例程，初始化 IO_DRIVER_CREATE_CONTEXT 結構 成員 ExtraCreateParameterList。 如果使用 ECP，則必須使用其相關聯的支援例程來配置、初始化和釋放它們。 從 FltCreateNamedPipeFile的呼叫傳回時，ECP 清單不會變更，而且可能會傳遞至其他建立作業 FltCreateNamedPipeFile 的其他呼叫。 ECP 清單結構不會自動解除分配。 FltCreateNamedPipeFile 的呼叫者必須呼叫 FltFreeExtraCreateParameterList 例程來解除分配此結構。

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

要求

要求 價值
最低支援的用戶端 可在 Windows 8 中使用。
目標平臺 普遍
標頭 fltkernel.h （包括 FltKernel.h）
連結庫 Fltmgr.lib
IRQL PASSIVE_LEVEL

另請參閱

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext