NtCreateNamedPipeFile 関数
特定の名前付きパイプの最初のインスタンスまたは既存の名前付きパイプの別のインスタンスのサーバー エンド ハンドルを作成して開きます。 関数は、パイプへのアクセスに使用できるハンドルを返します。
構文
NTSTATUS NtCreateNamedPipeFile(
[out] PHANDLE FileHandle,
[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,
[in] ULONG InboundQuota,
[in] ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout
);
パラメーター
FileHandle [out]
呼び出しが成功した場合にファイル ハンドルを受け取る変数へのポインター。
DesiredAccess [in]
呼び出し元が必要とするファイルまたはディレクトリへのアクセスの種類を指定するフラグのビットマスク。 このシステム定義の DesiredAccess フラグのセットは、ファイル オブジェクトに対する次の特定のアクセス権を決定します。
| フラグ | 説明 |
|---|---|
| DELETE | ファイルは削除できます。 |
| FILE_READ_DATA | ファイルからデータを読み取ることができます。 |
| FILE_READ_ATTRIBUTES | 以下で説明する FileAttributes フラグを読み取ることができます。 |
| FILE_READ_EA | ファイルに関連付けられている拡張属性 (EA) を読み取ることができます。 |
| READ_CONTROL | ファイルに関連付けられているアクセス制御リスト (ACL) と所有権情報を読み取ることができます。 |
| FILE_WRITE_DATA | ファイルにデータを書き込むことができます。 |
| FILE_WRITE_ATTRIBUTES | FileAttributes フラグを書き込むことができます。 |
| FILE_WRITE_EA | ファイルに関連付けられている EA を書き込むことができます。 |
| FILE_APPEND_DATA | データはファイルに追加できます。 |
| WRITE_DAC | ファイルに関連付けられている随意アクセス制御リスト (DACL) を書き込むことができます。 |
| WRITE_OWNER | ファイルに関連付けられている所有権情報を書き込むことができます。 |
| SYNCHRONIZE | 呼び出し元は、返された FileHandle が Signaled 状態に設定されるのを待機することで、I/O 操作の完了を同期できます。
CreateOptions またはFILE_SYNCHRONOUS_IO_NONALERTフラグが設定されている場合は、このフラグを設定するFILE_SYNCHRONOUS_IO_ALERT必要があります。 |
| FILE_EXECUTE | システム ページング I/O を使用して、ファイルからデータをメモリに読み込むことができます。 |
または、ディレクトリを表さないファイル オブジェクトに対して、次の汎用 ACCESS_MASK フラグを 1 つ以上指定することもできます。 STANDARD_RIGHTS_XXX フラグは、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です。 これらの汎用フラグを、前の表の追加フラグと組み合わせることもできます。
| ファイル値への必要なアクセス | DesiredAccess フラグへのマップ |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ、FILE_READ_DATA、FILE_READ_ATTRIBUTES、FILE_READ_EA、SYNCHRONIZE。 |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_WRITE_ATTRIBUTES、FILE_WRITE_EA、FILE_APPEND_DATA、SYNCHRONIZE。 |
| GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE、SYNCHRONIZE、FILE_READ_ATTRIBUTES、FILE_EXECUTE。 |
ディレクトリ ( FILE_DIRECTORY_FILECreateOptions フラグが設定されている) には、次の 1 つ以上の ACCESS_MASK フラグを指定できます。このフラグは、前に説明した互換性のあるフラグと組み合わせることもできます。
| ディレクトリ値への必要なアクセス | 説明 |
|---|---|
| FILE_LIST_DIRECTORY | ディレクトリ内のファイルを一覧表示できます。 |
| FILE_TRAVERSE | ディレクトリは走査できます。つまり、ファイルのパス名の一部にすることができます。 |
、FILE_READ_DATAFILE_WRITE_DATA、FILE_EXECUTE、および FILE_APPEND_DATADesiredAccess フラグは、ディレクトリ ファイルの作成または開きと互換性がありません。
ObjectAttributes [in]
InitializeObjectAttributes ルーチンによって既に初期化されている構造体へのOBJECT_ATTRIBUTESポインター。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは になります NULL。 それ以外の場合、呼び出し元は OBJ_KERNEL_HANDLEInitializeObjectAttributes の呼び出しで 属性を設定する必要があります。
ファイル オブジェクトのこの構造体のメンバーは次のとおりです。
| メンバー | 値 |
|---|---|
| ULONG の長さ | 指定された ObjectAttributes データの バイト数。 この値は、少なくとも sizeof(OBJECT_ATTRIBUTES)である必要があります。 |
| PUNICODE_STRING ObjectName | 作成または開くファイルの名前を含むバッファー内の Unicode 文字列へのポインター。 この値は、RootDirectory で指定されたディレクトリに対するファイルの名前でない限り、完全修飾ファイル指定である必要があります。 たとえば、"\Device\フロッピー1\myfile.dat" や "??\B:\myfile.dat" は、フロッピー ディスク ドライブ ドライバーと上にあるファイル システムが既に読み込まれている限り、完全修飾ファイル仕様である可能性があります。 (注: "??" は、Win32 オブジェクト名前空間の名前として "\DosDevices" を置き換えます。"\DosDevices" は引き続き機能しますが、"??" はオブジェクト マネージャーによってより高速に変換されます)。) |
| HANDLE RootDirectory | NtCreateNamedPipeFile の以前の呼び出しによって取得されたディレクトリへの省略可能なハンドル。 この値が NULL の場合、 ObjectName メンバーは、ターゲット ファイルへの完全パスを含む完全修飾ファイル仕様である必要があります。 この値が NULL 以外の場合、 ObjectName メンバーは、このディレクトリに対する相対ファイル名を指定します。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | ファイルに適用されるオプションのセキュリティ記述子。 このようなセキュリティ記述子で指定された ACL は、作成時にのみファイルに適用されます。 ファイルの作成時に値が NULL の場合、ファイルに配置される ACL はファイル システムに依存します。ほとんどのファイル システムは、そのような ACL の一部を、呼び出し元の既定の ACL と組み合わせて親ディレクトリ ファイルから伝達します。 |
| ULONG 属性 | ファイル オブジェクト属性を制御するフラグのセット。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは 0 にすることができます。 それ以外の場合、呼び出し元は フラグを設定する OBJ_KERNEL_HANDLE 必要があります。 呼び出し元は、必要に応じて フラグを OBJ_CASE_INSENSITIVE 設定することもできます。これは、完全一致検索を実行する代わりに、名前参照コードで ObjectName の大文字と小文字を無視する必要があることを示します。 |
IoStatusBlock [out]
最終的な完了状態と要求された操作に関する情報を受け取る型 IO_STATUS_BLOCK の変数へのポインター。
NtCreateNamedPipeFile から返されると、変数の Information メンバーには次のいずれかの値が含まれます。
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
ShareAccess [in]
呼び出し元が必要とするファイルへの共有アクセスの種類を、0 または 1、または次のフラグの組み合わせとして指定します。 排他アクセスを要求するには、このパラメーターを 0 に設定します。 共有違反エラーを回避するには、次のすべての共有アクセス フラグを指定します。
| ShareAccess フラグ | 説明 |
|---|---|
| FILE_SHARE_READ | ファイルは、他のスレッドのファイル作成呼び出しによって読み取りアクセスのために開くことができます。 |
| FILE_SHARE_WRITE | ファイルは、他のスレッドのファイル作成呼び出しによって書き込みアクセスのために開くことができます。 |
| FILE_SHARE_DELETE | ファイルは、他のスレッドのファイル作成呼び出しによって削除アクセスのために開くことができます。 |
通常、デバイス ドライバーと中間ドライバーは ShareAccess を 0 に設定します。これにより、呼び出し元は開いているファイルに排他的にアクセスできます。
CreateDisposition [in]
ファイルが既に存在する場合のファイルの処理方法を決定する値。 CreateDisposition には、次のいずれかを指定できます。
| 値 | 説明 |
|---|---|
| FILE_SUPERSEDE | ファイルが既に存在する場合は、指定したファイルに置き換えます。 存在しない場合は、指定されたファイルを作成します。 |
| FILE_CREATE | ファイルが既に存在する場合は、要求を失敗させ、指定されたファイルを作成したり開いたりしないでください。 存在しない場合は、指定されたファイルを作成します。 |
| FILE_OPEN | ファイルが既に存在する場合は、新しいファイルを作成する代わりにファイルを開きます。 存在しない場合は、要求を失敗させ、新しいファイルを作成しないでください。 |
| FILE_OPEN_IF | ファイルが既に存在する場合は、ファイルを開きます。 存在しない場合は、指定されたファイルを作成します。 |
| FILE_OVERWRITE | ファイルが既に存在する場合は、ファイルを開いて上書きします。 存在しない場合は、要求を失敗します。 |
| FILE_OVERWRITE_IF | ファイルが既に存在する場合は、ファイルを開いて上書きします。 存在しない場合は、指定されたファイルを作成します。 |
CreateOptions [in]
ファイルを作成または開くときに適用するオプションを、次のフラグの互換性のある組み合わせとして指定します。
| CreateOptions フラグ | 説明 |
|---|---|
| FILE_DIRECTORY_FILE (0x00000001) | 作成または開いているファイルはディレクトリ ファイルです。 このフラグでは、Disposition パラメーターを 、FILE_OPEN、または FILE_OPEN_IFのいずれかにFILE_CREATE設定する必要があります。 このフラグと互換性のある CreateOptions フラグは、FILE_SYNCHRONOUS_IO_ALERTFILE_SYNCHRONOUS_IO_NONALERTFILE_WRITE_THROUGH、FILE_OPEN_FOR_BACKUP_INTENTおよび FILE_OPEN_BY_FILE_IDです。 |
| FILE_WRITE_THROUGH (0x00000002) | ファイルにデータを書き込むシステム サービス、ファイル システム、ドライバーは、要求された書き込み操作が完了したと見なされる前に、実際にデータをファイルに転送する必要があります。 |
| FILE_SEQUENTIAL_ONLY (0x00000004) | ファイルへのすべてのアクセスはシーケンシャルになります。 |
| FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) | ファイルをキャッシュしたり、ドライバーの内部バッファーにバッファー化したりすることはできません。 このフラグは DesiredAccessFILE_APPEND_DATA フラグと互換性がありません。 |
| FILE_SYNCHRONOUS_IO_ALERT (0x00000010) | ファイルに対するすべての操作が同期的に実行されます。 呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグが設定されている場合は、I/O マネージャーが同期オブジェクトとしてファイル オブジェクトを使用するように DesiredAccessSYNCHRONIZE フラグも設定する必要があります。 |
| FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) | ファイルに対するすべての操作が同期的に実行されます。 システムで I/O キューの同期を待機し、完了はアラートの対象になりません。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグが設定されている場合は、I/O マネージャーが同期オブジェクトとしてファイル オブジェクトを使用するように DesiredAccessSYNCHRONIZE フラグも設定する必要があります。 |
| FILE_NON_DIRECTORY_FILE (0x00000040) | 開いているファイルがディレクトリ ファイルではないか、この呼び出しが失敗します。 開いているファイル オブジェクトは、データ ファイルを表すことができます。論理デバイス、仮想デバイス、または物理デバイス。またはボリューム。 |
| FILE_CREATE_TREE_CONNECTION (0x00000080) | ネットワーク経由で開くために、このファイルのツリー接続を作成します。 |
| FILE_COMPLETE_IF_OPLOCKED (0x00000100) | 呼び出し元のスレッドをブロックするのではなく、ターゲット ファイルが oplocked の場合は、代替成功コードを使用してすぐにこの操作を完了します。 ファイルが oplocked の場合、別の呼び出し元は既にネットワーク経由でファイルにアクセスできます。 |
| FILE_NO_EA_KNOWLEDGE (0x00000200) | 開かれている既存のファイルの拡張属性が、呼び出し元がファイルを正しく解釈するために拡張属性を理解する必要があることを示している場合、呼び出し元は拡張属性の処理方法を理解していないため、この要求を失敗させます。 |
| FILE_OPEN_REMOTE_INSTANCE (0x00000400) | システムの使用のために予約されています。は使用しません。 |
| FILE_RANDOM_ACCESS (0x00000800) | ファイルへのアクセスはランダムな場合があるため、ファイル システムまたはオペレーティング システムによってファイルに対して順次先読み操作を実行する必要はありません。 |
| FILE_DELETE_ON_CLOSE (0x00001000) | 最後のハンドルが FltClose に渡されたときにファイルを削除します。 |
| FILE_OPEN_BY_FILE_ID (0x00002000) | ファイルは ID で開かれています。 ファイル名には、デバイスの名前と、ファイルを開くために使用する 64 ビット ID が含まれます。 |
| FILE_OPEN_FOR_BACKUP_INTENT (0x000004000) | ファイルはバックアップの目的で開かれています。そのため、システムは特定のアクセス権を確認し、ファイルのセキュリティ記述子に対して入力 DesiredAccess を確認する前に、呼び出し元にファイルへの適切なアクセス権を付与する必要があります。 |
| FILE_NO_COMPRESSION (0x00008000) | 親ディレクトリからの の FILE_ATTRIBUTE_COMPRESSED 継承を抑制します。 これにより、圧縮されていないファイルを、圧縮済みとマークされたディレクトリに作成できます。 |
| FILE_OPEN_REQUIRING_OPLOCK (0x00010000) | ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。 ファイル システムは、作成操作を実行する前に oplock をチェックします。作成操作が既存の oplock を中断すると、作成操作は の STATUS_CANNOT_BREAK_OPLOCK 戻りコードで失敗します。 このフラグは、Windows 7、Windows Server 2008 R2 以降の Windows オペレーティング システムで使用できます。 |
| FILE_DISALLOW_EXCLUSIVE (0x00020000) | 既存のファイルを開くときに、 が指定されておらず、ファイル システム アクセス チェックで呼び出し元にファイルへの書き込みアクセス権が付与されない場合 FILE_SHARE_READ は、 でこのファイルを開け STATUS_ACCESS_DENIEDませんでした。 これは Windows 7 より前の既定の動作でした。 |
| FILE_SESSION_AWARE (0x00040000) | ファイルまたはデバイスがセッション認識で開かれています。 このフラグが指定されていない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。 このフラグは、セッション 0 にない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。 このフラグは、Windows Server 2012する前にはサポートされていません。 |
| FILE_RESERVE_OPFILTER (0x00100000) | このフラグを使用すると、アプリケーションはフィルターの日和見ロック (oplock) を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 開いているハンドルが既にある場合、作成要求は で STATUS_OPLOCK_NOT_GRANTED失敗します。 |
| FILE_OPEN_REPARSE_POINT (0x00200000) | 再解析ポイントを使用してファイルを開き、ファイルの通常の再解析ポイント処理をバイパスします。 詳細については、「解説」を参照してください。 |
| FILE_OPEN_NO_RECALL (0x00400000) | オフライン ストレージまたは仮想化を実行するフィルターに対して、このファイルが開かれた結果としてファイルの内容を再呼び出ししないように指示します。 |
| FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) | このフラグは、呼び出し元のスレッドに関連付けられているユーザーをキャプチャするようにファイル システムに指示します。 返されたハンドルを使用して FltQueryVolumeInformation または ZwQueryVolumeInformationFile を後続で呼び出すと、呼び出し元が使用できる空き領域を計算するために、その時点で呼び出し元ユーザーではなく、キャプチャされたユーザーが想定されます。 これは、 FsInformationClass の値 FileFsSizeInformation、、 FileFsFullSizeInformationおよび FileFsFullSizeInformationExに適用されます。 |
NamedPipeType [in]
作成する名前付きパイプの型 (バイト型またはメッセージ型)。
ReadMode [in]
パイプを読み取るモード (バイト型またはメッセージ型)。
CompletionMode [in]
操作を完了する方法を指定します。
MaximumInstances [in]
名前付きパイプの同時インスタンスの最大数。
InboundQuota [in]
名前付きパイプの受信側への書き込み用に予約されているプール クォータを指定します。
OutboundQuota [in]
名前付きパイプの受信側への書き込み用に予約されているプール クォータを指定します。
DefaultTimeout [in, optional]
名前付きパイプのインスタンスを待機するときにタイムアウト値が指定されていない場合に使用されるタイムアウト値への省略可能なポインター。
戻り値
関数の値は、作成/開く操作の最終的な状態です。
Remarks
名前付きパイプのインスタンスを作成するには、名前付きパイプ オブジェクト にFILE_CREATE_PIPE_INSTANCE アクセスできる必要があります。 新しい名前付きパイプを作成する場合は、セキュリティ属性パラメーターのアクセス制御リスト (ACL) によって、名前付きパイプの随意アクセス制御が定義されます。
名前付きパイプのすべてのインスタンスは、同じパイプの種類 (バイト型またはメッセージ型)、パイプ アクセス (双方向、受信、または送信)、インスタンス数、タイムアウト値を指定する必要があります。 異なる値を使用すると、この関数は失敗し、GetLastError はERROR_ACCESS_DENIEDを返します。
クライアント プロセスは、 CreateFile または CallNamedPipe 関数を使用して名前付きパイプに接続します。 サーバー側がメッセージ・モードであっても、名前付きパイプのクライアント側はバイト・モードで開始されます。 データの受信に関する問題を回避するには、クライアント側もメッセージ モードに設定します。 パイプのモードを変更するには、パイプ クライアントが読み取り専用パイプを開き、 GENERIC_READ して アクセスFILE_WRITE_ATTRIBUTES 必要があります。
パイプ サーバーは、パイプ クライアントが開始されるまでブロック読み取り操作を実行しないでください。 そうしないと、競合状態が発生する可能性があります。 これは通常、C ランタイムなどの初期化コードで、継承されたハンドルをロックして調べる必要がある場合に発生します。
名前付きパイプが作成されるたびに、システムは非ページ プール (カーネルによって使用される物理メモリ) を使用して受信バッファーまたは送信バッファーを作成します。 作成できるパイプ インスタンス (スレッドやプロセスなどのオブジェクト) の数は、使用可能な非ページ プールによって制限されます。 読み取りまたは書き込みの各要求には、読み取りまたは書き込みデータ用のバッファー内の領域と、内部データ構造用の追加の領域が必要です。
入出力バッファー・サイズはアドバイザリです。 名前付きパイプの各端に予約されている実際のバッファー サイズは、システムの既定値、システムの最小値または最大値、または指定したサイズが次の割り当て境界に切り上げられます。 指定するバッファー サイズは、プロセスが非ページ プールを使い果たさないほど小さく、一般的な要求に対応するのに十分な大きさにする必要があります。
パイプ書き込み操作が発生するたびに、システムは最初にパイプ書き込みクォータに対してメモリの充電を試みます。 残りのパイプ書き込みクォータが要求を満たすのに十分な場合、書き込み操作はすぐに完了します。 残りのパイプ書き込みクォータが小さすぎて要求を満たしていない場合、システムは、プロセス用に予約されている非ページ プールを使用して、データに対応するようにバッファーを拡張しようとします。 書き込み操作では、追加のバッファー クォータを解放できるように、パイプからデータが読み取られるまでブロックされます。 したがって、指定したバッファー サイズが小さすぎると、システムは必要に応じてバッファーを拡張しますが、欠点は操作がブロックされる点です。 操作が重複している場合、システム スレッドはブロックされます。それ以外の場合、アプリケーション スレッドはブロックされます。
名前付きパイプで使用されるリソースを解放するには、アプリケーションは必要なくなったときに常にハンドルを閉じる必要があります。これは CloseHandle 関数を呼び出すか、インスタンス ハンドルに関連付けられているプロセスが終了したときに実行されます。 名前付きパイプのインスタンスには、複数のハンドルが関連付けられている場合があることに注意してください。 名前付きパイプのインスタンスは、名前付きパイプのインスタンスへの最後のハンドルが閉じられると、常に削除されます。
要件
| 要件 | 値 |
|---|---|
| ヘッダー | ntioapi.h |
| ライブラリ | ntdll.lib |