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
名前の pipename 部分には、円記号以外の文字 (数字や特殊文字を含む) を含めることができます。 パイプ名の文字列全体の長は最大 256 文字です。 パイプ名では大文字と小文字は区別されません。
[in] dwOpenMode
開いているモード。
dwOpenMode で 0 以外の値または次の表に示すフラグが指定されている場合、関数は失敗します。
このパラメーターは、次のいずれかのパイプ アクセス モードを指定する必要があります。 パイプのインスタンスごとに同じモードを指定する必要があります。
| モード | 意味 |
|---|---|
|
パイプは双方向です。サーバー プロセスとクライアント プロセスの両方で、パイプとの間で読み取りと書き込みを行うことができます。 このモードにより、サーバーは 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 つ以上含めることもできます。 これらのモードは、同じパイプのインスタンスごとに異なる場合があります。
| モード | 意味 |
|---|---|
|
このフラグを使用してパイプの複数のインスタンスを作成しようとすると、最初のインスタンスの作成は成功しますが、次のインスタンスの作成は ERROR_ACCESS_DENIEDで失敗します。 |
|
ライトスルー モードが有効になっています。 このモードは、バイト型パイプに対する書き込み操作にのみ影響し、クライアントプロセスとサーバープロセスが異なるコンピュータ上にある場合にのみ影響します。 このモードが有効になっている場合、名前付きパイプに書き込む関数は、書き込まれたデータがネットワーク経由で送信され、リモート コンピューター上のパイプのバッファーに格納されるまで、戻りません。 このモードが有効になっていない場合、システムは、最小バイト数が累積されるまで、または最大時間が経過するまでデータをバッファリングすることで、ネットワーク操作の効率を向上させます。 |
|
重複モードが有効になっています。 このモードが有効になっている場合、完了するまでにかなりの時間がかかる可能性がある読み取り、書き込み、接続操作を実行する関数は、すぐに戻ることができます。 このモードでは、時間のかかる操作がバックグラウンドで実行されている間に、操作を開始したスレッドが他の操作を実行できるようになります。 たとえば、重複モードでは、スレッドはパイプの複数のインスタンスで同時入出力 (I/O) 操作を処理したり、同じパイプ ハンドルに対して同時に読み取りと書き込み操作を実行したりできます。 重複モードが有効になっていない場合、パイプ ハンドルに対して読み取り、書き込み、接続操作を実行する関数は、操作が完了するまで戻りません。 ReadFileEx 関数と WriteFileEx 関数は、パイプ ハンドルと重複モードでのみ使用できます。 ReadFile、WriteFile、ConnectNamedPipe、TransactNamedPipe 関数は、同期的または重複した操作として実行できます。 |
このパラメーターには、次のセキュリティ アクセス モードの任意の組み合わせを含めることができます。 これらのモードは、同じパイプのインスタンスごとに異なる場合があります。
| モード | 意味 |
|---|---|
|
呼び出し元は、名前付きパイプの随意アクセス制御リスト (ACL) への書き込みアクセス権を持ちます。 |
|
呼び出し元は、名前付きパイプの所有者への書き込みアクセス権を持ちます。 |
|
呼び出し元は、名前付きパイプの SACL への書き込みアクセス権を持ちます。 詳細については、「Access-Control Lists (ACL)」および「SACL Access Right」を参照してください。 |
[in] dwPipeMode
パイプ モード。
dwPipeMode で 0 以外の値または次の表に示すフラグが指定されている場合、関数は失敗します。
次のいずれかの型モードを指定できます。 パイプのインスタンスごとに同じ型モードを指定する必要があります。
| モード | 意味 |
|---|---|
|
データは、バイトストリームとしてパイプに書き込まれます。 このモードは、PIPE_READMODE_MESSAGEでは使用できません。 パイプは、異なる書き込み操作中に書き込まれたバイトを区別しません。 |
|
データは、メッセージのストリームとしてパイプに書き込まれます。 パイプは、各書き込み操作中に書き込まれたバイトをメッセージ単位として扱います。 GetLastError 関数は、メッセージが完全に読み取られない場合にERROR_MORE_DATAを返します。 このモードは、 PIPE_READMODE_MESSAGE または PIPE_READMODE_BYTEのいずれかで使用できます。 |
次のいずれかの読み取りモードを指定できます。 同じパイプのインスタンスごとに、異なる読み取りモードを指定できます。
次のいずれかの待機モードを指定できます。 同じパイプのインスタンスごとに、異なる待機モードを指定できます。
| モード | 意味 |
|---|---|
|
ブロッキング モードが有効になっています。 パイプ ハンドルが ReadFile、 WriteFile、または ConnectNamedPipe 関数で指定されている場合、読み取るデータ、すべてのデータが書き込まれる、またはクライアントが接続されるまで、操作は完了しません。 このモードを使用すると、クライアント プロセスがアクションを実行するまで無期限に待機する場合があります。 |
|
非ブロッキング モードが有効になっています。 このモードでは、 ReadFile、 WriteFile、 ConnectNamedPipe は常にすぐに返されます。
非ブロッキング モードは Microsoft LAN Manager バージョン 2.0 との互換性のためにサポートされており、名前付きパイプを使用して非同期 I/O を実現するために使用しないでください。 非同期パイプ I/O の詳細については、「 同期入力と重複入力と出力」を参照してください。 |
次のいずれかのリモート クライアント モードを指定できます。 同じパイプのインスタンスごとに、異なるリモート クライアント モードを指定できます。
| モード | 意味 |
|---|---|
|
リモート クライアントからのConnectionsを受け入れ、パイプのセキュリティ記述子に対して確認できます。 |
|
リモート クライアントからのConnectionsは自動的に拒否されます。 |
[in] nMaxInstances
このパイプに対して作成できるインスタンスの最大数。 パイプの最初のインスタンスでは、この値を指定できます。パイプの他のインスタンスには、同じ番号を指定する必要があります。 使用できる値は、1 ~ PIPE_UNLIMITED_INSTANCES (255) の範囲です。
このパラメーターが PIPE_UNLIMITED_INSTANCESの場合、作成できるパイプ インスタンスの数は、システム リソースの可用性によってのみ制限されます。 nMaxInstances がPIPE_UNLIMITED_INSTANCESより大きい場合、戻り値はINVALID_HANDLE_VALUEされ、GetLastError はERROR_INVALID_PARAMETERを返します。
[in] nOutBufferSize
出力バッファー用に予約するバイト数。 名前付きパイプ バッファーのサイズ設定については、次の「解説」セクションを参照してください。
[in] nInBufferSize
入力バッファー用に予約するバイト数。 名前付きパイプ バッファーのサイズ設定については、次の「解説」セクションを参照してください。
[in] nDefaultTimeOut
WaitNamedPipe 関数でNMPWAIT_USE_DEFAULT_WAITが指定されている場合の既定のタイムアウト値 (ミリ秒単位)。 名前付きパイプの各インスタンスは、同じ値を指定する必要があります。
値が 0 の場合、既定のタイムアウトは 50 ミリ秒になります。
[in, optional] lpSecurityAttributes
新しい名前付きパイプのセキュリティ記述子を指定し、子プロセスが返されたハンドルを継承できるかどうかを決定する、 SECURITY_ATTRIBUTES 構造体へのポインター。 lpSecurityAttributes が NULL の場合、名前付きパイプは既定のセキュリティ記述子を取得し、ハンドルを継承できません。 名前付きパイプの既定のセキュリティ記述子の ACL は、LocalSystem アカウント、管理者、作成者所有者にフル コントロールを付与します。 また、Everyone グループと匿名アカウントのメンバーに読み取りアクセス権を付与します。
戻り値
関数が成功した場合、戻り値は名前付きパイプ インスタンスのサーバー側へのハンドルです。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
CreateNamedPipe を使用して名前付きパイプのインスタンスを作成するには、ユーザーが名前付きパイプ オブジェクトにFILE_CREATE_PIPE_INSTANCEアクセスできる必要があります。 新しい名前付きパイプを作成する場合は、セキュリティ属性パラメーターのアクセス制御リスト (ACL) によって、名前付きパイプの随意アクセス制御が定義されます。
名前付きパイプのすべてのインスタンスは、同じパイプの種類 (バイト型またはメッセージ型)、パイプ アクセス (双方向、受信、または送信)、インスタンス数、およびタイムアウト値を指定する必要があります。 異なる値が使用されている場合、この関数は失敗し、GetLastError はERROR_ACCESS_DENIEDを返します。
クライアント プロセスは、 CreateFile または CallNamedPipe 関数を使用して名前付きパイプに接続します。 サーバー側がメッセージ モードの場合でも、名前付きパイプのクライアント側はバイト モードで開始されます。 データの受信に関する問題を回避するには、クライアント側もメッセージ モードに設定します。 パイプのモードを変更するには、パイプ クライアントが読み取り専用パイプを開き、 GENERIC_READ して アクセスFILE_WRITE_ATTRIBUTES 必要があります。
パイプ サーバーは、パイプ クライアントが起動するまでブロック読み取り操作を実行しないでください。 そうしないと、競合状態が発生する可能性があります。 これは通常、C ランタイムなどの初期化コードで、継承されたハンドルをロックして調べる必要がある場合に発生します。
名前付きパイプが作成されるたびに、システムは非ページ プール (カーネルによって使用される物理メモリ) を使用して受信バッファーまたは送信バッファーを作成します。 作成できるパイプ インスタンス (およびスレッドやプロセスなどのオブジェクト) の数は、使用可能な非ページ プールによって制限されます。 各読み取りまたは書き込み要求には、読み取りまたは書き込みデータ用のバッファー内の領域と、内部データ構造用の追加の領域が必要です。
入出力バッファー・サイズはアドバイザリです。 名前付きパイプの各端に予約されている実際のバッファー サイズは、システムの既定値、システムの最小または最大、または指定されたサイズが次の割り当て境界に切り上げられます。 指定するバッファー サイズは、プロセスが非ページ プールを使い果たさないほど小さく、一般的な要求に対応するのに十分な大きさにする必要があります。
パイプ書き込み操作が発生するたびに、システムは最初にパイプ書き込みクォータに対してメモリの充電を試みます。 残りのパイプ書き込みクォータが要求を満たすのに十分な場合、書き込み操作はすぐに完了します。 残りのパイプ書き込みクォータが小さすぎて要求を満たせない場合、システムはバッファーを拡張して、プロセス用に予約されている非ページ プールを使用してデータに対応しようとします。 書き込み操作は、追加のバッファー クォータを解放できるように、パイプからデータが読み取られるまでブロックされます。 したがって、指定したバッファー サイズが小さすぎる場合、システムは必要に応じてバッファーを拡張しますが、欠点は操作がブロックされるということです。 操作が重複している場合、システム スレッドはブロックされます。それ以外の場合、アプリケーション スレッドはブロックされます。
名前付きパイプで使用されるリソースを解放するには、アプリケーションはハンドルが不要になったときに常にハンドルを閉じる必要があります。これは、 CloseHandle 関数を呼び出すか、インスタンス ハンドルに関連付けられているプロセスが終了したときに実行されます。 名前付きパイプのインスタンスには、複数のハンドルが関連付けられている場合があることに注意してください。 名前付きパイプのインスタンスは、名前付きパイプのインスタンスへの最後のハンドルが閉じられると、常に削除されます。
Windows 10バージョン 1709: パイプは、アプリ コンテナー内でのみサポートされます。つまり、1 つの UWP プロセスから、同じアプリの一部である別の UWP プロセスまでです。 また、名前付きパイプでは、パイプ名の構文 \\.\pipe\LOCAL\ を使用する必要があります。
例
例については、「 マルチスレッド パイプ サーバー」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |