名前付きパイプのインスタンスを作成し、そのインスタンスのハンドルを返します。その後、そのハンドルを使ってパイプの操作を行えます。名前付きパイプのサーバープロセスはこの関数を使って、新しい名前付きパイプの最初のインスタンスを作成して基本的な属性を設定したり、既存の名前付きパイプの新しいインスタンスを作成できます。

HANDLE CreateNamedPipe(
  LPCTSTR lpName,                             // パイプ名
  DWORD dwOpenMode,        // パイプを開くモード
  DWORD dwPipeMode,                           // パイプ固有のモード
  DWORD nMaxInstances,                        // インスタンスの最大数
  DWORD nOutBufferSize,                       // 出力バッファのサイズ
  DWORD nInBufferSize,                        // 入力バッファのサイズ
  DWORD nDefaultTimeOut,                      // タイムアウトの間隔
  LPSECURITY_ATTRIBUTES lpSecurityAttributes  // セキュリティ記述子
);

パラメータ

lpName

パイプの名前を保持している、NULL で終わる一意の文字列へのポインタを指定します。文字列の形式は次のとおりです。

\\.\pipe\pipename

pipename の部分では、円記号（\）を除き、数字や記号を含む任意の文字を指定できます。パイプ名全体の最大の長さは 256 文字です。パイプ名では、大文字と小文字を区別しません。

dwOpenMode

パイプハンドルのパイプアクセス、オーバーラップ（非同期）、ライトスルー、セキュリティの各モードを指定します。

dwOpenMode パラメータで、以下の表に掲載されていないフラグを指定すると、CreateNamedPipe 関数は失敗します。

アクセスモードは、次の値のいずれかで指定します。パイプの各インスタンスで、同じ値を指定しなければなりません。

値	説明
PIPE_ACCESS_DUPLEX	パイプは双方向です。サーバーとクライアントの両方がパイプの読み書きを行えます。GENERIC_READ | GENERIC_WRITE アクセスを指定することに相当します。クライアント側は 関数を使ってパイプへ接続する際に、GENERIC_READ と GENERIC_WRITE アクセスの一方または両方を指定できます。
PIPE_ACCESS_INBOUND	パイプ内のデータの流れを、クライアントからサーバーへの方向に限定します。サーバー側でそのパイプに対して GENERIC_READ アクセスを指定することに相当します。クライアント側はこのパイプへ接続する際に、GENERIC_WRITE アクセスを指定しなければなりません。
PIPE_ACCESS_OUTBOUND	パイプ内のデータの流れを、サーバーからクライアントへの方向に限定します。サーバー側でそのパイプに対して GENERIC_WRITE アクセスを指定することに相当します。クライアント側はこのパイプへ接続する際に、GENERIC_READ アクセスを指定しなければなりません。

ライトスルーモードとオーバーラップモードは、次の値の任意の組み合わせで指定します。これらのモードは、同じパイプの各インスタンスで異なっていてもかまいません。

値	説明
FILE_FLAG_WRITE_THROUGH	ライトスルーモードを有効にします。クライアントプロセスとサーバープロセスを異なったコンピュータで実行していて、バイトタイプのパイプを使っている場合にのみ、このモードが影響を及ぼします。このモードが有効な場合、名前付きパイプにデータを書き込む関数は、書き込んだデータがネットワーク経由で送信されて、リモートコンピュータ上にあるパイプのバッファに格納されるまで、制御を返しません。このモードが無効な場合、システムは最小バイト数が蓄積されるまで、または最大の時間が経過するまでデータのバッファリングを行うことにより、ネットワークの使用効率を向上させます。
FILE_FLAG_OVERLAPPED	オーバーラップ（非同期）モードを有効にします。このモードが有効な場合、読み取り、書き込み、接続など完了するまでにかなり長い時間がかかる可能性のある操作を行う関数は、すぐに制御を返します。スレッドはこのモードを使うと、時間のかかる操作をバックグラウンドで実行している間に、他の操作を開始できます。たとえば、オーバーラップモードでは、1 つのスレッドが 1 つのパイプの複数のインスタンスに対して入出力（I/O）操作を同時に実行したり、同じパイプハンドルに対して複数の読み書き操作を実行することもできます。このモードが無効な場合、パイプの読み取り、書き込み、接続を行う関数は、その操作が完了するまで制御を返しません。 と の各関数は、オーバーラップモードでのみ実行できます。、、ConnectNamedPipe、TransactNamedPipe の各関数は、同期モードとオーバーラップモードのどちらでも実行できます。

セキュリティモードは、次の値の任意の組み合わせで指定します。これらのモードは、同じパイプの各インスタンスで異なっていてもかまいません。パラメータの他のモードでどのような値を指定したかにかかわりなく、これらの値を指定できます。

値	説明
WRITE_DAC	呼び出し側に、名前付きパイプの DACL（随意アクセス制御リスト）への書き込みアクセス権を割り当てます。
WRITE_OWNER	呼び出し側に、名前付きパイプのオーナーへの書き込みアクセス権を割り当てます。
ACCESS_SYSTEM_SECURITY	呼び出し側に、名前付きパイプの SACL（システムアクセス制御リスト）への書き込みアクセス権を割り当てます。詳細については、MSDN ライブラリの「」と「」を参照してください。

dwPipeMode

パイプハンドルのタイプ、読み取りモード、待機モードを指定します。

パイプハンドルのタイプモードは、次の値のいずれかで指定します。パイプの各インスタンスで、同じタイプモードを指定しなければなりません。0 を指定すると、既定としてバイトタイプモードが割り当てられます。

値	説明
PIPE_TYPE_BYTE	バイトストリームのデータをパイプに書き込みます。PIPE_READMODE_MESSAGE と同時に指定することはできません。
PIPE_TYPE_MESSAGE	メッセージストリームのデータをパイプに書き込みます。PIPE_READMODE_MESSAGE または PIPE_READMODE_BYTE のいずれかと組み合わせて指定できます。

読み取りモードは、次の値のいずれかで指定します。これらのモードは、パイプの各インスタンスで異なっていてもかまいません。0 を指定すると、既定としてバイト読み取りモードが割り当てられます。

値	説明
PIPE_READMODE_BYTE	パイプのデータを、バイトストリームのデータとして読み取ります。PIPE_TYPE_MESSAGE または PIPE_TYPE_BYTE のいずれかと組み合わせて指定できます。
PIPE_READMODE_MESSAGE	パイプのデータをメッセージストリームのデータとして読み取ります。PIPE_TYPE_MESSAGE を指定した場合にのみ、PIPE_READMODE_MESSAGE を指定できます。

待機モードは、次の値のいずれかで指定します。これらのモードは、同じパイプの各インスタンスで異なっていてもかまいません。0 を指定すると、既定としてブロッキングモードが割り当てられます。

値	説明
PIPE_WAIT	ブロッキングモードを有効にします。このモードでは、 関数は読み取るデータが発生するまで、 関数はデータがすべて書き込まれるまで、ConnectNamedPipe 関数はクライアントに接続されるまで制御を返しません。このモードを使うと、特定の状況では、クライアントプロセスが何か操作を行うまで長い時間待機する可能性があります。
PIPE_NOWAIT	ノンブロッキングモードを有効にします。このモードでは、ReadFile、WriteFile、ConnectNamedPipe の各関数は必ず、即座に制御を返します。 ノンブロッキングモードは、Microsoft LAN Lanager 2.0 との互換性を保つ目的でサポートされています。名前付きパイプで非同期入出力（I/O）を行うために使うことは避けてください。非同期のパイプ I/O の詳細については、MSDN ライブラリの「」を参照してください。

nMaxInstances

このパイプに対して作成できるインスタンスの最大数を指定します。パイプの各インスタンスで同じ値を指定しなければなりません。1～PIPE_UNLIMITED_INSTANCES（Winbase.h で 255 と定義されています）の値を指定します。PIPE_UNLIMITED_INSTANCES を指定すると、システムのリソースが利用できる限り、インスタンスを作成できます。

nOutBufferSize

出力バッファで予約するべきバイト数を指定します。名前付きパイプのバッファのサイズ指定については、この関数の「解説」を参照してください。

nInBufferSize

入力バッファで予約するべきバイト数を指定します。名前付きパイプのバッファのサイズ指定については、この関数の「解説」を参照してください。

nDefaultTimeOut

WaitNamedPipe 関数で NMPWAIT_USE_DEFAULT_WAIT を指定した場合に適用される、既定のタイムアウト値をミリ秒（ms）単位で指定します。パイプの各インスタンスで同じ値を指定しなければなりません。

lpSecurityAttributes

1 個の 構造体へのポインタを指定します。この構造体で、子プロセスが、返されたハンドルを継承できるかどうかを指定します。このパラメータで NULL を指定すると、既定のセキュリティ記述子が使われ、ハンドルを継承できません。

戻り値

関数が成功すると、名前付きパイプのインスタンスのサーバー側のハンドルが返ります。

関数が失敗すると、INVALID_HANDLE_VALUE が返ります。拡張エラー情報を取得するには、 関数を使います。nMaxInstances パラメータの値が PIPE_UNLIMITED_INSTANCES より大きい場合、ERROR_INVALID_PARAMETER が返ります。

解説

CreateNamedPipe 関数を使って名前付きパイプのインスタンスを作成するには、ユーザーはその名前付きパイプオブジェクトへの FILE_CREATE_PIPE_INSTANCE アクセス権を持っていなければなりません。新しい名前付きパイプを作成する場合、セキュリティ属性に関係するパラメータで指定されたアクセス制御リスト（ACL）が、その名前付きパイプの随意アクセス制御リスト（DACL）を定義します。

1 つの名前付きパイプのすべてのインスタンスで、パイプハンドルのタイプ（バイトタイプまたはメッセージタイプ）、アクセスモード（双方向、着信、発信のいずれか）、インスタンスの最大数、タイムアウト値の同じ値を指定しなければなりません。異なる値を指定すると、CreateNamedPipe 関数は失敗し、GetLastError 関数は ERROR_ACCESS_DENIED を返します。

名前付きパイプのサーバー側がメッセージモードに設定されている場合でも、クライアント側はバイトモードで開始されます。データを受信する際に問題が発生することを防止するために、必要に応じてクライアント側をメッセージモードに設定してください。

入力バッファと出力バッファで指定したサイズは、参考として使われるだけです。名前付きパイプの両側で割り当てられる実際のバッファサイズは、システムの既定値、システムの最小値、システムの最大値、指定されたサイズをすぐ上の割り当て境界値へ丸めた値のいずれかです。

パイプのサーバー側は、パイプのクライアントが処理を開始するまでは、ブロッキングモードの読み取り操作を行うべきではありません。さもないと、競合が発生することがあります。C のランタイムなどの初期化コードは、継承されたハンドルをロックして検討する必要がありますが、通常、この競合が発生するのは、このような場合です。

名前付きパイプの 1 つのインスタンスに対して 1 つまたは複数のハンドルを作成した後、最後のハンドルを閉じると、そのインスタンスは必ず削除されます。

対応情報

Windows NT/2000：Windows NT 3.1 以降
Windows 95/98：対応していません
ヘッダー：Winbase.h 内で宣言、Windows.h をインクルード
インポートライブラリ：Kernel32.lib を使用
Unicode：Windows NT/2000 は Unicode 版と ANSI 版を実装

参照

ConnectNamedPipe, , , , , TransactNamedPipe, WaitNamedPipe, ,