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 旗標。 如需詳細資訊，請參閱 FltCreateFileEx2之 FileAttributes 參數中有效旗標值的數據表。
READ_CONTROL 您可以讀取與命名管道相關聯的訪問控制清單 (ACL) 和擁有權資訊。
FILE_WRITE_DATA 數據可以寫入命名管道。
FILE_WRITE_ATTRIBUTES FileAttributes 旗標可以寫入。
FILE_APPEND_DATA 數據可以附加至檔案。
WRITE_DAC 您可以寫入與命名管道相關聯的 DACL) (任意存取控制清單。
WRITE_OWNER 可以寫入與命名管道相關聯的擁有權資訊。
ACCESS_SYSTEM_SECURITY 呼叫端將具有具名管道 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 所指向之結構中包含的數據位元組數目。 此值必須至少 為大小 (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 結構的指標。 從 FltCreateNamedPipeFile 傳回時，變數 的信息成員會 包含下列其中一個值：

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 值，例如下列其中一個。

傳回碼 Description
STATUS_FLT_DELETING_OBJECT
 篩選或實例參數中指定的 篩選 或 實例 正在損毀。 如果開啟的要求跨越磁碟區裝入點，而且 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 結構的 ExtraCreateParameter 成員。 如果使用 ECP，則必須使用其相關聯的支援例程來配置、初始化和釋放它們。 從 FltCreateNamedPipeFile 的呼叫傳回時，ECP 清單不會變更，而且可能會傳遞給其他建立作業的 FltCreateNamedPipeFile 呼叫。 ECP 清單結構不會自動解除分配。 FltCreateNamedPipeFile 的呼叫端必須藉由呼叫 FltFreeExtraCreateParameterList 例程來解除分配此結構。

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

規格需求

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

另請參閱

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext