CreateNamedPipeW

CreateNamedPipeW (Unicode) 関数 (winbase.h) は名前付きパイプのインスタンスを作成し、後続のパイプ操作に使えるハンドルを返す。

CreateNamedPipeW lpName, dwOpenMode, dwPipeMode, nMaxInstances, nOutBufferSize, nInBufferSize, nDefaultTimeOut, lpSecurityAttributes

lpName : [wstr] 一意のパイプ名。この文字列は次の形式でなければならない: \\\\.\\pipe\pipename。名前の pipename 部分にはバックスラッシュ以外の任意の文字（数字や特殊文字を含む）を含められる。パイプ名文字列全体の長さは 256 文字までで、パイプ名は大文字小文字を区別しない。
dwOpenMode : [int] オープンモード。dwOpenMode に以下の表にあるフラグまたは 0 以外を指定した場合、関数は失敗する。このパラメータは以下のパイプアクセスモードのいずれかを指定する必要がある。パイプの各インスタンスに同じモードを指定しなければならない。
dwPipeMode : [int] パイプモード。dwPipeMode に以下の表にあるフラグまたは 0 以外を指定した場合、関数は失敗する。以下のタイプモードのいずれかを指定できる。パイプの各インスタンスに同じタイプモードを指定しなければならない。
nMaxInstances : [int] このパイプに対して作成できるインスタンスの最大数。パイプの最初のインスタンスがこの値を指定する。パイプの他のインスタンスには同じ数を指定しなければならない。許容値は 1 から PIPE_UNLIMITED_INSTANCES (255) の範囲。PIPE_UNLIMITED_INSTANCES の場合、作成可能なパイプインスタンス数はシステムリソースの可用性によってのみ制限される。nMaxInstances が PIPE_UNLIMITED_INSTANCES より大きい場合、戻り値は INVALID_HANDLE_VALUE で GetLastError は ERROR_INVALID_PARAMETER を返す。
nOutBufferSize : [int] 出力バッファに予約するバイト数。名前付きパイプバッファのサイズに関する議論は以下の備考を参照。
nInBufferSize : [int] 入力バッファに予約するバイト数。名前付きパイプバッファのサイズに関する議論は以下の備考を参照。
nDefaultTimeOut : [int] WaitNamedPipe 関数が NMPWAIT_USE_DEFAULT_WAIT を指定したときの既定のタイムアウト値（ミリ秒単位）。名前付きパイプの各インスタンスは同じ値を指定しなければならない。値ゼロは 50 ミリ秒の既定タイムアウトとなる。
lpSecurityAttributes : [var] 新しい名前付きパイプのセキュリティ記述子を指定し、返されるハンドルを子プロセスが継承できるかを決定する SECURITY_ATTRIBUTES 構造体へのポインタ。lpSecurityAttributes が NULL の場合、名前付きパイプは既定のセキュリティ記述子を取得し、ハンドルは継承できない。名前付きパイプの既定セキュリティ記述子の ACL は LocalSystem アカウント、管理者、作成者所有者にフルコントロールを、Everyone グループと匿名アカウントに読み取りアクセスを付与する。

(プラグイン / モジュール : kernel32.dll)

解説

CreateNamedPipeW (Unicode) 関数 (winbase.h)
は名前付きパイプのインスタンスを作成し、後続のパイプ操作に使えるハンドルを返す。

[戻り値]
関数が成功した場合、戻り値は名前付きパイプインスタンスのサーバー側へのハンドル。関数が失敗した場合、戻り値は
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: パイプは app-container 内でのみサポートされ、つまり同じアプリの UWP
プロセス間でしか使えない。また、名前付きパイプはパイプ名に `\\.\pipe\LOCAL\` 構文を使う必要がある。

サンプル逆引き (1)

情報