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 以外の値または次の表に示すフラグが指定されている場合、関数は失敗します。

このパラメーターは、次のいずれかのパイプ アクセス モードを指定する必要があります。 パイプのインスタンスごとに同じモードを指定する必要があります。

このパラメーターには、書き込みモードと重複モードを有効にする次のフラグを 1 つ以上含めることもできます。 これらのモードは、同じパイプのインスタンスごとに異なる場合があります。

このパラメーターには、次のセキュリティ アクセス モードの任意の組み合わせを含めることができます。 これらのモードは、同じパイプのインスタンスごとに異なる場合があります。

[in] dwPipeMode

パイプ モード。

dwPipeMode で 0 以外の値または次の表に示すフラグが指定されている場合、関数は失敗します。

次のいずれかの型モードを指定できます。 パイプのインスタンスごとに同じ型モードを指定する必要があります。

次のいずれかの読み取りモードを指定できます。 同じパイプのインスタンスごとに、異なる読み取りモードを指定できます。

次のいずれかの待機モードを指定できます。 同じパイプのインスタンスごとに、異なる待機モードを指定できます。

次のいずれかのリモート クライアント モードを指定できます。 同じパイプのインスタンスごとに、異なるリモート クライアント モードを指定できます。

[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\ を使用する必要があります。

例

例については、「 マルチスレッド パイプ サーバー」を参照してください。

要件

関連項目

ConnectNamedPipe

CreateFile

パイプ関数

パイプの概要

ReadFile

ReadFileEx

SECURITY_ATTRIBUTES

TransactNamedPipe

WaitNamedPipe

WriteFile

WriteFileEx