CreateNamedPipeA 関数 (winbase.h)
名前付きパイプのインスタンスを作成し、後続のパイプ操作のハンドルを返します。 名前付きパイプ サーバー プロセスでは、この関数を使用して、特定の名前付きパイプの最初のインスタンスを作成し、その基本属性を確立するか、既存の名前付きパイプの新しいインスタンスを作成します。
構文
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
パラメーター
[in] lpName
一意のパイプ名。 この文字列は、次の形式である必要があります。
\\.\pipe\pipename
名前のパイプ名部分には、円記号以外の任意の文字 (数字や特殊文字を含む) を含めることができます。 パイプ名の文字列全体は、最大 256 文字です。 パイプ名では大文字と小文字は区別されません。
[in] dwOpenMode
開いているモード。
dwOpenMode
このパラメーターは、次のいずれかのパイプ アクセス モードを指定する必要があります。 パイプのインスタンスごとに同じモードを指定する必要があります。
| モード | 意味 |
|---|---|
|
パイプは双方向です。サーバー プロセスとクライアント プロセスの両方で、パイプの読み取りと書き込みを行うことができます。 このモードにより、サーバーはパイプに対する GENERIC_READ と GENERIC_WRITE アクセスに相当します。 クライアントは、CreateFile 関数を使用してパイプに接続するときに、GENERIC_READ または GENERIC_WRITEまたはその両方を指定できます。 |
|
パイプ内のデータフローは、クライアントからサーバーにのみ送られます。 このモードにより、サーバーはパイプに対する GENERIC_READ アクセスに相当します。 クライアントは、パイプに接続するときに GENERIC_WRITE アクセスを指定する必要があります。 GetNamedPipeInfoまたは GetNamedPipeHandleState 関数を呼び出してパイプ設定を読み取る必要がある場合、クライアントはパイプに接続するときに GENERIC_WRITE と FILE_READ_ATTRIBUTES アクセスを指定する必要があります。 |
|
パイプ内のデータフローは、サーバーからクライアントにのみ送信されます。 このモードにより、サーバーはパイプへの GENERIC_WRITE アクセスに相当します。 クライアントは、パイプに接続するときに GENERIC_READ アクセスを指定する必要があります。 SetNamedPipeHandleState 関数を呼び出して、クライアントがパイプ設定を変更する必要がある場合、クライアントはパイプに接続するときに GENERIC_READ と FILE_WRITE_ATTRIBUTES アクセスを指定する必要があります。 |
このパラメーターには、書き込みモードと重複モードを有効にする次のフラグを 1 つ以上含めることもできます。 これらのモードは、同じパイプのインスタンスごとに異なる場合があります。
このパラメーターには、次のセキュリティ アクセス モードの任意の組み合わせを含めることができます。 これらのモードは、同じパイプのインスタンスごとに異なる場合があります。
[in] dwPipeMode
パイプ モード。
dwPipeMode
次のいずれかの型モードを指定できます。 パイプのインスタンスごとに同じ型モードを指定する必要があります。
| モード | 意味 |
|---|---|
|
データは、バイト ストリームとしてパイプに書き込まれます。 このモードは、PIPE_READMODE_MESSAGEでは使用できません。 パイプは、異なる書き込み操作中に書き込まれたバイトを区別しません。 |
|
データは、メッセージのストリームとしてパイプに書き込まれます。 パイプは、各書き込み操作中に書き込まれたバイトをメッセージ単位として扱います。 GetLastError 関数は、メッセージが完全に読み取られない場合に ERROR_MORE_DATA を返します。 このモードは、PIPE_READMODE_MESSAGE または PIPE_READMODE_BYTEで使用できます。 |
次のいずれかの読み取りモードを指定できます。 同じパイプのインスタンスごとに、異なる読み取りモードを指定できます。
次のいずれかの待機モードを指定できます。 同じパイプのインスタンスごとに、異なる待機モードを指定できます。
| モード | 意味 |
|---|---|
|
ブロック モードが有効になっています。 パイプ ハンドルが |
|
非ブロッキング モードが有効になっています。 このモードでは、ReadFile、 非ブロッキング モードは Microsoft LAN Manager バージョン 2.0 との互換性のためにサポートされており、名前付きパイプで非同期 I/O を実現するために使用しないでください。 非同期パイプ I/O の詳細については、「同期および重複入力と出力のを参照してください。 |
次のいずれかのリモート クライアント モードを指定できます。 同じパイプのインスタンスごとに、異なるリモート クライアント モードを指定できます。
| モード | 意味 |
|---|---|
|
リモート クライアントからの接続を受け入れ、パイプのセキュリティ記述子に対して確認できます。 |
|
リモート クライアントからの接続は自動的に拒否されます。 |
[in] nMaxInstances
このパイプに対して作成できるインスタンスの最大数。 パイプの最初のインスタンスでは、この値を指定できます。パイプの他のインスタンスに対して同じ番号を指定する必要があります。 使用可能な値は、1 ~ PIPE_UNLIMITED_INSTANCES (255) の範囲です。
このパラメーターが PIPE_UNLIMITED_INSTANCESされている場合、作成できるパイプ インスタンスの数は、システム リソースの可用性によってのみ制限されます。
[in] nOutBufferSize
出力バッファー用に予約するバイト数。 名前付きパイプ バッファーのサイズ設定については、次の「解説」セクションを参照してください。
[in] nInBufferSize
入力バッファー用に予約するバイト数。 名前付きパイプ バッファーのサイズ設定については、次の「解説」セクションを参照してください。
[in] nDefaultTimeOut
WaitNamedPipe 関数が NMPWAIT_USE_DEFAULT_WAITを指定する場合の、既定のタイムアウト値 (ミリ秒単位)。 名前付きパイプの各インスタンスは、同じ値を指定する必要があります。
値が 0 の場合、既定のタイムアウトは 50 ミリ秒になります。
[in, optional] lpSecurityAttributes
新しい名前付きパイプのセキュリティ記述子を指定し、子プロセスが返されたハンドルを継承できるかどうかを判断する SECURITY_ATTRIBUTES 構造体へのポインター。 lpSecurityAttributes
戻り値
関数が成功した場合、戻り値は名前付きパイプ インスタンスのサーバー末尾へのハンドルです。
関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE。 拡張エラー情報を取得するには、GetLastError
備考
CreateNamedPipeを使用して名前付きパイプのインスタンス
名前付きパイプのすべてのインスタンスは、同じパイプの種類 (バイト型またはメッセージ型)、パイプ アクセス (双方向、受信、または送信)、インスタンス数、タイムアウト値を指定する必要があります。 異なる値が使用されている場合、この関数は失敗し、GetLastError
クライアント プロセスは、
パイプ サーバーは、パイプ クライアントが起動するまでブロック読み取り操作を実行しないでください。 そうしないと、競合状態が発生する可能性があります。 これは通常、C ランタイムなどの初期化コードで、継承されたハンドルをロックして調べる必要がある場合に発生します。
名前付きパイプが作成されるたびに、システムは非ページ プール (カーネルによって使用される物理メモリ) を使用して受信バッファーまたは送信バッファーを作成します。 作成できるパイプ インスタンス (およびスレッドやプロセスなどのオブジェクト) の数は、使用可能な非ページ プールによって制限されます。 各読み取りまたは書き込み要求には、読み取りまたは書き込みデータ用のバッファー内の領域と、内部データ構造用の追加の領域が必要です。
入力バッファー サイズと出力バッファー サイズはアドバイザリです。 名前付きパイプの各端に予約されている実際のバッファー サイズは、システムの既定値、システムの最小値または最大値、または次の割り当て境界に切り上げられた指定されたサイズのいずれかです。 指定するバッファー サイズは、プロセスが非ページ プールを使い果たさないほど小さく、一般的な要求に対応できるだけの大きさにする必要があります。
パイプ書き込み操作が発生するたびに、システムはまず、パイプ書き込みクォータに対してメモリの充電を試みます。 残りのパイプ書き込みクォータが要求を満たすのに十分な場合、書き込み操作はすぐに完了します。 残りのパイプ書き込みクォータが小さすぎて要求を満たしていない場合、システムは、プロセス用に予約された非ページ プールを使用して、データに対応するようにバッファーを拡張しようとします。 書き込み操作は、追加のバッファー クォータを解放できるように、パイプからデータが読み取られるまでブロックされます。 したがって、指定したバッファー サイズが小さすぎると、システムは必要に応じてバッファーを拡張しますが、欠点は操作がブロックされるということです。 操作が重複している場合、システム スレッドはブロックされます。それ以外の場合、アプリケーション スレッドはブロックされます。
名前付きパイプで使用されるリソースを解放するには、アプリケーションは、必要なくなったときに常にハンドルを閉じる必要があります。これは、CloseHandle 関数を呼び出すか、インスタンス ハンドルに関連付けられているプロセスが終了したときに実行されます。 名前付きパイプのインスタンスには、複数のハンドルが関連付けられている場合があることに注意してください。 名前付きパイプのインスタンスの最後のハンドルが閉じられると、名前付きパイプのインスタンスは常に削除されます。
Windows 10 バージョン 1709: パイプは、アプリ コンテナー内でのみサポートされます。つまり、1 つの UWP プロセスから、同じアプリの一部である別の UWP プロセスまでです。 また、名前付きパイプでは、パイプ名の構文 \\.\pipe\LOCAL\ を使用する必要があります。
例
例については、「マルチスレッド パイプ サーバー
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされる最小サーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | winbase.h (Windows.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
ConnectNamedPipe の
CreateFile の
パイプ関数 を
ReadFile の
ReadFileEx の
TransactNamedPipe の
WaitNamedPipe の
WriteFile の
WriteFileEx の