ConnectNamedPipe

名前付きパイプサーバープロセスがクライアントプロセスからの名前付きパイプインスタンスへの接続を待機できるようにする。

ConnectNamedPipe hNamedPipe, lpOverlapped

hNamedPipe : [intptr] 名前付きパイプインスタンスのサーバー側へのハンドル。このハンドルは CreateNamedPipe 関数が返す。
lpOverlapped : [var] OVERLAPPED 構造体へのポインタ。

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

解説

名前付きパイプサーバープロセスがクライアントプロセスからの名前付きパイプインスタンスへの接続を待機できるようにする。

[戻り値]
操作が同期の場合、ConnectNamedPipe
は操作が完了するまで戻らない。関数が成功した場合、戻り値はゼロ以外。関数が失敗した場合、戻り値はゼロ。拡張エラー情報を取得するには
GetLastError を呼ぶ。操作が非同期の場合、ConnectNamedPipe
は直ちに戻る。操作がまだ保留中の場合、戻り値はゼロで GetLastError は ERROR_IO_PENDING
を返す（HasOverlappedIoCompleted マクロを使って操作完了を判定できる）。関数が失敗した場合、戻り値はゼロで
GetLastError は ERROR_IO_PENDING または ERROR_PIPE_CONNECTED
以外の値を返す。関数呼び出し前にクライアントが接続した場合、関数はゼロを返し GetLastError は
ERROR_PIPE_CONNECTED を返す。これは CreateNamedPipe の呼び出しと ConnectNamedPipe
の呼び出しの間にクライアントが接続した場合に発生する。この状況では関数がゼロを返すもののクライアントとサーバー間の接続は正常に確立されている。

[備考]
名前付きパイプサーバープロセスは新しく作成したパイプインスタンスに対して ConnectNamedPipe
を使用できる。以前に別のクライアントプロセスに接続されていたインスタンスでも使用できる。この場合、ハンドルを新しいクライアントに再接続する前に、サーバープロセスはまず
DisconnectNamedPipe
関数を呼んで前のクライアントからハンドルを切断しなければならない。そうしないと、前のクライアントがハンドルを閉じていれば
ConnectNamedPipe はゼロを返し GetLastError は ERROR_NO_DATA
を返す。ハンドルを閉じていなければ ERROR_PIPE_CONNECTED を返す。ConnectNamedPipe の動作は 2
つの条件に依存する:
パイプハンドルの待機モードがブロッキングかノンブロッキングか、関数が同期実行かオーバーラップモードかである。サーバーは
CreateNamedPipe でパイプハンドルの待機モードを最初に指定し、SetNamedPipeHandleState
で変更できる。サーバープロセスは任意の待機関数や SleepEx
を使ってイベントオブジェクトがシグナル状態になったかを判定し、HasOverlappedIoCompleted マクロで
ConnectNamedPipe
操作の完了を判定できる。指定パイプハンドルがノンブロッキングモードの場合、ConnectNamedPipe
は常に直ちに戻る。ノンブロッキングモードでは、前のクライアントから切断されたパイプインスタンスに対する初回呼び出しでゼロ以外を返す。これはパイプが新しいクライアントプロセスに接続可能になったことを示す。ノンブロッキングモードでの他の状況ではすべて
ConnectNamedPipe はゼロを返す。これらの状況で GetLastError は、クライアントが接続されていない場合は
ERROR_PIPE_LISTENING、接続されている場合は
ERROR_PIPE_CONNECTED、前のクライアントがハンドルを閉じたがサーバーが切断していない場合は ERROR_NO_DATA
を返す。なお、ERROR_PIPE_CONNECTED エラーを受け取った後にのみクライアントとサーバー間の正常な接続が存在する。注意:
ノンブロッキングモードは Microsoft LAN Manager バージョン 2.0
との互換性のためにサポートされており、名前付きパイプで非同期入出力を実現するために使うべきではない。Windows 10 バージョン
1709: パイプは app-container 内でのみサポートされ、つまり同じアプリの UWP
プロセス間でしか使えない。また、名前付きパイプはパイプ名に `\\.\pipe\LOCAL\` 構文を使う必要がある。

サンプル逆引き (1)

情報