ConnectNamedPipe 関数 (namedpipeapi.h)
名前付きパイプ サーバー プロセスが、名前付きパイプのインスタンスに接続するクライアント プロセスを待機できるようにします。 クライアント プロセスは、 CreateFile 関数または CallNamedPipe 関数を呼び出して接続します。
構文
BOOL ConnectNamedPipe(
[in] HANDLE hNamedPipe,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
パラメーター
[in] hNamedPipe
名前付きパイプ インスタンスのサーバー側へのハンドル。 このハンドルは、 CreateNamedPipe 関数によって返されます。
[in, out, optional] lpOverlapped
OVERLAPPED 構造体へのポインター。
hNamedPipe が FILE_FLAG_OVERLAPPED で開かれた場合、lpOverlapped パラメーターは NULL にすることはできません。 有効な OVERLAPPED 構造体を指す必要があります。 hNamedPipe が FILE_FLAG_OVERLAPPED で開き、lpOverlapped が NULL の場合、関数は接続操作が完了したことを誤って報告する可能性があります。
hNamedPipe が FILE_FLAG_OVERLAPPED で作成され、lpOverlapped が NULL でない場合、OVERLAPPED 構造体には、手動リセット イベント オブジェクト (CreateEvent 関数を使用してサーバーが作成できる) へのハンドルが含まれている必要があります。
hNamedPipe が FILE_FLAG_OVERLAPPED で開かれない場合、クライアントが接続されるかエラーが発生するまで関数は戻りません。 同期操作が成功すると、関数が呼び出された後にクライアントが接続した場合、関数は 0 以外の値を返します。
戻り値
操作が同期の場合、 ConnectNamedPipe は操作が完了するまで戻りません。 関数が成功すると、戻り値は 0 以外になります。 関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
操作が非同期の場合、 ConnectNamedPipe は直ちにを返します。 操作がまだ保留中の場合、戻り値は 0 で、 GetLastError はERROR_IO_PENDINGを返します。 ( HasOverlappedIoCompleted マクロを使用して、操作がいつ完了したかを確認できます)。関数が失敗した場合、戻り値は 0 で、 GetLastError は ERROR_IO_PENDINGまたはERROR_PIPE_CONNECTED以外の値を返します。
関数が呼び出される前にクライアントが接続すると、関数は 0 を返し、 GetLastError は ERROR_PIPE_CONNECTEDを返します。 これは、クライアントが CreateNamedPipe の呼び出しと ConnectNamedPipe の呼び出しの間の間隔で接続した場合に発生する可能性があります。 この状況では、関数から 0 が返される場合でも、クライアントとサーバーの間に適切な接続があります。
注釈
名前付きパイプ サーバー プロセスでは、新しく作成されたパイプ インスタンスで ConnectNamedPipe を使用できます。 また、以前に別のクライアント プロセスに接続されていたインスタンスと共に使用することもできます。この場合、サーバー プロセスは、ハンドルを新しいクライアントに再接続する前に、最初に DisconnectNamedPipe 関数を呼び出して前のクライアントからハンドルを切断する必要があります。 それ以外の場合、 ConnectNamedPipe は 0 を返し、 GetLastError は、前のクライアントがハンドルを閉じた場合はERROR_NO_DATA、ハンドルを閉じていない場合はERROR_PIPE_CONNECTEDを返します。
ConnectNamedPipe の動作は、パイプ ハンドルの待機モードがブロッキングモードに設定されているか非ブロッキングに設定されているか、および関数が同期的に実行されるように設定されているか、重複モードで実行されるように設定されているかの 2 つの条件によって異なります。 サーバーは、最初に CreateNamedPipe 関数でパイプ ハンドルの待機モードを指定し、 SetNamedPipeHandleState 関数を使用して変更できます。
サーバー プロセスでは、任意の 待機関数 または SleepEx を使用して、イベント オブジェクトの状態が通知されるタイミングを判断し、 HasOverlappedIoCompleted マクロを使用して ConnectNamedPipe 操作がいつ完了するかを判断できます。
指定したパイプ ハンドルが非ブロッキング モードの場合、 ConnectNamedPipe は常に直ちにを返します。 非ブロッキング モードでは、 ConnectNamedPipe は、前のクライアントから切断されたパイプ インスタンスに対して初めて呼び出されるときに、0 以外の値を返します。 これは、パイプが新しいクライアント プロセスに接続できるようになったことを示します。 パイプ ハンドルが非ブロッキング モードの場合、他のすべての状況では、 ConnectNamedPipe は 0 を返します。 このような状況では、 GetLastError は、クライアントが接続されていない場合はERROR_PIPE_LISTENINGを返し、クライアントが接続されている場合はERROR_PIPE_CONNECTEDし、前のクライアントがパイプ ハンドルを閉じてもサーバーが切断されていない場合はERROR_NO_DATAします。 クライアントとサーバー間の良好な接続は、ERROR_PIPE_CONNECTED エラーが発生した後にのみ存在します。
例
例については、「 マルチスレッド パイプ サーバー」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | namedpipeapi.h |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |