次の方法で共有

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 フラグを 1 つ以上指定することもできます。 (STANDARD_RIGHTS_XXX フラグは、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です)。これらの汎用フラグを、前の表の追加フラグと組み合わせることもできます。

DesiredAccess to File Values 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構造体への ポインター。 この名前は、 RootDirectory で指定されたディレクトリに対するファイルの名前でない限り、完全修飾ファイル仕様またはデバイス オブジェクトの名前である必要があります。 たとえば、"\Device\NamedPipe\mypipe" や "\??\pipe\mypipe" はどちらも有効なファイル指定である可能性があります。 (注: "\??" は、Win32 オブジェクト名前空間の名前として "\DosDevices" を置き換えます。"\DosDevices" は引き続き機能しますが、"\??" はオブジェクト マネージャーによってより高速に変換されます)。)
HANDLE RootDirectory FltCreateFileEx2 の前の呼び出しによって取得される、ディレクトリへの省略可能なハンドル。 この値が NULL の場合、 ObjectNameメンバーは、ターゲット パイプへの完全パスを含む完全修飾ファイル仕様である必要があります。 この値が NULL 以外の場合、 ObjectName メンバーは、このディレクトリに対して相対的なパイプ名を指定します。
PSECURITY_DESCRIPTOR SecurityDescriptor パイプに適用するオプションのセキュリティ記述子 (SECURITY_DESCRIPTOR)。 このようなセキュリティ記述子で指定された ACL は、作成時にのみパイプに適用されます。 パイプの作成時に値が NULL の場合、パイプに配置される ACL は名前付きパイプ ファイル システムに依存し、任意のアクセス権を持つクライアントがインスタンスを作成できます。
ULONG 属性 ファイル オブジェクト属性を制御するフラグのセット。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは 0 にすることができます。 それ以外の場合、呼び出し元は OBJ_KERNEL_HANDLE フラグを設定する必要があります。 呼び出し元は、必要に応じて OBJ_CASE_INSENSITIVE フラグを設定することもできます。これは、完全一致検索を実行するのではなく、名前参照コードで ObjectName の大文字と小文字を無視する必要があることを示します。

[out] IoStatusBlock

最終的 な完了 状態と要求された操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 FltCreateNamedPipeFile から返されると、変数の Information メンバーには次のいずれかの値が含まれます。

FILE_CREATED

FILE_OPENED

[in] ShareAccess

呼び出し元が次のフラグの 1 つまたは組み合わせとして必要とするファイルへの共有アクセスの種類。 共有違反エラーを回避する可能性が最も高い場合は、次のすべての共有アクセス フラグを指定します。

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 システムはパイプ位置コンテキストを維持します。 このフラグが設定されている場合は、I/O マネージャーがファイル オブジェクトを同期オブジェクトとして使用するように DesiredAccess SYNCHRONIZE フラグも設定する必要があります。
FILE_SYNCHRONOUS_IO_NONALERT パイプに対するすべての操作は同期的に実行されます。 システムで I/O キューの同期を待機し、完了はアラートの対象になりません。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグが設定されている場合は、I/O マネージャーがファイル オブジェクトを同期オブジェクトとして使用するように DesiredAccess SYNCHRONIZE フラグも設定する必要があります。

[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 パラメーターで指定された フィルター または インスタンス が破棄されています。 この状態コードは、オープン要求がボリューム マウント ポイントを超え、 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で使用できます。
対象プラットフォーム ユニバーサル
Header fltkernel.h (FltKernel.h を含む)
Library Fltmgr.lib
IRQL PASSIVE_LEVEL

こちらもご覧ください

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext